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

package/lib/types/runtime.js

@@ -13,15 +13,18 @@ import { MAX_LOG_ITEMS, OperationLog, operationId } from './oplog.js';
 import { ExtractionRunStore, extractionRunId } from './extraction-runs.js';
 import { AxisRegistry, normalizeAxisName } from './axis-registry.js';
 import { KNOWLEDGE_STATE_LABEL, KnowledgeStore } from './knowledge.js';
-import { compositeEventIdentity, eventEntityFromRecords } from './events.js';
+import { compositeEventIdentity, eventEntityFromRecords, stripEventReferenceSection } from './events.js';
 import { buildAliasIndex, candidateEntityId, extractCandidates, normalizeCandidates, RELATES_TO } from './extract.js';
 import { skeletonBody } from './extract-model.js';
-import { applyTrialAxisResolution, normalizeKnowledge, runWikiTrial, trialSummary } from './wiki-trial.js';
-import { candidatesFromReport, coordinateIdsOf } from './wiki-materialize.js';
+import { applyTrialAxisResolution, cardNameFor, normalizeKnowledge, runWikiTrial, trialSummary } from './wiki-trial.js';
+import { EXTRACTION_CONTRACT_VERSION } from './extract-table.js';
+import { KnowledgePipeline } from './pipeline/engine.js';
+import { PipelineStore } from './pipeline/store.js';
+import { candidatesFromReport, coordinateIdsOf, coordinateIsEmpty } from './wiki-materialize.js';
 import { buildOrganizePrompt, buildOrganizeSystem, checkOrganize, citationsFrom, layoutHash, layoutOf, parseOrganize, placementsOf, renderFootnoteDefinitions, renderOrganizeBody, } from './card-organize.js';
 import { FTS_FILE, loadSqlite, segment } from './fts.js';
 import { attachImagesToKnowledge, insertImage, planSourceImages } from './source-images.js';
-import { buildWikiIndex, cardKey, deadLinksOf, planRelated, relatedEntriesOf, stripRelatedSection, RELATED_METADATA_KEY, } from './wiki-finalize.js';
+import { buildWikiIndex, cardKey, deadLinksOf, planRelated, relatedByGroupKey, relatedEntriesOf, stripRelatedSection, RELATED_METADATA_KEY, } from './wiki-finalize.js';
 import { applyRerank, applyThreshold, evidenceExcerpts, graphBoost, matchOf, noteIndexText, reviewWeight, rrfFuse, tokenSet } from './recall-rank.js';
 import { ASSETS_DIR, KNOWLEDGE_DB_FILE, PUBLISHED_IMAGE_MARKER, SOURCE_RAW_DIR, defaultAgentRoot, knowledgeBaseRoot } from './layout.js';
 import { KnowledgeDb } from './store/knowledge-db.js';
@@ -233,6 +236,15 @@ const RRF_K = 60;
 const RRF_WEIGHTS = { coordinate: 0.9, relation: 0.45, fts: 0.3, vector: 0.7, graph: 0.2 };
 /** 图谱只是 boost，不是路：它的权重只作用在**已经在候选池里**的条目上（见 `graphBoost`）。 */
 const GRAPH_BOOST_WEIGHT = RRF_WEIGHTS.graph;
