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

package/src/runtime.ts

@@ -23,13 +23,19 @@ import { LEGACY_ENTITY_TYPES } from './diagnosis/schema.js'
 import { DiagnosisStore } from './diagnosis/store.js'
 import { MAX_LOG_ITEMS, OperationLog, operationId } from './oplog.js'
 import { ExtractionRunStore, extractionRunId, type ExtractionRunPage, type ExtractionRunRecord, type ExtractionRunSummary } from './extraction-runs.js'
+import type { MaterializeTrajectoryReport, NormalizeTrajectoryReport, TrajectoryStage } from './trajectory-types.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 type { TrialAxis, TrialEvent, TrialKnowledge, TrialSource, TrialTokenUsage } from './wiki-trial-types.js'
+import { compositeEventIdentity, eventEntityFromRecords, stripEventReferenceSection, type EventEntity, type EventSourceRecord } from './events.js'
+import type { TrialAxis, TrialEvent, TrialKnowledge, TrialReport, 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 type { MaterializationSnapshot } from './materialize-snapshot.js'
 import { candidatesFromReport, coordinateIdsOf, coordinateIsEmpty, type MaterializedCard } from './wiki-materialize.js'
 import {
   buildOrganizePrompt, buildOrganizeSystem, checkOrganize, citationsFrom, layoutHash, layoutOf,
@@ -40,7 +46,7 @@ import {
 import { FTS_FILE, FtsIndex, loadSqlite, segment } from './fts.js'
 import { attachImagesToKnowledge, insertImage, planSourceImages, type SourceImage } from './source-images.js'
 import {
-  buildWikiIndex, cardKey, deadLinksOf, planRelated, relatedEntriesOf, stripRelatedSection,
+  buildWikiIndex, cardKey, deadLinksOf, planRelated, relatedByGroupKey, relatedEntriesOf, stripRelatedSection,
   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'
@@ -256,6 +262,15 @@ const RRF_K = 60
 const RRF_WEIGHTS = { coordinate: 0.9, relation: 0.45, fts: 0.3, vector: 0.7, graph: 0.2 } as const
 /** 图谱只是 boost，不是路：它的权重只作用在**已经在候选池里**的条目上（见 `graphBoost`）。 */
 const GRAPH_BOOST_WEIGHT = RRF_WEIGHTS.graph
+/**
+ * 重排失败后的冷却时间。
+ *
+ * 失败要先记住，否则每次召回都会重新拉起一个注定失败的 worker（那是「秒级重试」的代价）。
+ * 但**不能永久记住**：一次超时是暂态，而写死之后 `rerankNotes` 会在开头直接返回，
+ * 于是这个标志自我封闭 —— 只有换模型、重载家当或人工重跑自检才能清掉。带上冷却，
+ * 第一次失败仍然如实报（有生产门时仍然明确失败），之后每 30 秒给一次自愈机会。
+ */
+const RERANK_RETRY_COOLDOWN_MS = 30_000
 /**
  * 编码器健康门的判据：两段无关文本的余弦必须低于它。
  *
@@ -657,6 +672,8 @@ export interface ImportFailure {
  * 而这里要回答的是「刚才那一下让库里多了什么」。
  */
 export interface ImportCompileReport {
+  taskId?: string
+  state?: import('./pipeline/types.js').PipelineState
   cardsCreated: number
   cardsUpdated: number
   cardsReused?: number
@@ -1046,38 +1063,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 +1340,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 +1372,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 +1760,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 +1984,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 +2039,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
@@ -2134,8 +2121,8 @@ export class KnowledgeRuntime {
   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. */
-  private rerankUnavailable: string | undefined
+  /** Cache the last rerank failure with its time; see `RERANK_RETRY_COOLDOWN_MS`. */
+  private rerankUnavailable: { error: string; at: number } | undefined
   /** 解析后的 Python 解释器路径（配置为空时从家当目录解析）。 */
   private pythonPath: string
   /** 解析后的嵌入模型：本地目录或 HF 模型名。 */
@@ -2803,12 +2790,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 +3193,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)
@@ -3509,6 +3493,16 @@ export class KnowledgeRuntime {
    * 失败一律返回 `null`，**不抛** —— 「知识库不可用」是一条要显示的结论，不是一个异常。
    */
   private storeHandleOpening?: Promise<KnowledgeDb | null>
+  /**
+   * 知识存储现在可用吗（0070）。
+   *
+   * 读路径需要它把「确认是空」与「读不到」分开：`loadCards()` 在存储不可用时返回 `[]`，
+   * 而调用方据此做写决定（例如诊断的旧格式迁移）就会把一次读故障变成一次污染写。
+   */
+  async knowledgeStoreAvailable(): Promise<boolean> {
+    return (await this.storeHandle()) !== null
+  }
+
   private async storeHandle(): Promise<KnowledgeDb | null> {
     if (this.store !== undefined) return this.store
     this.storeHandleOpening ??= this.openStoreHandle()
@@ -4329,6 +4323,7 @@ export class KnowledgeRuntime {
    * 提示词与真编译发出去的那一份必须是**同一份**，否则预览这件事本身没有意义。
    */
   private async organizeContext(input: {
+    knowledge?: Knowledge[]
     cardTitle: string
     coordinate: CardCoordinate
     profileId: string
@@ -4353,10 +4348,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 +4536,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 +4548,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 +4560,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 +4642,7 @@ export class KnowledgeRuntime {
   }
 
   private async organizeCard(input: {
+    knowledge?: Knowledge[]
     cardTitle: string
     coordinate: CardCoordinate
     profileId: string
@@ -4670,6 +4668,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 +5018,16 @@ export class KnowledgeRuntime {
   }
 
   private compileCardNotes(card: KnowledgeCard): WikiNote[] {
-    if (card.status === 'problem') return []
+    /**
+     * **只排除 `deprecated`，不排除 `problem`。**
+     *
+     * `problem` 是人工标注的「这张卡有问题」，它仍然是知识，而召回契约里的
+     * `include_problems` 是一个**读取时**的开关（见 `recall` 里 eligible 的那一行）。
+     * 在编译期就把它的 note 丢掉，等于把这个开关变成死参数：无论传什么，编译产物
+     * 里根本没有它的 note，FTS / 向量索引里也没有。所以索引层保留，过滤留给读路径。
+     * `deprecated` 不同 —— 它是退役，编译与读取两层都该排除。
+     */
+    if (card.status === 'deprecated') return []
     const notes: WikiNote[] = []
     /**
      * 卡片文件所在目录：正文里的图片引用是相对它写的（`../../01_source_raw/_assets/…`），
@@ -5036,7 +5044,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}`
@@ -5070,10 +5078,17 @@ export class KnowledgeRuntime {
   /** 1-hop neighbourhood of a set of wiki cards inside the compiled graph. */
   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)
+    /**
+     * 必须读**传进来的** `graph`，不能读 `this.graph`。
+     *
+     * `this.graph` 是编译产物：卡片被删掉之后它不会跟着变小。调用方传的是
+     * `visibleGraph(snapshot.graph, liveGraphKeys(truth))` —— 已按存活实体过滤过的那一份。
+     * 用 `this.graph` 等于把删除掉的卡片留在召回结果的图里。
+     */
+    const edges = graph.edges.filter(edge => keys.has(String(edge.from)) || keys.has(String(edge.to))).slice(0, 50)
     const ids = new Set(keys)
     for (const edge of edges) { ids.add(String(edge.from)); ids.add(String(edge.to)) }
-    const nodes = this.graph.nodes
+    const nodes = graph.nodes
       .filter(visible)
       .filter(node => ids.has(`${node.type}:${node.id}`))
       .slice(0, 50)
@@ -5100,8 +5115,9 @@ 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 (this.rerankUnavailable) return { hits, result: { status: 'unavailable', provider, model: this.rerankModelPath, error: this.rerankUnavailable, threshold }, warning: `重排不可用，已按融合分数排序：${this.rerankUnavailable}` }
+    if (hits.length === 0) return { hits, result: { status: 'skipped', provider, model: this.rerankModelPath, scored: hits.length, threshold } }
+    const cooldownActive = this.rerankUnavailable !== undefined && Date.now() - this.rerankUnavailable.at < RERANK_RETRY_COOLDOWN_MS
+    if (this.rerankUnavailable && cooldownActive) return { hits, result: { status: 'unavailable', provider, model: this.rerankModelPath, error: this.rerankUnavailable.error, threshold }, warning: `重排不可用，已按融合分数排序：${this.rerankUnavailable.error}` }
     try {
       if (!this.rerankWorker) this.rerankWorker = this.spawnWorker('RERANK')
       const response = await this.rerankWorker.request({
@@ -5114,6 +5130,8 @@ export class KnowledgeRuntime {
       const raw: number[] = Array.isArray(response?.scores) ? (response.scores as unknown[]).map(Number) : []
       const outcome = applyRerank(raw, hits, threshold)
       const vocabSize = Number(response?.vocabSize)
+      // 一次成功的推理就是这条缓存的反证：清掉它，别让暂态失败变成会话级残疾。
+      this.rerankUnavailable = undefined
       return {
         hits: outcome.kept,
         scored: outcome.scored,
@@ -5130,7 +5148,7 @@ export class KnowledgeRuntime {
       // so a later recall does not respawn a doomed model every time.
       this.rerankWorker?.close()
       this.rerankWorker = null
-      this.rerankUnavailable = error
+      this.rerankUnavailable = { error, at: Date.now() }
       return { hits, result: { status: 'unavailable', provider, model: this.rerankModelPath, error, threshold }, warning: `重排不可用，已按融合分数排序：${error}` }
     }
   }
@@ -5345,7 +5363,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 +5411,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 +5495,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 +5557,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
@@ -5865,7 +5883,8 @@ export class KnowledgeRuntime {
         outcome.warnings.push(`Event 没有写入知识库：${cause instanceof Error ? cause.message : String(cause)}`)
       }
       outcome.warnings.push(...eventIngested.warnings)
-      if (ingested.skipped > 0 || eventIngested.skipped > 0) extractionComplete = false
+      outcome.warnings.push(...ingested.warnings)
+      if (ingested.skipped > 0 || ingested.failures > 0 || eventIngested.skipped > 0) extractionComplete = false
       // 落位要用库内的 id。这一份报告里每一条知识的映射都并进整轮那一份 ——
       // 后面的来源可能命中同一张卡，那时落位指的行也得是活的。
       Object.assign(knowledgeIds, ingested.ids)
@@ -6170,7 +6189,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()) {
@@ -6747,6 +6766,8 @@ export class KnowledgeRuntime {
     summary: string
     report: unknown
     actor?: string
+    /** 这条轨迹属于哪一段。省略 = 抽取（旧调用点的行为不变）。 */
+    stage?: TrajectoryStage
     /**
      * 这次轨迹的 id。**调用方可以先定**，因为注册表里的候选实体要记住「是哪一次发现的」，
      * 而那个 id 在报告组装之前就得有。不给就现生成一个。
@@ -6757,7 +6778,7 @@ export class KnowledgeRuntime {
     const store = await this.extractionRuns()
     if (store === null) return { saved: false, why: '抽取轨迹库不可用（需要 Node 22.5+ 的 node:sqlite）' }
     const report = input.report as { model?: { ok?: boolean; why?: string } } | null
-    const id = input.id?.trim() || extractionRunId()
+    const id = input.id?.trim() || extractionRunId(input.stage)
     const record: ExtractionRunRecord = {
       id,
       kb: this.rootDir,
@@ -6769,6 +6790,7 @@ export class KnowledgeRuntime {
       ...(report?.model?.why ? { modelWhy: report.model.why } : {}),
       summary: input.summary,
       hasReport: true,
+      stage: input.stage ?? 'extract',
       report: input.report,
     }
     try {
@@ -6779,6 +6801,154 @@ export class KnowledgeRuntime {
     }
   }
 
+  /**
+   * 归一段的轨迹（2026-10-18）。
+   *
+   * 这一段的产物以前只留在两处：任务里的流式输出（刷新就没），和事实表里最终写成的行
+   * （只剩结果）。中间那步 —— 「模型给的这 283 个名字里，哪些命中了已有实体、哪些新建了
+   * 候选、哪些因为不唯一没猜」—— 跑完就查不到了，而它恰好是坐标错了之后唯一能复盘的东西。
+   *
+   * **复用的那一次不落轨迹**：那一次什么都没做（指纹没变、一条事实都没重写），落一条
+   * 「复用」只会把真正的运行挤出第一页。
+   */
+  private async recordNormalizeTrajectory(input: {
+    source: PipelineSource
+    checkpoint: ExtractionCheckpoint
+    report: TrialReport
+    knowledge: { saved: number; merged: number; skipped: number; failures?: number; warnings: string[] }
+    events: { saved: number; merged: number; skipped: number; warnings: string[] }
+    unresolvedKnowledgeIds: string[]
+    fingerprint: string
+    warnings: string[]
+    context: PipelineContext
+  }): Promise<void> {
+    const report = input.report
+    const axes: NormalizeTrajectoryReport['axes'] = ([['object', report.objects], ['action', report.actions], ['scene', report.scenes]] as const).flatMap(([kind, rows]) => rows.map(axis => ({
+      kind,
+      name: axis.name,
+      outcome: axis.outcome,
+      ...(axis.id ? { id: axis.id } : {}),
+      ...(axis.how ? { how: axis.how } : {}),
+      aliases: axis.aliases,
+      ...(axis.parentMention ? { parentMention: axis.parentMention } : {}),
+    })))
+    const count = (outcome: string): number => axes.filter(row => row.outcome === outcome).length
+    const unresolved = new Set(input.unresolvedKnowledgeIds)
+    const payload: NormalizeTrajectoryReport = {
+      stage: 'normalize',
+      at: new Date().toISOString(),
+      source: { id: input.source.sourceId, title: input.source.title, version: input.source.version },
+      extractionId: input.checkpoint.id,
+      fingerprint: input.fingerprint,
+      mentions: report.objects.length + report.actions.length + report.scenes.length,
+      counts: { matched: count('matched'), created: count('new'), ambiguous: count('ambiguous'), mechanical: count('no-registry') },
+      axes: axes.slice(0, 400),
+      knowledge: {
+        saved: input.knowledge.saved,
+        merged: input.knowledge.merged,
+        skipped: input.knowledge.skipped,
+        failures: input.knowledge.failures ?? 0,
+        unresolved: unresolved.size,
+      },
+      events: { saved: input.events.saved, merged: input.events.merged, skipped: input.events.skipped },
+      rows: report.knowledge.slice(0, 300).map(item => ({
+        text: item.text,
+        coordinate: [item.object, item.action, item.scene].filter(Boolean).join(' · ') || '无坐标',
+        sources: item.sources.length,
+        unresolved: unresolved.has(item.id),
+      })),
+      model: {
+        ok: report.model.parsed === true,
+        ...(report.model.why ? { why: report.model.why } : {}),
+        provider: report.model.request?.provider ?? input.context.model.provider,
+        model: report.model.request?.model ?? input.context.model.model,
+        reasoningEffort: report.model.request?.reasoningEffort ?? input.context.model.reasoningEffort,
+      },
+      ...(report.axesContext ? { axesContext: report.axesContext } : {}),
+      warnings: input.warnings,
+    }
+    const saved = await this.recordExtractionRun({
+      stage: 'normalize',
+      docId: input.source.sourceId,
+      title: `${input.source.title} · 归一`,
+      summary: `命中 ${payload.counts.matched} · 新建候选 ${payload.counts.created} · 歧义 ${payload.counts.ambiguous}；写入 ${payload.knowledge.saved} 条 Knowledge / ${payload.events.saved} 个 Event`,
+      report: payload,
+    })
+    if (!saved.saved) throw new Error(saved.why ?? '归一轨迹没有存下来')
+  }
+
+  /**
+   * 物化段的轨迹（2026-10-18）：一个卡片分组 → 一张卡。
+   *
+   * 这一段的产物是卡片本身，所以「卡里有什么」已经查得到；查不到的是**这一次为什么这么排**：
+   * 分组指纹、卡片组织的结论（模型排的还是机械拼的）、进了哪几条知识、正文里为什么链到
+   * 那一张卡。这些是改完提示词、想知道「这次和上次差在哪」时唯一能对着看的东西。
+   *
+   * 粒度是**一组**而不是一个任务：一张卡组织失败，不该让同批其它卡的轨迹一起消失。
+   */
+  private async recordMaterializeTrajectory(input: {
+    group: MaterializationGroup
+    action: 'created' | 'updated' | 'withdrawn'
+    card: { id: string; title: string; status: string; characters: number; events: number; images: number }
+    knowledge: Knowledge[]
+    placements?: CardKnowledgeRow[]
+    organizeUsed: boolean
+    layout?: CardLayoutRecord
+    related: OrganizeRelatedCandidate[]
+    context: PipelineContext
+    warnings?: string[]
+  }): Promise<void> {
+    const sections: MaterializeTrajectoryReport['card']['sections'] = []
+    for (const row of input.placements ?? []) {
+      const hit = sections.find(section => section.label === row.section)
+      if (hit) hit.count += 1
+      else sections.push({ label: row.section, count: 1 })
+    }
+    const payload: MaterializeTrajectoryReport = {
+      stage: 'materialize',
+      at: new Date().toISOString(),
+      group: {
+        key: input.group.key,
+        title: input.group.title,
+        coordinate: [input.group.coordinate.objectId, input.group.coordinate.actionId, input.group.coordinate.sceneId].filter(Boolean).join(' · ') || '无坐标',
+        state: input.group.state,
+        fingerprint: input.group.fingerprint,
+      },
+      action: input.action,
+      card: {
+        id: input.card.id,
+        title: input.card.title,
+        status: input.card.status,
+        characters: input.card.characters,
+        knowledge: input.knowledge.length,
+        events: input.card.events,
+        images: input.card.images,
+        sections,
+      },
+      organize: input.organizeUsed
+        ? { used: true, ...(input.layout?.origin ? { origin: input.layout.origin } : {}), ...(input.layout?.hash ? { layoutHash: input.layout.hash } : {}) }
+        : { used: false },
+      rows: input.knowledge.slice(0, 300).map(row => ({ id: row.id, text: row.text, sources: row.sources.length })),
+      sources: [...input.group.sourceIds],
+      related: input.related.map(candidate => ({ title: candidate.title, reason: candidate.reason })),
+      model: {
+        ok: true,
+        provider: input.context.model.provider,
+        model: input.context.model.model,
+        reasoningEffort: input.context.model.reasoningEffort,
+      },
+      warnings: input.warnings ?? [],
+    }
+    const label = payload.action === 'created' ? '新建' : payload.action === 'updated' ? '更新' : '停用'
+    const saved = await this.recordExtractionRun({
+      stage: 'materialize',
+      title: `${payload.card.title || payload.group.title} · ${label}`,
+      summary: `${label}「${payload.card.title || payload.group.title}」：${payload.card.knowledge} 条知识 · ${payload.card.events} 个事件 · ${payload.card.images} 张图 · ${payload.card.sections.length} 节${payload.organize.used ? '' : '（机械拼装，未用卡片组织）'}`,
+      report: payload,
+    })
+    if (!saved.saved) throw new Error(saved.why ?? '物化轨迹没有存下来')
+  }
+
   /**
    * 轴注册表（0063 §3）：Object / Action / Scene 的 canonical 身份。
    *
@@ -6853,6 +7023,7 @@ export class KnowledgeRuntime {
    * 不能当成「没命中」。
    */
   async resolveTrialAxisSet(input: {
+    registry?: AxisRegistry
     axes: TrialAxisSet
     axesBlock?: AxisPromptBlock
     runId: string
@@ -6875,6 +7046,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 +7057,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 +7107,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 +7170,7 @@ export class KnowledgeRuntime {
         }
 
         // 没有可供模型比较的现有候选时，沿用注册表的新建候选路径。
-        const created = await this.resolveAxisMention({
+        const created = await resolve({
           kind: group.kind,
           mention: axis.name,
           parentMention: axis.parentMention,
@@ -7101,7 +7273,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 +7287,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 +7318,7 @@ export class KnowledgeRuntime {
   }
 
   async resolveAxisMention(input: {
+    registry?: AxisRegistry
     kind: AxisKind
     mention: string
     parentMention?: string
@@ -7163,7 +7336,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 +7350,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 +7367,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 })
@@ -7474,7 +7647,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）。`images.publish` 写入的独立图片会被识别并保留。
+     * 未被引用的来源图片也进这张账（2026-10-05）。`image_publish` 写入的独立图片会被识别并保留。
      *
      * 少了它，「来源与卡片都清完了、只剩一堆没人引用的图」这种状态在界面上**一个字都没有**
      * —— 清理孤儿的入口因此不出现，而用户唯一能看到的读数（「收录 N 个文件」）又把它算成
@@ -7511,7 +7684,7 @@ export class KnowledgeRuntime {
 
   /**
    * 还有没有人在引用这个桶 —— 判据是来源正文、来源 front matter 的 `metadata.assets`、
-   * 卡片正文出现过 `_assets/<bucket>/`，或者它是 `images.publish` 写入的独立图床图片。
+   * 卡片正文出现过 `_assets/<bucket>/`，或者它是 `image_publish` 写入的独立图床图片。
    * 独立图片没有来源/卡片引用是正常状态，必须保留。
    *
    * 为什么三处都要看：桶名是**内容哈希的前 12 位**（`convert/ingest.ts`），不是来源 id。
@@ -7549,7 +7722,7 @@ export class KnowledgeRuntime {
   }
 
   /**
-   * `images.publish` 的图片不需要被来源或卡片引用。新写入的桶有明确标记；同时兼容
+   * `image_publish` 的图片不需要被来源或卡片引用。新写入的桶有明确标记；同时兼容
    * 标记加入前已发布的图片：它们以图片自身的 SHA-256 前 12 位作为桶名。
    */
   private async isPublishedImageBucket(name: string): Promise<boolean> {
@@ -7557,7 +7730,7 @@ export class KnowledgeRuntime {
       if (existsSync(join(root, name, PUBLISHED_IMAGE_MARKER))) return true
     }
 
-    // 旧版本 images.publish 只会写入知识库根目录的 assets/，因此只在这里做哈希识别。
+    // 历史版本发布的图片只会写入知识库根目录的 assets/，因此只在这里做哈希识别。
     if (!/^[a-f0-9]{12}$/i.test(name)) return false
     const dir = join(this.rootDir, ASSETS_DIR, name)
     try {
@@ -7786,6 +7959,15 @@ export class KnowledgeRuntime {
     saved: number
     merged: number
     skipped: number
+    /**
+     * **写入失败**的条数，与 `skipped` 分开（0070）。
+     *
+     * `skipped` = 引文没通过核验（数据问题，重试无用）；`failures` = 落库时抛错
+     * （磁盘、锁、约束，基础设施问题，重试有意义）。合成一个数会让下游把两者
+     * 说成同一句话，而它们的处置完全不同。
+     */
+    failures: number
+    warnings: string[]
     /**
      * **报告里的知识 id → 库里的知识 id**（0069）。
      *
@@ -7798,11 +7980,13 @@ export class KnowledgeRuntime {
     ids: Record<string, string>
   }> {
     const store = await this.knowledgeStore()
-    if (store === null) return { saved: 0, merged: 0, skipped: input.knowledge.length, ids: {} }
+    if (store === null) return { saved: 0, merged: 0, skipped: input.knowledge.length, failures: 0, warnings: [], ids: {} }
     const axes = { objects: input.objects, actions: input.actions, scenes: input.scenes }
     let saved = 0
     let merged = 0
     let skipped = 0
+    let failures = 0
+    const warnings: string[] = []
     const ids: Record<string, string> = {}
     for (const item of input.knowledge) {
       const usable = item.sources.filter(source => source.found)
@@ -7832,9 +8016,20 @@ export class KnowledgeRuntime {
          * 直接用它，不需要再自己判一次归并方向。
          */
         ids[item.id] = result.knowledge.id
-      } catch { skipped += 1 }
+      } catch (cause) {
+        /*
+         * 写入失败与「引文没通过核验」必须分开报。
+         *
+         * 原来这里是一个 `catch { skipped += 1 }`：磁盘满、SQLITE_BUSY、约束冲突
+         * 全都被算成「引文没核验过」，原因被丢掉，而下游只看到同一句话 ——
+         * 运维读到的是一份数据问题，实际是基础设施问题，于是无限重试。
+         * Event 那条路径本来就把消息收进 warnings（见下面），这里对齐它。
+         */
+        failures += 1
+        warnings.push(`Knowledge「${item.text.slice(0, 40)}」写入失败：${cause instanceof Error ? cause.message : String(cause)}`)
+      }
     }
-    return { saved, merged, skipped, ids }
+    return { saved, merged, skipped, failures, warnings, ids }
   }
 
   /**
@@ -7884,14 +8079,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 +8100,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 +8118,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 +8161,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 +8261,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,8 +8283,518 @@ export class KnowledgeRuntime {
     return { saved, merged, skipped, ids, warnings }
   }
 
-  /** 抽取轨迹列表（新→旧，不含报告本体）。 */
-  async listExtractionRuns(query: { docId?: string; limit?: number; offset?: number } = {}): Promise<ExtractionRunPage | null> {
+  /** 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(),
+        source: sourceId => this.pipelineSource(sourceId),
+        /**
+         * 抽取指纹必须覆盖**真正喂给模型的那段实体清单**（0070），但要按本文提到的条目收窄。
+         *
+         * `extract` 把 `axisPromptBlock(source.content)` 拼进提示词（注册表里的实体名、
+         * 别名、定义与人工指引都在里面），而这些会随人的确认、合并与模型的补定义变化。
+         * 指纹漏掉它 → 注册表变了仍复用旧报告，模型当时的 `existing` / `dropped` 判断
+         * 被冻住。旧路径的指纹是含注册表成分的（`axesRevision`），这里原来不对称。
+         *
+         * 见 `pipelineExtractionFingerprint` —— 那里还有一条必需的配套：归一成功后要**刷新**这份
+         * 指纹，否则归一自己学到的实体（它们本来就出现在这份文档里）会让它永远无法复用。
+         */
+        fingerprint: (source, context) => this.pipelineExtractionFingerprint(source, context),
+        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),
+        /**
+         * 引擎只把 `snapshot` 原样传回来，所以那边看到的是 `unknown`；这里把它取回成
+         * 真实类型（见 `materialize-snapshot.ts` 里为什么不放在 `pipeline/types.ts`）。
+         */
+        groups: async context => {
+          const snapshot = await this.materializationSnapshot(store, context)
+          return { groups: snapshot.groups, blocked: snapshot.blocked, blockedAmbiguous: snapshot.blockedAmbiguous, blockedAwaitingNormalize: snapshot.blockedAwaitingNormalize, snapshot }
+        },
+        materialize: (group, context, output, snapshot) => this.materializePipelineGroup(store, group, context, output, snapshot as MaterializationSnapshot),
+        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 result.data.skipped
+            ? { summary: `索引无变化：复用 ${result.data.notesReused ?? 0} 条召回片段，仍为 v${result.data.version}。`, skipped: true }
+            : { summary: `检索索引已更新至 v${result.data.version}。`, skipped: false }
+        },
+        record: async checkpoint => {
+          /**
+           * `scope: 'extract-only'` —— 这份报告的 ②③④ 段**不是这个库里真的做过的事**。
+           *
+           * 报告的形状来自 `runWikiTrial`（试跑：一次调用里把归一、物化、建索引的机械结果
+           * 也顺带算出来）。但在这条流水线里，归一与物化是**独立阶段**，各有自己的任务与轨迹。
+           * 不标这一笔，用户点开抽取轨迹会看到「物化 · 0 张 Wiki Card」并以为物化跑过了。
+           *
+           * 旧的全链路编译（`compileOnce`）不标：那一条路上报告里的四段是真跑过的。
+           */
+          const audit = await this.recordExtractionRun({ id: checkpoint.id, docId: checkpoint.sourceId, title: checkpoint.report.title, summary: trialSummary(checkpoint.report), report: { ...checkpoint.report, scope: 'extract-only' } })
+          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 pipelineSource(sourceId: string): Promise<PipelineSource | undefined> {
+    const db = await this.storeHandle()
+    if (!db) throw new Error('来源存储不可用')
+    const row = db.source(sourceId)
+    return row ? { ...row.record, version: row.version, sourceHash: contentHashOf(row.record.content) } : undefined
+  }
+
+  /**
+   * 抽取指纹（0070）。
+   *
+   * 判据是「这段提示词会不会变」，所以实体清单要按**本文真的提到**的条目收窄：小库发的是
+   * 全集（`selection: 'full'`），直接哈希整块清单会让「新增一个与本文无关的实体」触发全库
+   * 重抽 —— 而那正是既有测试钉住不许发生的退化。
+   *
+   * **已知的取舍**（不是疏漏）：提示词里那份清单是 `promptEntries` 按相关度排/截出来的，
+   * 而这里按字面包含关系重筛一遍。两者不完全等价 —— 「在提示词里但本文没有字面提到」的
+   * 实体被改名时，这里不会失效。选择这条判据是因为另一条（原样哈希发出去的清单）与
+   * 上面那条被测试钉住的产品规则直接冲突。残留风险由归一那一侧兜住：归一总是对着**实时**
+   * 注册表重新解析坐标，所以模型当时的 `existing` 判断不会原样变成最终卡名。
+   *
+   * 它有两个调用点：抽取前判断能不能复用，以及归一成功后**刷新**已存的那一份。后者是必需的：
+   * 归一学到的实体本来就出现在这份文档里，不刷新的话这份文档下次抽取永远复用不上。这与
+   * `normalizationFingerprint` 存「补判之后」的快照是同一条规则，不是两套。
+   */
+  private async pipelineExtractionFingerprint(source: PipelineSource, context: PipelineContext): Promise<string> {
+    const axes = await this.axisPromptBlock(source.content)
+    const text = normalizeAxisName(source.content)
+    const relevant = (['object', 'action', 'scene'] as const).map(kind => (axes?.entries[kind] ?? [])
+      .filter(entry => [entry.name, ...entry.aliases].map(normalizeAxisName).some(value => value.length > 0 && text.includes(value)))
+      .map(entry => ({ id: entry.id, name: entry.name, aliases: entry.aliases, description: entry.description, guidance: entry.guidance }))
+      .sort((left, right) => left.id.localeCompare(right.id)))
+    return contentHashOf(JSON.stringify({ source: source.sourceHash, title: source.title, contract: EXTRACTION_CONTRACT_VERSION, note: context.note, format: context.format, axes: relevant, model: { provider: context.model.provider, model: context.model.model, reasoningEffort: context.model.reasoningEffort } }))
+  }
+
+  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 || knowledge.failures || events.skipped) throw new Error(`出处核验或写入失败：${knowledge.skipped} 条 Knowledge 引文未通过核验、${knowledge.failures} 条写入失败、${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.refreshFingerprint(checkpoint.id, await this.pipelineExtractionFingerprint(source, 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()
+        const warnings = [...knowledge.warnings, ...events.warnings, ...eventReferences.warnings, ...(unresolvedKnowledgeIds.length ? [`${unresolvedKnowledgeIds.length} 条 Knowledge 的坐标仍有歧义，保留事实与出处，暂不物化。`] : [])]
+        /**
+         * 轨迹在**提交之后**才落（`RELEASE` 之后）：写在 savepoint 里面的话，回滚了还会留下
+         * 一条「归一成功了」的记录。
+         *
+         * 落不下来只记一条警告，不把这一段判失败 —— 事实已经写进知识库了，这时候抛错会让人
+         * 以为没生效。抽取那一段是反过来的（它的产物只有报告，存不下就等于什么都没做）。
+         */
+        try {
+          await this.recordNormalizeTrajectory({ source, checkpoint, report, knowledge, events, unresolvedKnowledgeIds, fingerprint: normalized.fingerprint, warnings, context })
+        } catch (cause) {
+          warnings.push(`归一轨迹没有存下来：${cause instanceof Error ? cause.message : String(cause)}`)
+        }
+        return { reused: false, warnings }
+      } 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 []
+    /**
+     * **来源正文预读一次**，别在每一行上重读整份文档。
+     *
+     * `assessSource` 要对每条 knowledge-source 判定「引文是否还在当前版本里」，而那需要
+     * 该文档的正文。原来的写法是 `db.source(id)`：每行一次全表 join + 整份正文 + 全文
+     * flatten + 子串匹配 —— 5000 条知识 × 每份 50 KB 就是几百 MB 的重复工作，而这只是
+     * 一次调用。正文在这里读一次（一条查询），下面按 documentId 查表。
+     */
+    const bodies = new Map<string, { version: number; content: string }>()
+    for (const row of db.sources()) bodies.set(row.record.sourceId, { version: row.version, content: row.record.content })
+    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, bodies)).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 needsNormalizationForGroup(store: PipelineStore, knowledge: Knowledge[], unresolved: { ids: Set<string>; sources: Set<string> }, db: KnowledgeDb | null): boolean {
+    return knowledge.some(row => unresolved.ids.has(row.id)) || [...new Set(knowledge.flatMap(row => row.sources.map(source => source.documentId)))].filter(Boolean).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 : knowledge.some(row => row.sources.some(evidence => evidence.documentId === id && evidence.toVersion !== undefined && evidence.toVersion !== source?.version))
+    })
+  }
+
+  /** 相关推荐的整库计划。它是增强，所以算不出来时给空表而不是把编译卡住。 */
+  private async relatedPlan(): Promise<Map<string, OrganizeRelatedCandidate[]>> {
+    const plan = new Map<string, OrganizeRelatedCandidate[]>()
+    try {
+      const cards = await this.loadCards()
+      const relations = Object.values(await this.readExtractedRelations()).flat()
+      for (const [key, entries] of planRelated(cards, relations, await this.projectedRelated(cards))) {
+        if (entries.length > 0) plan.set(key, entries.map(entry => ({ title: entry.title, entityType: entry.entityType, reason: entry.reason })))
+      }
+    } catch { /* 增强项：算不出来就不给清单 */ }
+    return plan
+  }
+
+  /**
+   * 一个分组的**事实指纹**：只有它变了才需要重新成卡。
+   *
+   * 抽成一处是因为它有**两个**调用点：阶段开始时的全库快照，与单组写回之前的复查。
+   * 两处必须用同一个表达式，否则「什么算变化」就有两套说法。
+   */
+  private pipelineGroupFingerprint(knowledge: Knowledge[], context: PipelineContext): string {
+    return contentHashOf(JSON.stringify({ knowledge: 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 }))
+  }
+
+  /**
+   * **只读这一组**的事实指纹，写回之前复查用。
+   *
+   * 快照在阶段内是稳定的，但那有个前提：写入者都走同一条串行队列。别的进程、或同一个库的
+   * 另一条路径（强制重归一复用同一个检查点 id、诊断载入示例、删除流程）不受它约束 ——
+   * 那时「分组的知识行变了，而 head 指针没变」是可能的，只看 head 会漏掉，于是拿陈旧的
+   * 行去写卡片（丢更新）。这里按坐标只读这一组，代价与该组的知识条数成正比，不扫全库。
+   */
+  private async freshGroupFingerprint(coordinate: CardCoordinate, context: PipelineContext, db: KnowledgeDb): Promise<string> {
+    const store = await this.knowledgeStore()
+    if (!store) return ''
+    const raw: Knowledge[] = []
+    for (let offset = 0;; offset += 500) {
+      const page = await store.list({ objectId: coordinate.objectId, actionId: coordinate.actionId, sceneId: coordinate.sceneId, excludeWithdrawn: true, limit: 500, offset })
+      raw.push(...page.knowledge)
+      if (offset + page.knowledge.length >= page.total) break
+    }
+    // 只读这一组**用到**的那些来源正文，而不是全库的。
+    const documentIds = [...new Set(raw.flatMap(row => row.sources.map(source => source.documentId)).filter(Boolean))]
+    const bodies = new Map<string, { version: number; content: string }>()
+    for (const id of documentIds) {
+      const source = db.source(id)
+      if (source) bodies.set(id, { version: source.version, content: source.record.content })
+    }
+    const rows = raw
+      .filter(row => row.status !== 'deprecated')
+      .map(row => assessKnowledgeEvidence(row, db, bodies))
+      .map(row => ({ ...row, sources: row.sources.filter(source => !source.withdrawn && source.evidenceStatus !== 'missing') }))
+      .filter(row => row.sources.length > 0)
+    return this.pipelineGroupFingerprint(rows, context)
+  }
+
+  /**
+   * 物化阶段的**一次**全库快照。
+   *
+   * 逐组现算会变成 O(组数 × 语料)：每个分组要扫 4 遍全库（三次分组、一次知识），
+   * 再加上每组一次图片分发与一次相关推荐 —— 几百张卡时单线程跑不完。这里全部算一次。
+   */
+  private async materializationSnapshot(store: PipelineStore, context: PipelineContext, options: { plans?: boolean } = {}): Promise<MaterializationSnapshot> {
+    /**
+     * `plans: false` 给**只读状态**的调用方（`pipelineStatus`）：它只要 groups / blocked /
+     * 各类计数，而图片分发与相关推荐是整库计算（全部来源正文 + 全部卡片 + 关系投影），
+     * 让它跟着 2.5 秒一次的状态轮询跑，等于把整个语料每 2.5 秒重算一遍。
+     */
+    const plans = options.plans !== false
+    const unresolved = store.unresolvedKnowledge()
+    const grouped = new Map<string, { coordinate: CardCoordinate; knowledge: Knowledge[] }>()
+    let blockedAmbiguous = 0
+    let blockedAwaitingNormalize = 0
+    const groupFor = (coordinate: CardCoordinate) => {
+      const key = coordinateKeyOf(coordinate)
+      if (!grouped.has(key)) grouped.set(key, { coordinate, knowledge: [] })
+      return grouped.get(key)!
+    }
+    for (const row of await this.activePipelineKnowledge()) {
+      const coordinate = { objectId: row.objectId, actionId: row.actionId, sceneId: row.sceneId }
+      if (coordinateIsEmpty(coordinate)) { blockedAmbiguous += 1; continue }
+      groupFor(coordinate).knowledge.push(row)
+    }
+    const db = await this.storeHandle()
+    const events = 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 = events.get(key) ?? []
+      bucket.push(event)
+      events.set(key, bucket)
+    }
+    const cards = await this.loadCards()
+    const byCoordinate = new Map(cards.filter(card => card.coordinate).map(card => [coordinateKeyOf(card.coordinate!), card]))
+    const groups: MaterializationGroup[] = []
+    const knowledge = new Map<string, Knowledge[]>()
+    for (const [key, value] of grouped) {
+      const names = await this.coordinateNames(value.coordinate)
+      const existing = byCoordinate.get(key)
+      // Event 只作为卡片引用；它的增删和正文变化不得触发 Knowledge 重新组织。
+      const fingerprint = this.pipelineGroupFingerprint(value.knowledge, context)
+      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 = this.needsNormalizationForGroup(store, value.knowledge, unresolved, db)
+      if (needsNormalization) blockedAwaitingNormalize += value.knowledge.length
+      knowledge.set(key, value.knowledge)
+      groups.push({ key, title: existing?.title ?? cardNameFor(names.object || null, names.action || null, names.scene || null), coordinate: value.coordinate, knowledgeCount: value.knowledge.length, eventCount: events.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 || grouped.has(coordinateKeyOf(card.coordinate)) || !store.materialization(coordinateKeyOf(card.coordinate)) || card.status === 'deprecated') continue
+      groups.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' })
+    }
+    const sources = plans ? (await this.loadSources()).map(source => ({ sourceId: source.sourceId, content: source.content })) : []
+    const imagePlan = plans
+      ? planSourceImages({
+        cards: groups.filter(item => item.state !== 'withdrawn').map(item => ({ key: item.key, content: (knowledge.get(item.key) ?? []).map(row => row.text).join('\n\n'), sourceRefs: item.sourceIds })),
+        sources,
+      })
+      : { byCard: new Map<string, SourceImage[]>() }
+    /**
+     * 相关推荐是按**卡片身份**（`type:entityId`）算的，而分组键是坐标 —— 两套键永远对不上，
+     * 所以必须在这里把身份映射到分组键。少了这一步，`organizeCard` 拿不到「可引用的邻居」，
+     * 而模型一旦照样写出 `[[名字]]`，`checkOrganize` 会判 `ORGANIZE_UNKNOWN_REFERENCE`、
+     * 整组物化失败（卡片永远写不出来）。
+     *
+     * 只对**已经有卡片**的分组建映射：新建的卡片在相关计划里本来就不存在（与旧行为一致）。
+     * 键用的是卡片自己的类型，与 `relatedForCard(existing)` 一致。
+     */
+    const relatedByKey = new Map<string, OrganizeRelatedCandidate[]>()
+    if (plans) {
+      const plan = await this.relatedPlan()
+      for (const [key, entries] of relatedByGroupKey(groups, groupKey => {
+        const card = byCoordinate.get(groupKey)
+        return card === undefined ? undefined : cardKey(card)
+      }, plan)) {
+        relatedByKey.set(key, entries)
+      }
+    }
+    return {
+      groups: groups.sort((a, b) => a.title.localeCompare(b.title)),
+      blocked: blockedAmbiguous + blockedAwaitingNormalize,
+      blockedAmbiguous, blockedAwaitingNormalize,
+      knowledge, events, sources, images: imagePlan.byCard, related: relatedByKey,
+    }
+  }
+
+  private async materializePipelineGroup(store: PipelineStore, group: MaterializationGroup, context: PipelineContext, output: (text: string) => void, snapshot: MaterializationSnapshot): Promise<void> {
+    const db = await this.storeHandle()
+    if (!db) throw new Error('知识库不可用')
+    /**
+     * 复查读**同一份快照**：语料在物化阶段内不会变（归一排在编译队列的后面），
+     * 所以分组指纹是稳定的；这里只对目标组重算「是否等待归一」。
+     * 会变的是人工裁决 —— 那一条在写回之前单独重读（见下面的 `statusAtWrite`）。
+     */
+    const known = snapshot.groups.find(item => item.key === group.key)
+    if (!known || known.fingerprint !== group.fingerprint) throw new Error('卡片分组在处理期间已变化，请刷新并重试')
+    const knowledge = snapshot.knowledge.get(group.key) ?? []
+    if (this.needsNormalizationForGroup(store, knowledge, store.unresolvedKnowledge(), db)) throw new Error(known.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
+      /**
+       * 撤回也要过同一道人工裁决的闸门（0070）：这一条原来在它**后面**才判，
+       * 于是「有人在处理期间给这张卡做了 review / 停用」会被 `{...existing, status:'deprecated'}`
+       * 静默覆盖。
+       */
+      const statusBeforeDeprecate = (await this.readCard(existing.entityId))?.status
+      if (statusBeforeDeprecate === undefined) throw new Error('卡片在处理期间已被删除，本次物化未提交，请刷新后重试')
+      if (statusBeforeDeprecate !== existing.status) throw new Error(`卡片在处理期间被人工改动（状态 ${existing.status} → ${statusBeforeDeprecate}），本次物化未提交，请重试`)
+      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)
+      // 停用也是一次物化：卡片从可召回里退出，这一步发生过，就该留一条轨迹。
+      await this.recordMaterializeTrajectory({
+        group, action: 'withdrawn', knowledge: [],
+        card: { id: existing.entityId, title: existing.title, status: 'deprecated', characters: existing.content.length, events: 0, images: 0 },
+        organizeUsed: false, related: [], context,
+      }).catch(() => undefined)
+      return
+    }
+    const events = snapshot.events.get(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 images = snapshot.images.get(group.key) ?? []
+    const related = existing && snapshot.related.has(group.key) ? { related: snapshot.related.get(group.key)! } : {}
+    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)
+    /**
+     * 冻结的是这一组的事实，而且要在**写之前**再核一次（0070）。
+     *
+     * 两条都要：斜杠前那条查的是「来源是不是等归一」（head 指针级别），它看不见
+     * 「只有知识行变了」；这条按坐标重算整组指纹，能把那种变化也挡住。
+     */
+    if (this.needsNormalizationForGroup(store, knowledge, store.unresolvedKnowledge(), db)) throw new Error('卡片组织期间事实发生变化，结果未提交，请重试')
+    if (await this.freshGroupFingerprint(group.coordinate, context, db) !== group.fingerprint) throw new Error('卡片分组在处理期间事实发生了变化，结果未提交，请重试')
+    if (this.closed) throw new Error('知识库已关闭，本次物化未提交')
+    /**
+     * 状态必须**在写之前**重读，并且和读到的旧值比对。
+     *
+     * `existing` 是在模型调用（`organizeCard`，秒到几十秒）**之前**读的，而 `status` 是
+     * 显式传下去的 —— `writeCard` 的「不传 = 保留库里已有的」保护因此不生效。用户在
+     * 这段时间里点了「停用」，旧值会把人工裁决静默覆盖掉，卡片又回到索引里，
+     * 而且没有任何地方报错。所以：值变了就**拒绝提交**，让人重试，而不是猜哪个对。
+     */
+    const statusAtWrite = entityId ? (await this.readCard(entityId))?.status : undefined
+    // 「卡片没了」与「状态被改了」是两件事：前者要重建成新卡，后者要人重试。分开说。
+    if (existing !== undefined && statusAtWrite === undefined) throw new Error('卡片在处理期间已被删除，本次物化未提交，请刷新后重试')
+    if (statusAtWrite !== existing?.status) {
+      throw new Error(`卡片在处理期间被人工改动（状态 ${existing?.status ?? '未知'} → ${statusAtWrite ?? '未知'}），本次物化未提交，请重试`)
+    }
+    const written = await this.writeCard({ entityType, entityId, title, content, summary, sourceRefs: group.sourceIds, status: statusAtWrite === 'deprecated' ? 'unreviewed' : statusAtWrite ?? '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)
+    /**
+     * 卡片已经写好了，轨迹落不下来不该把它判失败（同归一那条理由）。所以这里吞掉异常 ——
+     * 但**不吞在别处**：写卡失败仍然抛。
+     */
+    await this.recordMaterializeTrajectory({
+      group,
+      action: existing === undefined ? 'created' : 'updated',
+      knowledge,
+      placements,
+      organizeUsed: Boolean(context.organize && knowledge.length > 0),
+      ...(layoutOf(metadata) ? { layout: layoutOf(metadata)! } : {}),
+      related: snapshot.related.get(group.key) ?? [],
+      card: {
+        id: entityId,
+        title,
+        status: statusAtWrite === 'deprecated' ? 'unreviewed' : statusAtWrite ?? 'unreviewed',
+        characters: content.length,
+        events: eventIds.length,
+        images: images.length,
+      },
+      context,
+    }).catch(() => undefined)
+  }
+
+  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 }
+    }))
+    // 状态查询不要图片分发与相关推荐：它每 2.5 秒被轮询一次，而那两项是整库计算。
+    const { groups, blocked } = await this.materializationSnapshot(pipeline.store, context, { plans: false })
+    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 }
+  }
+
+  /** 轨迹列表（新→旧，不含报告本体）。`stage` 省略 = 三段一起。 */
+  async listExtractionRuns(query: { docId?: string; stage?: TrajectoryStage; limit?: number; offset?: number } = {}): Promise<ExtractionRunPage | null> {
     const store = await this.extractionRuns()
     if (store === null) return null
     try { return await store.list(query) } catch { return null }
@@ -8271,11 +8980,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 +9015,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 +9163,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)
@@ -9132,7 +9843,7 @@ export class KnowledgeRuntime {
     if (derived === null) return { ranking: [], rows: [], diagnostic: { route: 'fts', status: 'degraded', reason: '当前 Node 没有 node:sqlite（需要 22.5+），关键词路已降级' } }
     if (!(captured?.ready ?? derived.hasFts())) return { ranking: [], rows: [], diagnostic: { route: 'fts', status: 'degraded', reason: '关键词索引还没建（在 derived.db 里），先编译一次' } }
     try {
-      const found = (captured?.hits ?? derived.searchFts(query, pool)).filter(hit => eligibleIds.has(hit.unitId))
+      const found = (captured?.hits ?? derived.searchFts(query, pool, eligibleIds)).filter(hit => eligibleIds.has(hit.unitId))
       /**
        * 覆盖率门槛（见 `MIN_QUERY_COVERAGE`）：只蹭到一两个高频单字的命中在这里淘汰，
        * 于是「整批都弱」也能弃答 —— 这是相对阈值做不到的那一半。
@@ -9426,7 +10137,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 +10153,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 +10247,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)
@@ -9559,7 +10273,6 @@ export class KnowledgeRuntime {
       }
     }
     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
@@ -9589,6 +10302,15 @@ export class KnowledgeRuntime {
     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))
+    /**
+     * 关键词路的可见性必须在 **SQL 里、在 LIMIT 之前**收窄。
+     *
+     * 原来这里是先 `LIMIT candidatePool` 再在 JS 里 `filter(eligibleIds)`：删除或停用
+     * 卡片之后索引不会立刻重建，那些死 unitId 仍占着候选位，把能用的候选挤出窗口 ——
+     * 关键词路于是报「0 命中」，整次召回按弃答处理（面板上也看不出原因）。
+     * 向量路一直是先过滤再取 top-k（见下面的扫描循环），这里是它漏掉的那一半。
+     */
+    const capturedFts = { ready: derived?.hasFts() ?? false, hits: derived?.searchFts(query, candidatePool, eligibleIds) ?? [] }
     const queryTerms = [...new Set(segment(query))]
     const warnings: string[] = []
     // 一份 SourceRaw 语料，两处要用：关键词路的**查询词覆盖率**必须对着「建索引时那份
@@ -9700,7 +10422,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 +10431,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()