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

package/src/runtime.ts

@@ -25,11 +25,15 @@ 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 { compositeEventIdentity, eventEntityFromRecords, type EventEntity, type EventSourceRecord } from './events.js'
+import { compositeEventIdentity, eventEntityFromRecords, stripEventReferenceSection, 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'
-import { applyTrialAxisResolution, normalizeKnowledge, runWikiTrial, trialSummary, type AxisPromptBlock, type TrialAxisSet, type TrialAxisSetResolution } from './wiki-trial.js'
+import { applyTrialAxisResolution, cardNameFor, normalizeKnowledge, runWikiTrial, trialSummary, type AxisPromptBlock, type TrialAxisSet, type TrialAxisSetResolution } from './wiki-trial.js'
+import { EXTRACTION_CONTRACT_VERSION } from './extract-table.js'
+import { KnowledgePipeline, type PipelineContext, type PipelineSource } from './pipeline/engine.js'
+import { PipelineStore, type ExtractionCheckpoint } from './pipeline/store.js'
+import type { MaterializationGroup, PipelineStatus } from './pipeline/types.js'
 import { candidatesFromReport, coordinateIdsOf, coordinateIsEmpty, type MaterializedCard } from './wiki-materialize.js'
 import {
   buildOrganizePrompt, buildOrganizeSystem, checkOrganize, citationsFrom, layoutHash, layoutOf,
@@ -657,6 +661,8 @@ export interface ImportFailure {
  * 而这里要回答的是「刚才那一下让库里多了什么」。
  */
 export interface ImportCompileReport {
+  taskId?: string
+  state?: import('./pipeline/types.js').PipelineState
   cardsCreated: number
   cardsUpdated: number
   cardsReused?: number
@@ -1046,38 +1052,6 @@ function appendExtracted(existing: string, additions: string[]): string {
   return content
 }
 
-/** 坐标 WikiCard 的事件摘要段由 Event 引用派生；全文与时间线留在独立 Event 实体。 */
-function withEventReferences(
-  content: string,
-  rawRefs: unknown,
-  eventsById: ReadonlyMap<string, EventEntity>,
-): string {
-  let refs: string[] = []
-  if (Array.isArray(rawRefs)) refs = rawRefs.filter((item): item is string => typeof item === 'string')
-  else if (typeof rawRefs === 'string') {
-    try {
-      const parsed: unknown = JSON.parse(rawRefs)
-      if (Array.isArray(parsed)) refs = parsed.filter((item): item is string => typeof item === 'string')
-    } catch { /* 无效引用会作为空列表处理 */ }
-  }
-  const lines = content.split('\n')
-  const start = lines.findIndex(line => line.trim() === '## 关联 Event')
-  if (start >= 0) {
-    let end = start + 1
-    while (end < lines.length && !/^#{1,2}\s+/.test(lines[end] ?? '')) end += 1
-    lines.splice(start, end - start)
-  }
-  const base = lines.join('\n').trimEnd()
-  const entries = [...new Set(refs)].map(id => eventsById.get(id)).filter((event): event is EventEntity => event !== undefined)
-  if (entries.length === 0) return base
-  const bullets = entries.map(event => {
-    const occurredAt = event.occurredAt ? ` · ${event.occurredAt}` : ''
-    const summary = event.summary.trim() ? `：${event.summary.trim()}` : ''
-    return `- **${event.title}**${occurredAt}${summary}（${event.id}）`
-  })
-  return `${base ? `${base}\n\n` : ''}## 关联 Event\n\n${bullets.join('\n')}`
-}
-
 /** 把 `incoming` 按小节折进 `existing`；结构对不上时整段追加。 */
 function foldBody(existing: string, incoming: string): string {
   if (!existing) return incoming
@@ -1355,9 +1329,10 @@ function markdownImageRefs(content: string): string[] {
  *    `tags` / `generated` / `sources`。它们是真 YAML 键，人能读、`grep` 得到、
  *    外部工具能按公开规范读走。`generated.at` 就是**采集时间**（OKF 里没有「抓取
  *    时间」这个概念，本文件何时被谁写出来就是它）。
- * 2. **我们自己的运行键**：`source_id` / `external_id` / `created_at` / `updated_at` /
- *    `metadata` / `lineage`。OKF 明确允许自定义键，且要求消费者不得因为未知键拒收，
- *    所以这两类可以同处一个 front matter。
+ * 2. **我们自己的运行键**：`created_at` / `updated_at` / `metadata` / `lineage`。
+ *    来源身份保存在 SQLite 的 `entity_id` / `external_id` 列，不在 front matter 重复一份。
+ *    OKF 明确允许自定义键，且要求消费者不得因为未知键拒收，所以运行元数据可以同处
+ *    一个 front matter。
  *
  * `metadata` 只剩**类型专属的扩展键**（转换任务 id、内容哈希、资产清单、格式…）：
  * 那些东西 OKF 没有对应概念，但也不该混进上面那组公开字段里。
@@ -1386,8 +1361,6 @@ function sourceFrontMatter(record: SourceRaw, provenance?: SourceProvenance): Re
       ...(origin.lastModified?.trim() ? { last_modified: origin.lastModified.trim() } : {}),
     }))
   }
-  frontMatter.source_id = record.sourceId
-  frontMatter.external_id = record.externalId ?? ''
   frontMatter.created_at = record.createdAt
   frontMatter.updated_at = record.updatedAt
   frontMatter.metadata = record.metadata
@@ -1776,7 +1749,7 @@ function resolveConfiguredPython(configured: string | undefined, resourcePython:
 
 export interface KnowledgeRuntimeOptions {
   /** Production deployment requires a working Python + embedding + rerank stack. */
-  environmentGuard?: () => Promise<void>
+  environmentGuard?: (kind?: 'embedding' | 'rerank') => Promise<void>
   /**
    * 这一库的「坐标提取备注」（0068），人写的。
    *
@@ -2000,7 +1973,7 @@ function blankProgress(
 }
 
 export class KnowledgeRuntime {
-  private readonly environmentGuard?: () => Promise<void>
+  private readonly environmentGuard?: (kind?: 'embedding' | 'rerank') => Promise<void>
   /** 当前生效的配置。volatile 改动会就地合并进来（见 `updateConfig`），所以它不是只读的。 */
   config: RuntimeKnowledgeConfig
   readonly rootDir: string
@@ -2055,6 +2028,9 @@ export class KnowledgeRuntime {
   /** 抽取轨迹（`<memoryDir>/extraction-runs.sqlite`）。同一个懒打开的理由。 */
   private extractionRunsStore: ExtractionRunStore | null = null
   private extractionRunsReady: boolean | null = null
+  private closed = false
+  private pipelineEngine?: KnowledgePipeline
+  private pipelineOpening?: Promise<KnowledgePipeline>
   /** 轴注册表（`<memoryDir>/knowledge.sqlite`）。与抽取轨迹同一个懒打开的理由。 */
   private axesStore: AxisRegistry | null = null
   private axesReady: boolean | null = null
@@ -2803,12 +2779,20 @@ export class KnowledgeRuntime {
   }
 
   close(): void {
+    if (this.closed) return
+    this.closed = true
+    this.pipelineEngine?.close()
     for (const task of this.compileTasks.values()) {
       if (['succeeded', 'failed', 'cancelled'].includes(task.progress.state)) continue
       task.cancelRequested = true
       task.pauseRequested = false
       task.resume?.()
     }
+    if (this.compilePending > 0) { void this.compileTail.finally(() => this.closeStores()); return }
+    this.closeStores()
+  }
+
+  private closeStores(): void {
     this.embeddingWorker?.close()
     this.embeddingWorker = null
     this.rerankWorker?.close()
@@ -3198,34 +3182,23 @@ export class KnowledgeRuntime {
         failed[0] ? `第一份的原因：${failed[0].message}` : undefined)
     }
 
-    /**
-     * 编译。**只要有一份写成就编**：成功的那几份已经是库里的知识，
-     * 「因为同批里有一份失败就不编」等于把已经进来的知识又挡在门外一次。
-     */
     let compile: ImportCompileReport | null = null
-    if (input.compile !== false) {
-      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 {
-        const data = rebuilt.data
+    if (input.compile === true) {
+      try {
+        const before = new Map((await this.loadCards()).map(card => [card.entityId, this.cardHashOf(card)]))
+        const pipeline = await this.pipeline()
+        const task = await pipeline.start('all', { sourceIds: written.map(source => source.sourceId) }).completion
+        const after = await this.loadCards()
         compile = {
-          cardsCreated: data.cardsCreated,
-          cardsUpdated: data.cardsUpdated,
-          cardsReused: data.cardsReused,
-          notesReused: data.notesReused,
-          notesRecompiled: data.notesRecompiled,
-          sourcesExtracted: data.sourcesExtracted,
-          sourcesSkipped: data.sourcesSkipped,
-          cardsRemoved: data.cardsRemoved,
-          embedding: data.embedding,
-          version: data.version,
+          taskId: task.id, state: task.state,
+          cardsCreated: after.filter(card => !before.has(card.entityId)).length,
+          cardsUpdated: after.filter(card => before.has(card.entityId) && before.get(card.entityId) !== this.cardHashOf(card)).length,
+          sourcesExtracted: Math.max(0, (task.results?.extract?.done ?? 0) - (task.results?.extract?.reused ?? 0) - (task.results?.extract?.failed ?? 0)),
+          sourcesSkipped: task.results?.extract?.reused ?? 0,
         }
-        warnings.push(...(rebuilt.warnings ?? []))
-      }
+        warnings.push(...task.warnings)
+        if (task.state !== 'succeeded') warnings.push(`来源已保存；全链路未完成：${task.summary}。可在知识处理页面继续。`)
+      } catch (cause) { warnings.push(`来源已保存；知识处理未完成：${cause instanceof Error ? cause.message : String(cause)}`) }
     }
 
     return success({ written, failed, attempted: items.length, compile }, warnings)
@@ -4329,6 +4302,7 @@ export class KnowledgeRuntime {
    * 提示词与真编译发出去的那一份必须是**同一份**，否则预览这件事本身没有意义。
    */
   private async organizeContext(input: {
+    knowledge?: Knowledge[]
     cardTitle: string
     coordinate: CardCoordinate
     profileId: string
@@ -4353,10 +4327,11 @@ export class KnowledgeRuntime {
     const store = await this.knowledgeStore()
     if (store === null) return { ok: false, reason: '知识库不可用，这次没有组织卡片（正文退回确定性布局）' }
 
-    const listed = await store.list({
+    const listed = input.knowledge ? { knowledge: input.knowledge, total: input.knowledge.length } : await store.list({
       objectId: input.coordinate.objectId,
       actionId: input.coordinate.actionId,
       sceneId: input.coordinate.sceneId,
+      excludeWithdrawn: true,
       limit: MAX_ORGANIZE_KNOWLEDGE,
     })
     if (listed.knowledge.length === 0) {
@@ -4540,7 +4515,8 @@ export class KnowledgeRuntime {
     if (call === undefined) return failure({ card, warnings: [] }, 'MODEL_UNAVAILABLE', '当前没有可用的模型，无法重新组织这张卡片', true, '检查模型配置后再试。')
 
     const profile = this.organizeProfile()
-    const related = await this.relatedForCard(card)
+    const organizationCard = { ...card, content: stripEventReferenceSection(card.content) }
+    const related = await this.relatedForCard(organizationCard)
     const images = await this.imagesForCard(card)
     const organized = await this.organizeCard({
       cardTitle: card.title,
@@ -4551,7 +4527,7 @@ export class KnowledgeRuntime {
       ...(profile === undefined ? {} : { requiredSections: profile.sections.filter(section => section.required).map(section => section.label) }),
       ...(related.related === undefined ? {} : { related: related.related }),
       ...(images.images.length === 0 ? {} : { images: images.images }),
-      existing: card,
+      existing: organizationCard,
       call,
     })
     if (organized.kind !== 'applied') {
@@ -4563,7 +4539,7 @@ export class KnowledgeRuntime {
       entityType: card.entityType,
       entityId: card.entityId,
       title: organized.title,
-      content: organized.content,
+      content: stripEventReferenceSection(organized.content),
       sourceRefs: card.sourceRefs,
       summary: organized.summary,
       status: card.status,
@@ -4645,6 +4621,7 @@ export class KnowledgeRuntime {
   }
 
   private async organizeCard(input: {
+    knowledge?: Knowledge[]
     cardTitle: string
     coordinate: CardCoordinate
     profileId: string
@@ -4670,6 +4647,7 @@ export class KnowledgeRuntime {
     | { kind: 'skipped'; warnings: string[] }
   > {
     const context = await this.organizeContext({
+      knowledge: input.knowledge,
       cardTitle: input.cardTitle,
       coordinate: input.coordinate,
       profileId: input.profileId,
@@ -5019,7 +4997,7 @@ export class KnowledgeRuntime {
   }
 
   private compileCardNotes(card: KnowledgeCard): WikiNote[] {
-    if (card.status === 'problem') return []
+    if (card.status === 'problem' || card.status === 'deprecated') return []
     const notes: WikiNote[] = []
     /**
      * 卡片文件所在目录：正文里的图片引用是相对它写的（`../../01_source_raw/_assets/…`），
@@ -5036,7 +5014,7 @@ export class KnowledgeRuntime {
      * `metadata.related_cards`；这里继续剥离旧版本正文里的标记，保证存量卡片迁移期间
      * 也不会把导航送进召回。
      */
-    const recallBody = stripRelatedSection(card.content)
+    const recallBody = stripEventReferenceSection(stripRelatedSection(card.content))
     for (const [index, chunk] of splitWikiNotes({ ...card, content: recallBody }).entries()) {
       const baseId = `${card.entityType}:${card.entityId}`
       const unitId = index === 0 ? baseId : `${baseId}#${index}`
@@ -5100,7 +5078,7 @@ export class KnowledgeRuntime {
   private async rerankNotes(query: string, hits: RecallHit[], threshold: number): Promise<{ hits: RecallHit[]; result: RerankResult; scored?: Array<{ unitId: string; logit: number; rerankScore: number; kept: boolean }>; warning?: string }> {
     const provider = this.config.rerankProvider
     if (provider === 'none') return { hits, result: { status: 'skipped', provider, threshold } }
-    if (hits.length < 2) return { hits, result: { status: 'skipped', provider, model: this.rerankModelPath, scored: hits.length, threshold } }
+    if (hits.length === 0) return { hits, result: { status: 'skipped', provider, model: this.rerankModelPath, scored: hits.length, threshold } }
     if (this.rerankUnavailable) return { hits, result: { status: 'unavailable', provider, model: this.rerankModelPath, error: this.rerankUnavailable, threshold }, warning: `重排不可用，已按融合分数排序：${this.rerankUnavailable}` }
     try {
       if (!this.rerankWorker) this.rerankWorker = this.spawnWorker('RERANK')
@@ -5345,7 +5323,6 @@ export class KnowledgeRuntime {
      */
     const profile = this.organizeProfile()
     const profileId = profile?.id ?? 'concept'
-    const eventsById = new Map((await this.loadEvents()).map(event => [event.id, event]))
     for (const item of pending.values()) {
       if (runId) await this.checkpointCompileTask(runId)
       const key = `${item.entityType}:${item.entityId}`
@@ -5394,7 +5371,7 @@ export class KnowledgeRuntime {
         && layoutOf(existing.metadata)?.origin === 'model'
       const finalTitle = preserveModelLayout ? existing.title : item.title
       const contentBeforeEvents = preserveModelLayout ? existing.content : content
-      const finalContent = withEventReferences(contentBeforeEvents, item.metadata.event_refs, eventsById)
+      const finalContent = stripEventReferenceSection(contentBeforeEvents)
       const finalSummary = preserveModelLayout ? existing.summary : item.summary
       let finalPlacements = preserveModelLayout || item.placements === undefined
         ? undefined
@@ -5478,7 +5455,7 @@ export class KnowledgeRuntime {
       outcome.cardsUpdated += 1
       for (const warning of written.warnings ?? []) outcome.warnings.push(`卡片 ${card.entityId}：${warning}`)
     }
-    // WikiCard 是 Knowledge 与 Event 的坐标聚合层；Event 本体读自独立 event 表。
+    // WikiCard 只由 Knowledge 物化；Event 作为独立事实按坐标挂引用。
     const eventSync = await this.syncEventReferences()
     outcome.cardsUpdated += eventSync.updated
     outcome.warnings.push(...eventSync.warnings)
@@ -5540,12 +5517,13 @@ export class KnowledgeRuntime {
      * 用的输入与收尾阶段那个相关块**完全相同**（同一份 `relations` + 同一个坐标投影），
      * 所以「正文里能提到谁」与「末尾相关块列了谁」不会是两个答案。
      */
+    const cardsWithoutLegacyEventSections = input.cards.map(card => ({ ...card, content: stripEventReferenceSection(card.content) }))
     const relatedPlan = planRelated(
-      input.cards,
+      cardsWithoutLegacyEventSections,
       input.relations,
       await this.projectedRelated(input.cards),
     )
-    const withCoordinate = input.cards
+    const withCoordinate = cardsWithoutLegacyEventSections
       .filter(card => card.coordinate !== undefined)
       .sort((left, right) => left.entityId.localeCompare(right.entityId))
     if (withCoordinate.length === 0) return 0
@@ -6170,7 +6148,7 @@ export class KnowledgeRuntime {
     const projected = await this.projectedRelated(cards)
     const related = planRelated(cards, relations, projected)
     /** 统计清理旧导航块之后的正文断链；相关卡片本身不再伪装成正文链接。 */
-    const nextCards = cards.map(card => ({ ...card, content: stripRelatedSection(card.content) }))
+    const nextCards = cards.map(card => ({ ...card, content: stripEventReferenceSection(stripRelatedSection(card.content)) }))
     const deadLinks = deadLinksOf(nextCards)
     let rewritten = 0
     for (const [index, card] of cards.entries()) {
@@ -6853,6 +6831,7 @@ export class KnowledgeRuntime {
    * 不能当成「没命中」。
    */
   async resolveTrialAxisSet(input: {
+    registry?: AxisRegistry
     axes: TrialAxisSet
     axesBlock?: AxisPromptBlock
     runId: string
@@ -6875,6 +6854,7 @@ export class KnowledgeRuntime {
       candidates: Candidate[]
     }
     type Judgment = { decision: 'match' | 'new' | 'uncertain'; candidateId: string }
+    const resolve = (value: Parameters<KnowledgeRuntime['resolveAxisMention']>[0]) => this.resolveAxisMention({ ...value, registry: input.registry })
     const groups: Array<{ kind: AxisKind; key: GroupKey }> = [
       { kind: 'object', key: 'objects' },
       { kind: 'action', key: 'actions' },
@@ -6885,7 +6865,7 @@ export class KnowledgeRuntime {
     const axisKey = (kind: AxisKind, mention: string): string => `${kind}\u0000${normalizeAxisName(mention)}`
     const supplementalEntries: Record<AxisKind, Candidate[]> = { object: [], action: [], scene: [] }
     try {
-      const registry = await this.axisRegistry()
+      const registry = input.registry ?? await this.axisRegistry()
       if (registry !== null) {
         // 初次抽取的候选清单可能被截断。再按本批轴 mention 做一次本地召回，补进未下发的已有坐标。
         const query = groups.flatMap(group => input.axes[group.key].flatMap(axis => [
@@ -6935,7 +6915,7 @@ export class KnowledgeRuntime {
         const key = axisKey(group.kind, axis.name)
         let lookup: AxisResolution | null
         try {
-          lookup = await this.resolveAxisMention({
+          lookup = await resolve({
             kind: group.kind,
             mention: axis.name,
             parentMention: axis.parentMention,
@@ -6998,7 +6978,7 @@ export class KnowledgeRuntime {
         }
 
         // 没有可供模型比较的现有候选时，沿用注册表的新建候选路径。
-        const created = await this.resolveAxisMention({
+        const created = await resolve({
           kind: group.kind,
           mention: axis.name,
           parentMention: axis.parentMention,
@@ -7101,7 +7081,7 @@ export class KnowledgeRuntime {
       const key = axisKey(item.kind, item.axis.name)
       const judgment = decisions.get(key)
       if (judgment?.decision === 'new') {
-        const resolution = await this.resolveAxisMention({
+        const resolution = await resolve({
           kind: item.kind,
           mention: item.axis.name,
           parentMention: item.axis.parentMention,
@@ -7115,7 +7095,7 @@ export class KnowledgeRuntime {
       if (judgment?.decision === 'match') {
         const candidate = item.candidates.find(value => value.id === judgment.candidateId)
         if (candidate) {
-          const resolution = await this.resolveAxisMention({
+          const resolution = await resolve({
             kind: item.kind,
             mention: item.axis.name,
             parentMention: item.axis.parentMention,
@@ -7146,6 +7126,7 @@ export class KnowledgeRuntime {
   }
 
   async resolveAxisMention(input: {
+    registry?: AxisRegistry
     kind: AxisKind
     mention: string
     parentMention?: string
@@ -7163,7 +7144,7 @@ export class KnowledgeRuntime {
     /** 模型给这一轮的定义（0068）。只在新建、或给一个还没有定义的实体补一次。 */
     description?: string
   }): Promise<AxisResolution | null> {
-    const registry = await this.axisRegistry()
+    const registry = input.registry ?? await this.axisRegistry()
     if (registry === null) return null
     const runId = input.runId ?? ''
     let parentId = ''
@@ -7177,7 +7158,7 @@ export class KnowledgeRuntime {
       })
       if (parent.entity) parentId = parent.entity.id
     }
-    const preferId = await this.axisIdByName(input.kind, input.preferMention)
+    const preferId = await this.axisIdByName(input.kind, input.preferMention, registry)
     return registry.resolve({
       kind: input.kind, mention: input.mention,
       ...(parentId ? { parentId } : {}), ...(runId ? { runId } : {}),
@@ -7194,10 +7175,10 @@ export class KnowledgeRuntime {
    * 「是已有的某个东西」而那个名字在库里指两个实体时，把它当成指认就等于替人做了
    * 「哪一个」的决定 —— 而注册表的规矩是「不唯一就不猜」。
    */
-  private async axisIdByName(kind: AxisKind, mention: string | undefined): Promise<string | undefined> {
+  private async axisIdByName(kind: AxisKind, mention: string | undefined, supplied?: AxisRegistry): Promise<string | undefined> {
     const name = (mention ?? '').trim()
     if (!name) return undefined
-    const registry = await this.axisRegistry()
+    const registry = supplied ?? await this.axisRegistry()
     if (registry === null) return undefined
     try {
       const probe = await registry.resolve({ kind, mention: name, create: false })
@@ -7884,14 +7865,12 @@ export class KnowledgeRuntime {
       refs.push(event.id)
       eventsByCoordinate.set(key, refs)
     }
-    const eventIndex = new Map(events.map(event => [event.id, event]))
     const warnings: string[] = []
     let updated = 0
     for (const card of await this.loadCards()) {
-      const refs = card.coordinate === undefined
+      const refs = card.status === 'deprecated' || card.coordinate === undefined || card.entityType === 'diagnosis/case'
         ? []
         : (eventsByCoordinate.get(coordinateKeyOf(card.coordinate)) ?? []).sort()
-      db.setCardEvents(card.entityId, refs)
       const oldRaw = card.metadata.event_refs
       let oldRefs: string[] = []
       let oldRefsValid = false
@@ -7907,11 +7886,17 @@ export class KnowledgeRuntime {
         oldRefs = oldRaw.filter((item): item is string => typeof item === 'string').sort()
         oldRefsValid = true
       }
-      const content = withEventReferences(card.content, refs, eventIndex)
+      const content = stripEventReferenceSection(card.content)
       const contentChanged = content !== card.content
       const refsChanged = !oldRefsValid || JSON.stringify(refs) !== JSON.stringify(oldRefs)
-      if (!refsChanged && !contentChanged) continue
-      if (!oldRefsValid && refs.length === 0 && oldRaw === undefined && !contentChanged) continue
+      if (!refsChanged && !contentChanged) {
+        db.setCardEvents(card.entityId, refs)
+        continue
+      }
+      if (!oldRefsValid && refs.length === 0 && oldRaw === undefined && !contentChanged) {
+        db.setCardEvents(card.entityId, refs)
+        continue
+      }
       const written = await this.writeCard({
         ...card,
         sourceRefs: card.sourceRefs,
@@ -7919,8 +7904,11 @@ export class KnowledgeRuntime {
         metadata: { ...card.metadata, event_refs: JSON.stringify(refs) },
         origin: 'internal',
       })
-      if (written.ok === false) warnings.push(`坐标 WikiCard ${card.title} 的 Event 聚合视图未更新：${written.error.message}`)
-      else updated += 1
+      if (written.ok === false) warnings.push(`WikiCard ${card.title} 的 Event 引用未更新：${written.error.message}`)
+      else {
+        db.setCardEvents(card.entityId, refs)
+        updated += 1
+      }
     }
     return { updated, warnings }
   }
@@ -7959,10 +7947,6 @@ export class KnowledgeRuntime {
 
     for (const event of db.events()) {
       const remaining = event.records.filter(record => record.sourceId !== input.sourceId)
-      if (remaining.length === 0) {
-        db.removeEvent(event.id)
-        continue
-      }
       const state: EventState = {
         id: event.id,
         identityKey: event.identityKey,
@@ -8063,7 +8047,8 @@ export class KnowledgeRuntime {
     }
 
     for (const state of states.values()) {
-      if (!state.dirty || state.records.length === 0) continue
+      if (!state.dirty) continue
+      if (state.records.length === 0) { db.removeEvent(state.id); continue }
       const records = state.records
       const entity = eventEntityFromRecords({
         id: state.id,
@@ -8084,6 +8069,256 @@ export class KnowledgeRuntime {
     return { saved, merged, skipped, ids, warnings }
   }
 
+  /** The stage runner shares this base's existing writer queue and audit database. */
+  async pipeline(): Promise<KnowledgePipeline> {
+    if (this.closed) throw new Error('知识库已关闭')
+    this.pipelineOpening ??= (async () => {
+      const db = await this.storeHandle()
+      const audit = await this.extractionRuns()
+      if (this.closed) throw new Error('知识库已关闭')
+      if (!db || !audit || !await this.knowledgeStore()) throw new Error('知识库或任务历史不可用，无法启动处理任务')
+      const store = new PipelineStore(db.connection(), audit.connection())
+      const engine = new KnowledgePipeline(store, {
+        capture: () => ({ model: this.modelSeamNow(), note: this.extractionNote(), profile: structuredClone(this.organizeProfile()), organize: this.config.cardOrganize, format: 'table' }),
+        serialize: work => {
+          this.compilePending += 1
+          const run = this.compileTail.then(work, work)
+          this.compileTail = run.then(() => undefined, () => undefined).finally(() => { this.compilePending -= 1 })
+          return run
+        },
+        sources: () => this.pipelineSources(),
+        fingerprint: (source, context) => contentHashOf(JSON.stringify({ source: source.sourceHash, title: source.title, contract: EXTRACTION_CONTRACT_VERSION, note: context.note, format: context.format, model: { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort } })),
+        extract: async (source, context, onDelta) => {
+          if (!context.model.call) throw new Error(`抽取模型不可用：${context.model.why ?? '请在编译设置中选择模型'}`)
+          const axes = await this.axisPromptBlock(source.content)
+          return runWikiTrial({ title: source.title, text: source.content, docId: source.sourceId, axes, note: context.note, call: context.model.call, modelRequest: { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort }, outputFormat: context.format, sessionId: `knowledge:${this.baseId || 'default'}`, onDelta })
+        },
+        normalize: (source, checkpoint, context, force, output) => this.normalizePipelineSource(store, source, checkpoint, context, force, output),
+        groups: context => this.materializationGroups(store, context),
+        materialize: (group, context, output) => this.materializePipelineGroup(store, group, context, output),
+        build: async (taskId, checkpoint) => {
+          let result: Envelope<RebuildReport>
+          try { result = await this.compileOnce(taskId, 'all', undefined, { extract: false, checkpoint }) }
+          catch (cause) { await this.settleProgressFailure(taskId, cause); throw cause }
+          this.settleProgressReport(taskId, result)
+          if (!result.ok) throw new Error(result.error.message)
+          return `检索索引已发布：v${result.data.version}`
+        },
+        record: async checkpoint => {
+          const audit = await this.recordExtractionRun({ id: checkpoint.id, docId: checkpoint.sourceId, title: checkpoint.report.title, summary: trialSummary(checkpoint.report), report: checkpoint.report })
+          if (!audit.saved) throw new Error(`抽取报告保存失败：${audit.why}`)
+        },
+      })
+      this.pipelineEngine = engine
+      if (this.closed) engine.close()
+      return engine
+    })()
+    return this.pipelineOpening
+  }
+
+  private async pipelineSources(): Promise<PipelineSource[]> {
+    const db = await this.storeHandle()
+    if (!db) throw new Error('来源存储不可用')
+    return db.sources().map(row => ({ ...row.record, version: row.version, sourceHash: contentHashOf(row.record.content) })).sort((a, b) => a.sourceId.localeCompare(b.sourceId))
+  }
+
+  private async normalizationFingerprint(checkpoint: ExtractionCheckpoint, context: PipelineContext): Promise<string> {
+    const registry = await this.axisRegistry()
+    const report = checkpoint.normalized?.report ?? checkpoint.report
+    const query = [...report.objects, ...report.actions, ...report.scenes].flatMap(axis => [axis.name, axis.existing ?? '', axis.definition ?? '', axis.parentMention ?? '']).join('\n')
+    const candidates = await registry?.promptEntries(24, query)
+    const mentions = [...checkpoint.report.objects, ...checkpoint.report.actions, ...checkpoint.report.scenes].flatMap(axis => [axis.name, axis.existing ?? '', axis.parentMention ?? '']).map(normalizeAxisName).filter(Boolean)
+    const resolvedIds = new Set([...report.objects, ...report.actions, ...report.scenes].map(axis => axis.id).filter(Boolean))
+    // Ignore unrelated filler rows and registry recency; retain candidates that can affect these mentions.
+    const relevant = Object.fromEntries(Object.entries(candidates?.entries ?? {}).map(([kind, entries]) => [kind, entries.filter(entry => resolvedIds.has(entry.id) || mentions.some(mention => [entry.name, ...entry.aliases, entry.description].map(normalizeAxisName).some(value => value.includes(mention) || (value.length > 1 && mention.includes(value))))).sort((a, b) => a.id.localeCompare(b.id))]))
+    return contentHashOf(JSON.stringify({ extraction: checkpoint.id, model: { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort }, candidates: relevant }))
+  }
+
+  private async normalizePipelineSource(store: PipelineStore, source: PipelineSource, checkpoint: ExtractionCheckpoint, context: PipelineContext, force: boolean, output: (text: string) => void): Promise<{ reused: boolean; warnings: string[] }> {
+    const fingerprint = await this.normalizationFingerprint(checkpoint, context)
+    if (!force && checkpoint.normalized?.fingerprint === fingerprint && store.head(source.sourceId).normalized?.id === checkpoint.id) return { reused: true, warnings: [] }
+    if (!checkpoint.report.model.response) throw new Error('抽取记录没有原始返回，无法归一；请重新抽取该文档')
+    const registry = await this.axisRegistry()
+    if (!registry) throw new Error('实体注册表不可用')
+    const draft = await registry.draft()
+    try {
+      const axesBlock = await this.axisPromptBlock(source.content)
+      const call: ModelCall | undefined = context.model.call ? request => context.model.call!({ ...request, onDelta: output }) : undefined
+      const report = await runWikiTrial({
+        title: source.title, text: source.content, docId: source.sourceId, axes: axesBlock,
+        // Reparse the captured response; this callback never requests another extraction.
+        call: async () => checkpoint.report.model.response!, modelRequest: checkpoint.report.model.request,
+        resolveAxisSet: axes => this.resolveTrialAxisSet({ registry: draft.registry, axes, axesBlock, runId: checkpoint.id, call, modelRequest: context.model }),
+      })
+      if (!report.model.parsed) throw new Error(report.model.why ?? '抽取结果无法归一')
+      const db = await this.storeHandle()
+      const current = db?.source(source.sourceId)
+      if (this.closed) throw new Error('知识库已关闭，本次归一未提交')
+      if (!db || !current || current.version !== source.version || contentHashOf(current.record.content) !== source.sourceHash) throw new Error('来源在归一期间已变化，请重新抽取最新版本')
+      const sql = db.connection()
+      sql.exec('SAVEPOINT pipeline_normalize')
+      try {
+        draft.commit()
+        // Preserve evidence history while replacing this source's active contribution.
+        sql.prepare('UPDATE knowledge_sources SET withdrawn=1 WHERE document_id=?').run(source.sourceId)
+        const knowledge = await this.ingestTrialKnowledge({ runId: checkpoint.id, knowledge: report.knowledge, objects: report.objects, actions: report.actions, scenes: report.scenes, sourceVersions: { [source.sourceId]: source.version } })
+        const events = await this.ingestTrialEvents({ sourceId: source.sourceId, runId: checkpoint.id, events: report.events, objects: report.objects, actions: report.actions, scenes: report.scenes })
+        if (knowledge.skipped || events.skipped) throw new Error(`出处核验或写入失败：${knowledge.skipped} 条 Knowledge、${events.skipped} 个 Event；本次归一没有提交`)
+        const unresolvedKnowledgeIds = report.knowledge.filter(item => ([['object', report.objects], ['action', report.actions], ['scene', report.scenes]] as const).some(([kind, axes]) => {
+          const name = item[kind]
+          const axis = name ? axes.find(axis => axis.name === name) : undefined
+          return name !== null && (!axis || axis.outcome === 'ambiguous' || axis.outcome === 'no-registry')
+        })).map(item => knowledge.ids[item.id]!).filter(Boolean)
+        const normalized = { report, knowledgeIds: knowledge.ids, eventIds: events.ids, unresolvedKnowledgeIds, fingerprint: '' }
+        // Store the post-resolution candidate snapshot so learning its own entities does not invalidate this run.
+        normalized.fingerprint = await this.normalizationFingerprint({ ...checkpoint, normalized }, context)
+        store.saveNormalization(checkpoint, normalized)
+        sql.exec('RELEASE pipeline_normalize')
+        // Updating Event references is a cheap relation refresh. It does not reorganize or index card content.
+        const eventReferences = await this.syncEventReferences()
+        return { reused: false, warnings: [...events.warnings, ...eventReferences.warnings, ...(unresolvedKnowledgeIds.length ? [`${unresolvedKnowledgeIds.length} 条 Knowledge 的坐标仍有歧义，保留事实与出处，暂不物化。`] : [])] }
+      } catch (cause) { sql.exec('ROLLBACK TO pipeline_normalize; RELEASE pipeline_normalize'); throw cause }
+    } finally { draft.close() }
+  }
+
+  private async activePipelineKnowledge(): Promise<Knowledge[]> {
+    const knowledge = await this.knowledgeStore()
+    const db = await this.storeHandle()
+    if (!knowledge || !db) return []
+    const rows: Knowledge[] = []
+    for (let offset = 0;; offset += 500) {
+      const page = await knowledge.list({ excludeWithdrawn: true, limit: 500, offset })
+      rows.push(...page.knowledge.filter(row => row.status !== 'deprecated').map(row => assessKnowledgeEvidence(row, db)).map(row => ({ ...row, sources: row.sources.filter(source => !source.withdrawn && source.evidenceStatus !== 'missing') })).filter(row => row.sources.length > 0))
+      if (offset + page.knowledge.length >= page.total) break
+    }
+    return rows
+  }
+
+  private async materializationGroups(store: PipelineStore, context: PipelineContext): Promise<{ groups: MaterializationGroup[]; blocked: number }> {
+    const unresolved = store.unresolvedKnowledge()
+    const groups = new Map<string, { coordinate: CardCoordinate; knowledge: Knowledge[] }>()
+    let blocked = 0
+    const groupFor = (coordinate: CardCoordinate) => {
+      const key = coordinateKeyOf(coordinate)
+      if (!groups.has(key)) groups.set(key, { coordinate, knowledge: [] })
+      return groups.get(key)!
+    }
+    for (const row of await this.activePipelineKnowledge()) {
+      const coordinate = { objectId: row.objectId, actionId: row.actionId, sceneId: row.sceneId }
+      if (coordinateIsEmpty(coordinate)) { blocked += 1; continue }
+      groupFor(coordinate).knowledge.push(row)
+    }
+    const db = await this.storeHandle()
+    const eventsByCoordinate = new Map<string, EventEntity[]>()
+    for (const event of db?.events() ?? []) {
+      const coordinate = event.coordinateIds
+      if (!coordinate.objectId || !coordinate.actionId || !coordinate.sceneId) continue
+      const key = coordinateKeyOf(coordinate)
+      const bucket = eventsByCoordinate.get(key) ?? []
+      bucket.push(event)
+      eventsByCoordinate.set(key, bucket)
+    }
+    const cards = await this.loadCards()
+    const byCoordinate = new Map(cards.filter(card => card.coordinate).map(card => [coordinateKeyOf(card.coordinate!), card]))
+    const result: MaterializationGroup[] = []
+    for (const [key, value] of groups) {
+      const names = await this.coordinateNames(value.coordinate)
+      const existing = byCoordinate.get(key)
+      // Event 只作为卡片引用；它的增删和正文变化不得触发 Knowledge 重新组织。
+      const fingerprint = contentHashOf(JSON.stringify({ knowledge: value.knowledge.map(row => ({ id: row.id, text: row.text, status: row.status, sources: row.sources.filter(source => !source.withdrawn) })).sort((a, b) => a.id.localeCompare(b.id)), profile: context.profile, organize: context.organize, model: context.organize ? { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort } : undefined }))
+      const receipt = store.materialization(key)
+      const current = existing && receipt?.fingerprint === fingerprint && receipt.cardId === existing.entityId
+      const contributingSources = [...new Set(value.knowledge.flatMap(row => row.sources.map(source => source.documentId)))].filter(Boolean).sort()
+      const needsNormalization = value.knowledge.some(row => unresolved.ids.has(row.id)) || contributingSources.some(id => {
+        const source = db?.source(id)
+        const head = store.head(id)
+        return head.normalized ? head.normalized.sourceVersion !== source?.version || head.extracted?.id !== head.normalized.id : value.knowledge.some(row => row.sources.some(evidence => evidence.documentId === id && evidence.toVersion !== undefined && evidence.toVersion !== source?.version))
+      })
+      if (needsNormalization) blocked += value.knowledge.length
+      result.push({ key, title: existing?.title ?? cardNameFor(names.object || null, names.action || null, names.scene || null), coordinate: value.coordinate, knowledgeCount: value.knowledge.length, eventCount: eventsByCoordinate.get(key)?.length ?? 0, sourceIds: contributingSources, ...(existing ? { cardId: existing.entityId } : {}), state: needsNormalization ? 'blocked' : current ? 'current' : existing ? 'changed' : 'new', ...(needsNormalization ? { reason: '分组中的来源已变化、新抽取待归一或坐标有歧义，请先完成归一' } : {}), fingerprint })
+    }
+    for (const card of cards) {
+      if (!card.coordinate || groups.has(coordinateKeyOf(card.coordinate)) || !store.materialization(coordinateKeyOf(card.coordinate)) || card.status === 'deprecated') continue
+      result.push({ key: coordinateKeyOf(card.coordinate), title: card.title, coordinate: card.coordinate, knowledgeCount: 0, eventCount: 0, sourceIds: card.sourceRefs, cardId: card.entityId, state: card.sourceRefs.some(id => unresolved.sources.has(id)) ? 'blocked' : 'withdrawn', ...(card.sourceRefs.some(id => unresolved.sources.has(id)) ? { reason: '来源中的坐标仍有歧义，请先完成归一' } : {}), fingerprint: 'withdrawn' })
+    }
+    return { groups: result.sort((a, b) => a.title.localeCompare(b.title)), blocked }
+  }
+
+  private async materializePipelineGroup(store: PipelineStore, group: MaterializationGroup, context: PipelineContext, output: (text: string) => void): Promise<void> {
+    const db = await this.storeHandle()
+    if (!db) throw new Error('知识库不可用')
+    const fresh = (await this.materializationGroups(store, context)).groups.find(item => item.key === group.key)
+    if (!fresh || fresh.fingerprint !== group.fingerprint) throw new Error('卡片分组在处理期间已变化，请刷新并重试')
+    if (fresh.state === 'blocked') throw new Error(fresh.reason)
+    const storedExisting = group.cardId ? await this.readCard(group.cardId) : undefined
+    const existing = storedExisting
+      ? { ...storedExisting, content: stripEventReferenceSection(storedExisting.content) }
+      : undefined
+    if (group.state === 'withdrawn') {
+      if (!existing) return
+      const written = await this.writeCard({ ...existing, status: 'deprecated', origin: 'compile' })
+      if (!written.ok) throw new Error(written.error.message)
+      store.materialized(group.key, group.fingerprint, existing.entityId)
+      return
+    }
+    const allKnowledge = await this.activePipelineKnowledge()
+    const knowledge = allKnowledge.filter(row => coordinateKeyOf({ objectId: row.objectId, actionId: row.actionId, sceneId: row.sceneId }) === group.key)
+    const events = db.events().filter(event => coordinateKeyOf(event.coordinateIds) === group.key)
+    const profile = context.profile
+    const entityType = (profile?.id ?? 'concept') as SchemaType
+    let title = group.title
+    let content = `## 知识\n\n${knowledge.map(row => `- ${row.text}`).join('\n')}`
+    let summary = knowledge[0]?.text ?? ''
+    let placements: CardKnowledgeRow[] = knowledge.map((row, index) => ({ knowledgeId: row.id, section: '知识', ordinal: index + 1, origin: 'compiler' }))
+    let metadata: Record<string, unknown> = { ...(existing?.metadata ?? {}), pipeline_materialization: true }
+    const entityId = existing?.entityId ?? `coord-${hash(group.key)}`
+    const imagePlan = planSourceImages({
+      cards: (await this.materializationGroups(store, context)).groups.filter(item => item.state !== 'withdrawn').map(item => ({ key: item.key, content: allKnowledge.filter(row => coordinateKeyOf({ objectId: row.objectId, actionId: row.actionId, sceneId: row.sceneId }) === item.key).map(row => row.text).join('\n\n'), sourceRefs: item.sourceIds })),
+      sources: (await this.loadSources()).map(source => ({ sourceId: source.sourceId, content: source.content })),
+    })
+    const images = imagePlan.byCard.get(group.key) ?? []
+    const related = existing ? await this.relatedForCard(existing) : {}
+    metadata.citations = citationsFrom({ placements, knowledge: new Map(knowledge.map(row => [row.id, { source: row.sources[0]?.documentId, heading: row.sources[0]?.headingPath.at(-1) }])) })
+    if (context.organize && knowledge.length > 0) {
+      if (!context.model.call) throw new Error(`卡片组织模型不可用：${context.model.why ?? '请选择模型'}`)
+      const result = await this.organizeCard({ knowledge, images, ...related, cardTitle: title, coordinate: group.coordinate, profileId: entityType, force: true, suggestedSections: profile?.sections.map(section => section.label), requiredSections: profile?.sections.filter(section => section.required).map(section => section.label), existing, call: request => context.model.call!({ ...request, onDelta: output }) })
+      if (result.kind !== 'applied') throw new Error(result.kind === 'reused' ? '组织结果已变化，请刷新后重试' : result.warnings.join('；'))
+      title = result.title; content = result.content; summary = result.summary; placements = result.placements
+      metadata = { ...metadata, layout: result.layout, citations: result.citations }
+    }
+    for (const image of images) content = insertImage(content, image)
+    const eventIds = events.map(event => event.id).sort()
+    content = stripEventReferenceSection(content)
+    metadata.event_refs = JSON.stringify(eventIds)
+    // Freeze the selected group's facts, not an arbitrary subset of its rows.
+    const latest = (await this.materializationGroups(store, context)).groups.find(item => item.key === group.key)
+    if (!latest || latest.fingerprint !== group.fingerprint || latest.state === 'blocked') throw new Error('卡片组织期间事实发生变化，结果未提交，请重试')
+    if (this.closed) throw new Error('知识库已关闭，本次物化未提交')
+    const written = await this.writeCard({ entityType, entityId, title, content, summary, sourceRefs: group.sourceIds, status: existing?.status === 'deprecated' ? 'unreviewed' : existing?.status ?? 'unreviewed', coordinate: group.coordinate, placements, metadata, origin: 'compile' })
+    if (!written.ok) throw new Error(written.error.message)
+    db.setCardEvents(entityId, eventIds)
+    store.materialized(group.key, group.fingerprint, entityId)
+  }
+
+  async pipelineStatus(): Promise<PipelineStatus> {
+    const pipeline = await this.pipeline()
+    const sources = await this.pipelineSources()
+    const context: PipelineContext = { model: this.modelSeamNow(), note: this.extractionNote(), profile: this.organizeProfile(), organize: this.config.cardOrganize, format: 'table' }
+    const rows: PipelineStatus['sources'] = await Promise.all(sources.map(async source => {
+      const head = pipeline.store.head(source.sourceId)
+      const extracted = head.extracted?.sourceVersion === source.version && head.extracted.sourceHash === source.sourceHash
+      const normalized = extracted && head.normalized?.id === head.extracted?.id && head.normalized?.normalized?.fingerprint === await this.normalizationFingerprint(head.normalized!, context)
+      return { id: source.sourceId, title: source.title, version: source.version, extractionId: head.extracted?.id, normalizedId: head.normalized?.id, state: normalized ? 'normalized' as const : extracted ? 'extracted' as const : head.extracted ? 'outdated' as const : 'pending' as const }
+    }))
+    const { groups, blocked } = await this.materializationGroups(pipeline.store, context)
+    const db = await this.derivedHandle()
+    const manifest = db?.artifact('build-manifest.json')
+    const hashes = manifest ? (JSON.parse(manifest) as { cardHashes?: Record<string, string> }).cardHashes ?? {} : {}
+    const cards = await this.loadCards()
+    const indexPending = cards.some(card => hashes[`${card.entityType}:${card.entityId}`] !== this.cardHashOf(card)) || Object.keys(hashes).length !== cards.length
+    return { sources: rows, groups, blocked, pendingNew: groups.filter(group => group.state === 'new').length, pendingUpdated: groups.filter(group => group.state === 'changed').length, pendingWithdrawn: groups.filter(group => group.state === 'withdrawn').length, indexPending }
+  }
+
   /** 抽取轨迹列表（新→旧，不含报告本体）。 */
   async listExtractionRuns(query: { docId?: string; limit?: number; offset?: number } = {}): Promise<ExtractionRunPage | null> {
     const store = await this.extractionRuns()
@@ -8271,11 +8506,12 @@ export class KnowledgeRuntime {
    * 跑一趟编译的**实体**（0066）。它不做排队，也不对外承诺「你 await 它就等于你发起了
    * 它」—— 那两件事分别在 `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?.()
+  private async compileOnce(runId: string, only: 'all' | 'schema' | 'wiki' | 'embeddings' = 'all', lineage?: LineageContext, options: { extract?: boolean; forceExtract?: boolean; checkpoint?: () => Promise<void> } = {}): Promise<Envelope<RebuildReport>> {
+    if (only === 'all' || only === 'embeddings') await this.environmentGuard?.('embedding')
     this.publication = { artifacts: new Map() }
     const configAtStart = JSON.stringify({ config: this.config, fingerprint: this.embeddingFingerprint() })
     try {
+      await options.checkpoint?.()
       await this.loadCompiledState()
       const result = await this.prepareCompile(runId, only, lineage, options)
       await this.checkpointCompileTask(runId)
@@ -8305,6 +8541,7 @@ export class KnowledgeRuntime {
         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: 编译期间设置已变化，请重新编译')
+        await options.checkpoint?.()
         db.publish(this.publication)
         this.vectorIndex = null
       }
@@ -8452,7 +8689,7 @@ export class KnowledgeRuntime {
         tally.knowledge > 0
           ? `抽出知识 ${tally.knowledge} 条`
           : '未用模型：正文按 ## 小节切',
-        tally.skipped > 0 ? `跳过未变 ${tally.skipped} 份` : '指纹全变，没有可复用的',
+        tally.skipped > 0 ? `复用未变来源 ${tally.skipped} 份` : options.forceExtract ? '本次为手动强制重抽' : '正在检查新增或变化的来源',
       ]
       if (done < total) {
         setStep('knowledge', 'running', knowledgeFacts)
@@ -9426,7 +9663,7 @@ export class KnowledgeRuntime {
      * 只取**命中这几张卡**的落位。用 `placements()`（全表）在这里是错的量级：
      * 一次召回十来张卡，而库里可能有上千张。
      */
-    try { placements = snapshot?.placements.length ? new Map(snapshot.placements) : store.placementsOf([...new Set(hits.map(hit => hit.entityId))]) } catch { return }
+    try { placements = snapshot ? new Map(snapshot.placements) : store.placementsOf([...new Set(hits.map(hit => hit.entityId))]) } catch { return }
     /**
      * 每条命中要哪几条 Knowledge：以 Card 正文切出的 heading 为准。
      *
@@ -9442,7 +9679,7 @@ export class KnowledgeRuntime {
     })
     const wanted = new Set(perHit.flat().map(row => row.knowledgeId))
     if (wanted.size === 0) return
-    const rows = snapshot && snapshot.knowledge.length > 0
+    const rows = snapshot
       ? new Map(snapshot.knowledge.filter(row => wanted.has(row.id) && knowledge !== null)
         .flatMap(row => {
           // Deleted facts never reappear through a historical snapshot.
@@ -9536,11 +9773,14 @@ 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)
-    try { await this.environmentGuard?.() }
+    try {
+      if (recallMode !== 'fts') await this.environmentGuard?.('embedding')
+      if (options.rerank !== false && this.config.rerankProvider !== 'none') await this.environmentGuard?.('rerank')
+    }
     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 liveKeys = new Set(liveCards.filter(card => card.status !== 'deprecated').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)
@@ -9700,7 +9940,7 @@ export class KnowledgeRuntime {
       ].join('\n')
       const reranked = await this.rerankNotes(rerankQuery, hits, this.config.rerankThreshold)
       rerankScored = reranked.scored ?? []
-      hits = reranked.hits.slice(0, recallTopK)
+      hits = reranked.hits
       rerank = reranked.result
       if (reranked.warning) warnings.push(reranked.warning)
     }
@@ -9709,7 +9949,7 @@ export class KnowledgeRuntime {
     }
     // 重排换的是相关性顺序，评分加权仍然要压在最上面 —— 否则「review 过的排前面一点」
     // 只在关掉重排时成立，而重排默认是开着的。
-    hits = [...hits].sort((left, right) => rankKey(right) - rankKey(left) || left.unitId.localeCompare(right.unitId))
+    hits = [...hits].sort((left, right) => rankKey(right) - rankKey(left) || left.unitId.localeCompare(right.unitId)).slice(0, recallTopK)
 
     // --- R4 · 证据片段 -----------------------------------------------------
     const truth = await this.storeHandle()