+/**
+ * 重排失败后的冷却时间。
+ *
+ * 失败要先记住，否则每次召回都会重新拉起一个注定失败的 worker（那是「秒级重试」的代价）。
+ * 但**不能永久记住**：一次超时是暂态，而写死之后 `rerankNotes` 会在开头直接返回，
+ * 于是这个标志自我封闭 —— 只有换模型、重载家当或人工重跑自检才能清掉。带上冷却，
+ * 第一次失败仍然如实报（有生产门时仍然明确失败），之后每 30 秒给一次自愈机会。
+ */
+const RERANK_RETRY_COOLDOWN_MS = 30_000;
 /**
  * 编码器健康门的判据：两段无关文本的余弦必须低于它。
  *
@@ -684,38 +696,6 @@ function appendExtracted(existing, additions) {
     }
     return content;
 }
-/** 坐标 WikiCard 的事件摘要段由 Event 引用派生；全文与时间线留在独立 Event 实体。 */
-function withEventReferences(content, rawRefs, eventsById) {
-    let refs = [];
-    if (Array.isArray(rawRefs))
-        refs = rawRefs.filter((item) => typeof item === 'string');
-    else if (typeof rawRefs === 'string') {
-        try {
-            const parsed = JSON.parse(rawRefs);
-            if (Array.isArray(parsed))
-                refs = parsed.filter((item) => 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 !== 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, incoming) {
     if (!existing)
@@ -1008,9 +988,10 @@ function markdownImageRefs(content) {
  *    `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 没有对应概念，但也不该混进上面那组公开字段里。
@@ -1043,8 +1024,6 @@ function sourceFrontMatter(record, provenance) {
             ...(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;
@@ -1551,6 +1530,9 @@ export class KnowledgeRuntime {
     /** 抽取轨迹（`<memoryDir>/extraction-runs.sqlite`）。同一个懒打开的理由。 */
     extractionRunsStore = null;
     extractionRunsReady = null;
+    closed = false;
+    pipelineEngine;
+    pipelineOpening;
     /** 轴注册表（`<memoryDir>/knowledge.sqlite`）。与抽取轨迹同一个懒打开的理由。 */
     axesStore = null;
     axesReady = null;
@@ -1630,7 +1612,7 @@ export class KnowledgeRuntime {
     embeddingWorkerFingerprint;
     /** Separate process so a rerank model failure cannot take embeddings down. */
     rerankWorker = null;
-    /** Cache the first rerank failure; do not respawn a doomed model per recall. */
+    /** Cache the last rerank failure with its time; see `RERANK_RETRY_COOLDOWN_MS`. */
     rerankUnavailable;
     /** 解析后的 Python 解释器路径（配置为空时从家当目录解析）。 */
     pythonPath;
@@ -2292,6 +2274,10 @@ export class KnowledgeRuntime {
         return { vectors, device };
     }
     close() {
+        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;
@@ -2299,6 +2285,13 @@ export class KnowledgeRuntime {
             task.pauseRequested = false;
             task.resume?.();
         }
+        if (this.compilePending > 0) {
+            void this.compileTail.finally(() => this.closeStores());
+            return;
+        }
+        this.closeStores();
+    }
+    closeStores() {
         this.embeddingWorker?.close();
         this.embeddingWorker = null;
         this.rerankWorker?.close();
@@ -2680,39 +2673,26 @@ export class KnowledgeRuntime {
         if (written.length === 0) {
             return failure({ ...empty, failed, attempted: items.length }, 'IMPORT_ALL_FAILED', `${items.length} 份来源全部写入失败，没有任何东西进入知识库`, true, failed[0] ? `第一份的原因：${failed[0].message}` : undefined);
         }
-        /**
-         * 编译。**只要有一份写成就编**：成功的那几份已经是库里的知识，
-         * 「因为同批里有一份失败就不编」等于把已经进来的知识又挡在门外一次。
-         */
         let compile = null;
-        if (input.compile !== false) {
-            let rebuilt;
+        if (input.compile === true) {
             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;
+                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);
@@ -2984,6 +2964,15 @@ export class KnowledgeRuntime {
      * 失败一律返回 `null`，**不抛** —— 「知识库不可用」是一条要显示的结论，不是一个异常。
      */
     storeHandleOpening;
+    /**
+     * 知识存储现在可用吗（0070）。
+     *
+     * 读路径需要它把「确认是空」与「读不到」分开：`loadCards()` 在存储不可用时返回 `[]`，
+     * 而调用方据此做写决定（例如诊断的旧格式迁移）就会把一次读故障变成一次污染写。
+     */
+    async knowledgeStoreAvailable() {
+        return (await this.storeHandle()) !== null;
+    }
     async storeHandle() {
         if (this.store !== undefined)
             return this.store;
@@ -3894,10 +3883,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) {
@@ -4075,7 +4065,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,
@@ -4086,7 +4077,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') {
@@ -4097,7 +4088,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,
@@ -4183,6 +4174,7 @@ export class KnowledgeRuntime {
     }
     async organizeCard(input) {
         const context = await this.organizeContext({
+            knowledge: input.knowledge,
             cardTitle: input.cardTitle,
             coordinate: input.coordinate,
             profileId: input.profileId,
@@ -4511,7 +4503,16 @@ export class KnowledgeRuntime {
         return cards.flatMap(card => this.compileCardNotes(card));
     }
     compileCardNotes(card) {
-        if (card.status === 'problem')
+        /**
+         * **只排除 `deprecated`，不排除 `problem`。**
+         *
+         * `problem` 是人工标注的「这张卡有问题」，它仍然是知识，而召回契约里的
+         * `include_problems` 是一个**读取时**的开关（见 `recall` 里 eligible 的那一行）。
+         * 在编译期就把它的 note 丢掉，等于把这个开关变成死参数：无论传什么，编译产物
+         * 里根本没有它的 note，FTS / 向量索引里也没有。所以索引层保留，过滤留给读路径。
+         * `deprecated` 不同 —— 它是退役，编译与读取两层都该排除。
+         */
+        if (card.status === 'deprecated')
             return [];
         const notes = [];
         /**
@@ -4529,7 +4530,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}`;
@@ -4562,13 +4563,20 @@ export class KnowledgeRuntime {
     /** 1-hop neighbourhood of a set of wiki cards inside the compiled graph. */
     oneHopGraph(keys, includeProblem, graph = this.graph) {
         const visible = (node) => includeProblem || node.status !== 'problem';
-        const edges = this.graph.edges.filter(edge => keys.has(String(edge.from)) || keys.has(String(edge.to))).slice(0, 50);
+        /**
+         * 必须读**传进来的** `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);
@@ -4595,10 +4603,11 @@ export class KnowledgeRuntime {
         const provider = this.config.rerankProvider;
         if (provider === 'none')
             return { hits, result: { status: 'skipped', provider, threshold } };
-        if (hits.length < 2)
+        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}` };
+        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');
@@ -4612,6 +4621,8 @@ export class KnowledgeRuntime {
             const raw = Array.isArray(response?.scores) ? response.scores.map(Number) : [];
             const outcome = applyRerank(raw, hits, threshold);
             const vocabSize = Number(response?.vocabSize);
+            // 一次成功的推理就是这条缓存的反证：清掉它，别让暂态失败变成会话级残疾。
+            this.rerankUnavailable = undefined;
             return {
                 hits: outcome.kept,
                 scored: outcome.scored,
@@ -4629,7 +4640,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}` };
         }
     }
@@ -4843,7 +4854,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);
@@ -4892,7 +4902,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
@@ -4986,7 +4996,7 @@ export class KnowledgeRuntime {
             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);
@@ -5035,8 +5045,9 @@ export class KnowledgeRuntime {
          * 用的输入与收尾阶段那个相关块**完全相同**（同一份 `relations` + 同一个坐标投影），
          * 所以「正文里能提到谁」与「末尾相关块列了谁」不会是两个答案。
          */
-        const relatedPlan = planRelated(input.cards, input.relations, await this.projectedRelated(input.cards));
-        const withCoordinate = input.cards
+        const cardsWithoutLegacyEventSections = input.cards.map(card => ({ ...card, content: stripEventReferenceSection(card.content) }));
+        const relatedPlan = planRelated(cardsWithoutLegacyEventSections, input.relations, await this.projectedRelated(input.cards));
+        const withCoordinate = cardsWithoutLegacyEventSections
             .filter(card => card.coordinate !== undefined)
             .sort((left, right) => left.entityId.localeCompare(right.entityId));
         if (withCoordinate.length === 0)
@@ -5366,7 +5377,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)
+            outcome.warnings.push(...ingested.warnings);
+            if (ingested.skipped > 0 || ingested.failures > 0 || eventIngested.skipped > 0)
                 extractionComplete = false;
             // 落位要用库内的 id。这一份报告里每一条知识的映射都并进整轮那一份 ——
             // 后面的来源可能命中同一张卡，那时落位指的行也得是活的。
@@ -5674,7 +5686,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()) {
@@ -6288,7 +6300,7 @@ export class KnowledgeRuntime {
         if (store === null)
             return { saved: false, why: '抽取轨迹库不可用（需要 Node 22.5+ 的 node:sqlite）' };
         const report = input.report;
-        const id = input.id?.trim() || extractionRunId();
+        const id = input.id?.trim() || extractionRunId(input.stage);
         const record = {
             id,
             kb: this.rootDir,
@@ -6300,6 +6312,7 @@ export class KnowledgeRuntime {
             ...(report?.model?.why ? { modelWhy: report.model.why } : {}),
             summary: input.summary,
             hasReport: true,
+            stage: input.stage ?? 'extract',
             report: input.report,
         };
         try {
@@ -6310,6 +6323,135 @@ export class KnowledgeRuntime {
             return { saved: false, why: cause instanceof Error ? cause.message : String(cause) };
         }
     }
+    /**
+     * 归一段的轨迹（2026-10-18）。
+     *
+     * 这一段的产物以前只留在两处：任务里的流式输出（刷新就没），和事实表里最终写成的行
+     * （只剩结果）。中间那步 —— 「模型给的这 283 个名字里，哪些命中了已有实体、哪些新建了
+     * 候选、哪些因为不唯一没猜」—— 跑完就查不到了，而它恰好是坐标错了之后唯一能复盘的东西。
+     *
+     * **复用的那一次不落轨迹**：那一次什么都没做（指纹没变、一条事实都没重写），落一条
+     * 「复用」只会把真正的运行挤出第一页。
+     */
+    async recordNormalizeTrajectory(input) {
+        const report = input.report;
+        const axes = [['object', report.objects], ['action', report.actions], ['scene', report.scenes]].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) => axes.filter(row => row.outcome === outcome).length;
+        const unresolved = new Set(input.unresolvedKnowledgeIds);
+        const payload = {
+            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）：一个卡片分组 → 一张卡。
+     *
+     * 这一段的产物是卡片本身，所以「卡里有什么」已经查得到；查不到的是**这一次为什么这么排**：
+     * 分组指纹、卡片组织的结论（模型排的还是机械拼的）、进了哪几条知识、正文里为什么链到
+     * 那一张卡。这些是改完提示词、想知道「这次和上次差在哪」时唯一能对着看的东西。
+     *
+     * 粒度是**一组**而不是一个任务：一张卡组织失败，不该让同批其它卡的轨迹一起消失。
+     */
+    async recordMaterializeTrajectory(input) {
+        const 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 = {
+            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 身份。
      *
@@ -6390,6 +6532,7 @@ export class KnowledgeRuntime {
      * 不能当成「没命中」。
      */
     async resolveTrialAxisSet(input) {
+        const resolve = (value) => this.resolveAxisMention({ ...value, registry: input.registry });
         const groups = [
             { kind: 'object', key: 'objects' },
             { kind: 'action', key: 'actions' },
@@ -6400,7 +6543,7 @@ export class KnowledgeRuntime {
         const axisKey = (kind, mention) => `${kind}\u0000${normalizeAxisName(mention)}`;
         const supplementalEntries = { 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 => [
@@ -6455,7 +6598,7 @@ export class KnowledgeRuntime {
                 const key = axisKey(group.kind, axis.name);
                 let lookup;
                 try {
-                    lookup = await this.resolveAxisMention({
+                    lookup = await resolve({
                         kind: group.kind,
                         mention: axis.name,
                         parentMention: axis.parentMention,
@@ -6519,7 +6662,7 @@ export class KnowledgeRuntime {
                     continue;
                 }
                 // 没有可供模型比较的现有候选时，沿用注册表的新建候选路径。
-                const created = await this.resolveAxisMention({
+                const created = await resolve({
                     kind: group.kind,
                     mention: axis.name,
                     parentMention: axis.parentMention,
@@ -6629,7 +6772,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,
@@ -6643,7 +6786,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,
@@ -6672,7 +6815,7 @@ export class KnowledgeRuntime {
         };
     }
     async resolveAxisMention(input) {
-        const registry = await this.axisRegistry();
+        const registry = input.registry ?? await this.axisRegistry();
         if (registry === null)
             return null;
         const runId = input.runId ?? '';
@@ -6688,7 +6831,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 } : {}),
@@ -6704,11 +6847,11 @@ export class KnowledgeRuntime {
      * 「是已有的某个东西」而那个名字在库里指两个实体时，把它当成指认就等于替人做了
      * 「哪一个」的决定 —— 而注册表的规矩是「不唯一就不猜」。
      */
-    async axisIdByName(kind, mention) {
+    async axisIdByName(kind, mention, supplied) {
         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 {
@@ -7022,7 +7165,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 个文件」）又把它算成
@@ -7059,7 +7202,7 @@ export class KnowledgeRuntime {
     }
     /**
      * 还有没有人在引用这个桶 —— 判据是来源正文、来源 front matter 的 `metadata.assets`、
-     * 卡片正文出现过 `_assets/<bucket>/`，或者它是 `images.publish` 写入的独立图床图片。
+     * 卡片正文出现过 `_assets/<bucket>/`，或者它是 `image_publish` 写入的独立图床图片。
      * 独立图片没有来源/卡片引用是正常状态，必须保留。
      *
      * 为什么三处都要看：桶名是**内容哈希的前 12 位**（`convert/ingest.ts`），不是来源 id。
@@ -7103,7 +7246,7 @@ export class KnowledgeRuntime {
         return unreferenced;
     }
     /**
-     * `images.publish` 的图片不需要被来源或卡片引用。新写入的桶有明确标记；同时兼容
+     * `image_publish` 的图片不需要被来源或卡片引用。新写入的桶有明确标记；同时兼容
      * 标记加入前已发布的图片：它们以图片自身的 SHA-256 前 12 位作为桶名。
      */
     async isPublishedImageBucket(name) {
@@ -7111,7 +7254,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);
@@ -7362,11 +7505,13 @@ export class KnowledgeRuntime {
     async ingestTrialKnowledge(input) {
         const store = await this.knowledgeStore();
         if (store === null)
-            return { saved: 0, merged: 0, skipped: input.knowledge.length, ids: {} };
+            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 = [];
         const ids = {};
         for (const item of input.knowledge) {
             const usable = item.sources.filter(source => source.found);
@@ -7405,11 +7550,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 };
     }
     /**
      * 把抽取到的 Event 写成独立事件实体，并按身份规则追加来源记录。
@@ -7461,14 +7615,12 @@ export class KnowledgeRuntime {
             refs.push(event.id);
             eventsByCoordinate.set(key, refs);
         }
-        const eventIndex = new Map(events.map(event => [event.id, event]));
         const warnings = [];
         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 = [];
             let oldRefsValid = false;
@@ -7486,13 +7638,17 @@ export class KnowledgeRuntime {
                 oldRefs = oldRaw.filter((item) => 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)
+            if (!refsChanged && !contentChanged) {
+                db.setCardEvents(card.entityId, refs);
                 continue;
-            if (!oldRefsValid && refs.length === 0 && oldRaw === undefined && !contentChanged)
+            }
+            if (!oldRefsValid && refs.length === 0 && oldRaw === undefined && !contentChanged) {
+                db.setCardEvents(card.entityId, refs);
                 continue;
+            }
             const written = await this.writeCard({
                 ...card,
                 sourceRefs: card.sourceRefs,
@@ -7501,9 +7657,11 @@ export class KnowledgeRuntime {
                 origin: 'internal',
             });
             if (written.ok === false)
-                warnings.push(`坐标 WikiCard ${card.title} 的 Event 聚合视图未更新：${written.error.message}`);
-            else
+                warnings.push(`WikiCard ${card.title} 的 Event 引用未更新：${written.error.message}`);
+            else {
+                db.setCardEvents(card.entityId, refs);
                 updated += 1;
+            }
         }
         return { updated, warnings };
     }
@@ -7524,10 +7682,6 @@ export class KnowledgeRuntime {
         const ids = {};
         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 = {
                 id: event.id,
                 identityKey: event.identityKey,
@@ -7629,8 +7783,12 @@ export class KnowledgeRuntime {
                 saved += 1;
         }
         for (const state of states.values()) {
-            if (!state.dirty || state.records.length === 0)
+            if (!state.dirty)
+                continue;
+            if (state.records.length === 0) {
+                db.removeEvent(state.id);
                 continue;
+            }
             const records = state.records;
             const entity = eventEntityFromRecords({
                 id: state.id,
@@ -7650,7 +7808,565 @@ export class KnowledgeRuntime {
         }
         return { saved, merged, skipped, ids, warnings };
     }
-    /** 抽取轨迹列表（新→旧，不含报告本体）。 */
+    /** The stage runner shares this base's existing writer queue and audit database. */
+    async pipeline() {
+        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),
+                build: async (taskId, checkpoint) => {
+                    let result;
+                    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;
+    }
+    async pipelineSources() {
+        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));
+    }
+    async pipelineSource(sourceId) {
+        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` 存「补判之后」的快照是同一条规则，不是两套。
+     */
+    async pipelineExtractionFingerprint(source, context) {
+        const axes = await this.axisPromptBlock(source.content);
+        const text = normalizeAxisName(source.content);
+        const relevant = ['object', 'action', 'scene'].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 } }));
+    }
+    async normalizationFingerprint(checkpoint, context) {
+        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 }));
+    }
+    async normalizePipelineSource(store, source, checkpoint, context, force, output) {
+        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 = 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]].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();
+        }
+    }
+    async activePipelineKnowledge() {
+        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();
+        for (const row of db.sources())
+            bodies.set(row.record.sourceId, { version: row.version, content: row.record.content });
+        const rows = [];
+        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;
+    }
+    /**
+     * 这一组现在能不能物化（有没有来源变了、新抽取待归一、或坐标还有歧义）。
+     *
+     * 抽成一处是因为它有**两个**调用点：阶段开始时的全量快照，与单组写回之前的复查。
+     * 各写一份的话，「什么算变化」迟早会有两套说法。
+     */
+    needsNormalizationForGroup(store, knowledge, unresolved, db) {
+        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));
+        });
+    }
+    /** 相关推荐的整库计划。它是增强，所以算不出来时给空表而不是把编译卡住。 */
+    async relatedPlan() {
+        const plan = new Map();
+        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;
+    }
+    /**
+     * 一个分组的**事实指纹**：只有它变了才需要重新成卡。
+     *
+     * 抽成一处是因为它有**两个**调用点：阶段开始时的全库快照，与单组写回之前的复查。
+     * 两处必须用同一个表达式，否则「什么算变化」就有两套说法。
+     */
+    pipelineGroupFingerprint(knowledge, context) {
+        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 会漏掉，于是拿陈旧的
+     * 行去写卡片（丢更新）。这里按坐标只读这一组，代价与该组的知识条数成正比，不扫全库。
+     */
+    async freshGroupFingerprint(coordinate, context, db) {
+        const store = await this.knowledgeStore();
+        if (!store)
+            return '';
+        const raw = [];
+        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();
+        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 遍全库（三次分组、一次知识），
+     * 再加上每组一次图片分发与一次相关推荐 —— 几百张卡时单线程跑不完。这里全部算一次。
+     */
+    async materializationSnapshot(store, context, options = {}) {
+        /**
+         * `plans: false` 给**只读状态**的调用方（`pipelineStatus`）：它只要 groups / blocked /
+         * 各类计数，而图片分发与相关推荐是整库计算（全部来源正文 + 全部卡片 + 关系投影），
+         * 让它跟着 2.5 秒一次的状态轮询跑，等于把整个语料每 2.5 秒重算一遍。
+         */
+        const plans = options.plans !== false;
+        const unresolved = store.unresolvedKnowledge();
+        const grouped = new Map();
+        let blockedAmbiguous = 0;
+        let blockedAwaitingNormalize = 0;
+        const groupFor = (coordinate) => {
+            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();
+        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 = [];
+        const knowledge = new Map();
+        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() };
+        /**
+         * 相关推荐是按**卡片身份**（`type:entityId`）算的，而分组键是坐标 —— 两套键永远对不上，
+         * 所以必须在这里把身份映射到分组键。少了这一步，`organizeCard` 拿不到「可引用的邻居」，
+         * 而模型一旦照样写出 `[[名字]]`，`checkOrganize` 会判 `ORGANIZE_UNKNOWN_REFERENCE`、
+         * 整组物化失败（卡片永远写不出来）。
+         *
+         * 只对**已经有卡片**的分组建映射：新建的卡片在相关计划里本来就不存在（与旧行为一致）。
+         * 键用的是卡片自己的类型，与 `relatedForCard(existing)` 一致。
+         */
+        const relatedByKey = new Map();
+        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,
+        };
+    }
+    async materializePipelineGroup(store, group, context, output, snapshot) {
+        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');
+        let title = group.title;
+        let content = `## 知识\n\n${knowledge.map(row => `- ${row.text}`).join('\n')}`;
+        let summary = knowledge[0]?.text ?? '';
+        let placements = knowledge.map((row, index) => ({ knowledgeId: row.id, section: '知识', ordinal: index + 1, origin: 'compiler' }));
+        let metadata = { ...(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() {
+        const pipeline = await this.pipeline();
+        const sources = await this.pipelineSources();
+        const context = { model: this.modelSeamNow(), note: this.extractionNote(), profile: this.organizeProfile(), organize: this.config.cardOrganize, format: 'table' };
+        const rows = 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' : extracted ? 'extracted' : head.extracted ? 'outdated' : 'pending' };
+        }));
+        // 状态查询不要图片分发与相关推荐：它每 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).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 = {}) {
         const store = await this.extractionRuns();
         if (store === null)
@@ -7853,10 +8569,12 @@ export class KnowledgeRuntime {
      * 它」—— 那两件事分别在 `enqueueCompile()` 与 `rebuild()` / `startCompile()` 里。
      */
     async compileOnce(runId, only = 'all', lineage, options = {}) {
-        await this.environmentGuard?.();
+        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);
@@ -7889,6 +8607,7 @@ export class KnowledgeRuntime {
                 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;
             }
@@ -8042,7 +8761,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);
@@ -8717,7 +9436,7 @@ export class KnowledgeRuntime {
         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`）：只蹭到一两个高频单字的命中在这里淘汰，
              * 于是「整批都弱」也能弃答 —— 这是相对阈值做不到的那一半。
@@ -9043,7 +9762,7 @@ export class KnowledgeRuntime {
          * 一次召回十来张卡，而库里可能有上千张。
          */
         try {
-            placements = snapshot?.placements.length ? new Map(snapshot.placements) : store.placementsOf([...new Set(hits.map(hit => hit.entityId))]);
+            placements = snapshot ? new Map(snapshot.placements) : store.placementsOf([...new Set(hits.map(hit => hit.entityId))]);
         }
         catch {
             return;
@@ -9065,7 +9784,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.
@@ -9159,14 +9878,17 @@ export class KnowledgeRuntime {
         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?.();
+            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);
@@ -9188,7 +9910,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
@@ -9220,6 +9941,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 = [];
         // 一份 SourceRaw 语料，两处要用：关键词路的**查询词覆盖率**必须对着「建索引时那份
@@ -9327,7 +10057,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);
@@ -9337,7 +10067,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();
         cards = cards.filter(card => truth?.card(card.entityId) !== undefined && card.sourceRefs.every(ref => truth?.source(ref) !== undefined));