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

package/src/source-evidence.ts

@@ -2,17 +2,24 @@ import type { Knowledge, KnowledgeSource } from './knowledge.js'
 import type { KnowledgeDb } from './store/knowledge-db.js'
 
 /** Checking an evidence anchor does not establish whether a claim is true. */
-export function assessKnowledgeEvidence(knowledge: Knowledge, db: KnowledgeDb): Knowledge {
+/**
+ * `bodies` 是可选的**来源正文预读**（documentId → 当前版本与正文）。批量路径（物化快照）
+ * 一次读完全部来源再传进来，于是每条知识不再各自 join 一次 blob、各做一次整份文档的
+ * flatten 与子串匹配 —— 那是 O(知识条数 × 文档大小)。不传时退回按需读取（单条判定）。
+ */
+export function assessKnowledgeEvidence(knowledge: Knowledge, db: KnowledgeDb, bodies?: ReadonlyMap<string, { version: number; content: string }>): Knowledge {
   return {
     ...knowledge,
-    sources: knowledge.sources.map(source => assessSource(source, db)),
+    sources: knowledge.sources.map(source => assessSource(source, db, bodies)),
   }
 }
 
-function assessSource(source: KnowledgeSource, db: KnowledgeDb): KnowledgeSource {
+function assessSource(source: KnowledgeSource, db: KnowledgeDb, bodies?: ReadonlyMap<string, { version: number; content: string }>): KnowledgeSource {
+  if (source.withdrawn) return { ...source, evidenceStatus: 'historical', quoteInCurrentVersion: false }
   if (!source.documentId) return { ...source, evidenceStatus: 'human' }
-  const head = db.source(source.documentId)
+  const head = bodies?.get(source.documentId) ?? db.source(source.documentId)
   if (!head) return { ...source, evidenceStatus: 'missing', quoteInCurrentVersion: false }
+  const content = 'record' in head ? head.record.content : head.content
   const flatten = (text: string): string => text.replace(/\s+/g, '')
   const quote = flatten(source.quote)
   return {
@@ -20,7 +27,7 @@ function assessSource(source: KnowledgeSource, db: KnowledgeDb): KnowledgeSource
     currentVersion: head.version,
     evidenceStatus: source.toVersion === undefined ? 'unversioned'
       : source.toVersion === head.version ? 'current' : 'historical',
-    quoteInCurrentVersion: quote !== '' && flatten(head.record.content).includes(quote),
+    quoteInCurrentVersion: quote !== '' && flatten(content).includes(quote),
   }
 }
 

package/src/store/axis-references.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto'
 import type { AxisKind } from '../axis-registry.js'
-import { compositeEventIdentity, eventEntityFromRecords, type EventEntity } from '../events.js'
+import { compositeEventIdentity, eventEntityFromRecords, stripEventReferenceSection, type EventEntity } from '../events.js'
 import { cardCoordinateKey, type CardCoordinate } from '../types.js'
 import type { KnowledgeDb, CardKnowledgeRow } from './knowledge-db.js'
 
@@ -28,7 +28,7 @@ export function redirectAxisReferences(db: KnowledgeDb, kind: AxisKind, fromId:
       const eventRefs = [...new Set([...db.cardEventIds(base.card.entityId), ...db.cardEventIds(row.card.entityId)])]
       const card = {
         ...base.card, coordinate: next,
-        content: merged ? `${base.card.content}\n\n${row.card.content}` : row.card.content,
+        content: stripEventReferenceSection(merged ? `${base.card.content}\n\n${row.card.content}` : row.card.content),
         sourceRefs: [...new Set([...base.card.sourceRefs, ...row.card.sourceRefs])],
         annotations: [...new Map([...(base.card.annotations ?? []), ...(row.card.annotations ?? [])].map(annotation => [annotation.id, annotation])).values()],
         metadata: { ...base.card.metadata, layout: undefined, citations: undefined,
@@ -84,7 +84,7 @@ export function redirectAxisReferences(db: KnowledgeDb, kind: AxisKind, fromId:
     }
     if (redirects.size) {
       for (const row of db.cards()) {
-        let content = row.card.content
+        let content = stripEventReferenceSection(row.card.content)
         for (const [from, into] of redirects) content = content.replaceAll(from, into)
         if (content === row.card.content && !affectedCards.has(row.card.entityId)) continue
         const metadata = { ...row.card.metadata, event_refs: JSON.stringify(db.cardEventIds(row.card.entityId)) }

package/src/store/derived.ts

@@ -158,12 +158,29 @@ export class DerivedDb {
     try {
       const owner = readPragma(db, 'application_id')
       const version = readPragma(db, 'user_version')
-      if (userTableCount(db) === 0 && owner === 0) {
+      /**
+       * 属主标记为 0 = 这份文件从来没有被我们的初始化**写完过**。两种来源都要按「无主」处理：
+       *
+       * 1. 全新/空的文件（一张表都没有）；
+       * 2. `schemaSql()` 已经建好表、`PRAGMA application_id` 还没写就被杀掉的那一次
+       *    （崩溃、kill、磁盘满）。第二种原来会落到下面的「属主不对」分支，返回
+       *    `NOT_A_DERIVED_DB` —— 而 `derivedHandle()` 会把这个结论缓存住，于是编译与召回
+       *    **永久**失败，尽管这个文件按定义是可重建的。
+       *
+       * 但不能因此误伤别人的库：只有「文件里所有表都是我们自己建的」才认领重建，
+       * 出现陌生表就仍然拒绝打开（认错库比打不开糟）。
+       */
+      const tables = userTables(db)
+      const foreign = tables.filter(name => !['artifact', 'vector_index', 'fts'].includes(name))
+      if (owner === 0 && foreign.length === 0) {
+        db.exec('DROP TABLE IF EXISTS fts')
+        db.exec('DROP TABLE IF EXISTS artifact')
+        db.exec('DROP TABLE IF EXISTS vector_index')
         db.exec('PRAGMA journal_mode = WAL')
         db.exec(schemaSql())
         db.exec(`PRAGMA application_id = ${DERIVED_DB_APPLICATION_ID}`)
         db.exec(`PRAGMA user_version = ${DERIVED_DB_SCHEMA}`)
-        return { ok: true, db: new DerivedDb(db, file), rebuilt: false }
+        return { ok: true, db: new DerivedDb(db, file), rebuilt: tables.length > 0 }
       }
       if (owner !== DERIVED_DB_APPLICATION_ID) {
         db.close()
@@ -302,11 +319,19 @@ export class DerivedDb {
    * 查询语法错误或索引损坏时**返回空数组而不抛**：关键词路是三条召回路线之一，
    * 它挂了不该把整次召回带走 —— 调用方在诊断里如实说明这一路没结果。
    */
-  searchFts(query: string, limit: number): FtsHit[] {
+  searchFts(query: string, limit: number, eligible?: ReadonlySet<string>): FtsHit[] {
     const expression = matchExpression(query)
     if (expression === null || !this.hasFts()) return []
     try {
-      const rows = this.raw('SELECT unit_id, bm25(fts) AS rank FROM fts WHERE fts MATCH ? ORDER BY rank LIMIT ?').all(expression, limit) as Array<{ unit_id?: unknown; rank?: unknown }>
+      /*
+       * `eligible` 必须进 SQL。先 LIMIT 再在 JS 里过滤，会让已删除/停用卡片的死
+       * unitId 占满候选窗口（索引只在编译时重建，删除不会立刻反映到 fts 表）。
+       * 用 `json_each` 传一个 JSON 数组而不是拼参数列表：一个绑定参数，不受
+       * SQLITE_MAX_VARIABLE_NUMBER 限制。
+       */
+      const rows = (eligible === undefined
+        ? this.raw('SELECT unit_id, bm25(fts) AS rank FROM fts WHERE fts MATCH ? ORDER BY rank LIMIT ?').all(expression, limit)
+        : this.raw('SELECT unit_id, bm25(fts) AS rank FROM fts WHERE fts MATCH ? AND unit_id IN (SELECT value FROM json_each(?)) ORDER BY rank LIMIT ?').all(expression, JSON.stringify([...eligible]), limit)) as Array<{ unit_id?: unknown; rank?: unknown }>
       const parsed = rows
         .map(row => ({ unitId: String(row.unit_id ?? ''), raw: Number(row.rank ?? 0) }))
         .filter(row => row.unitId !== '' && Number.isFinite(row.raw))
@@ -316,6 +341,14 @@ export class DerivedDb {
       const scale = best > 0 ? best : 1
       return parsed.map(row => ({ ...row, score: Math.max(0, Math.min(1, -row.raw / scale)) }))
     } catch {
+      /**
+       * `json_each` 不可用（SQLite 没编 JSON）或索引损坏时，**不能直接返回空**。
+       *
+       * 空数组会被上游读成「这一路没命中」，而实际是「这一路坏了」—— 正是这次要消灭的
+       * 那种静默降级。退回不带资格过滤的两参数查询：结果仍然正确（调用方还会过滤一遍），
+       * 只是候选窗口可能被已删除的条目占掉。真的连那条也失败，才认「没有结果」。
+       */
+      if (eligible !== undefined) return this.searchFts(query, limit)
       return []
     }
   }
@@ -335,7 +368,7 @@ function readPragma(db: SqliteDatabase, name: string): number {
   return typeof first === 'number' ? first : Number(first ?? 0)
 }
 
-function userTableCount(db: SqliteDatabase): number {
-  const rows = db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all() as Array<{ name?: unknown }>
-  return rows.length
+/** 文件里现有的表名。用来判断「这份文件是不是我们建的」。 */
+function userTables(db: SqliteDatabase): string[] {
+  return (db.prepare("SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%'").all() as Array<{ name?: unknown }>).map(row => String(row.name ?? ''))
 }

package/src/store/knowledge-db.ts

@@ -31,6 +31,7 @@ import { createHash } from 'node:crypto'
 import { mkdir } from 'node:fs/promises'
 import { dirname } from 'node:path'
 import type { SqliteDatabase, SqliteStatement } from '../fts.js'
+import { applyRetention } from '../retention.js'
 import { KNOWLEDGE_DB_FILE } from '../layout.js'
 import { cardCoordinateKey, legacyCardStorageKey, type CardCoordinate, type KnowledgeCard, type SourceRaw } from '../types.js'
 import type { EventEntity } from '../events.js'
@@ -445,15 +446,25 @@ function rebuildCardTableForSchemaMigration(db: SqliteDatabase): void {
        head_version, created_at, updated_at, object_id, action_id, scene_id)
     VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
   `)
+  /** 已经用掉的落位键。同坐标多行时后面那些要退回身份键（见下面的说明）。 */
+  const used = new Set<string>()
   for (const row of rows) {
     const entityId = String(row.entity_id ?? '')
     const objectId = String(row.object_id ?? '')
     const actionId = String(row.action_id ?? '')
     const sceneId = String(row.scene_id ?? '')
     const coordinate = coordinateOfRow({ object_id: objectId, action_id: actionId, scene_id: sceneId })
-    const key = coordinate === undefined
+    let key = coordinate === undefined
       ? legacyCardStorageKey(entityId)
       : cardCoordinateKey(coordinate)
+    /**
+     * 同一坐标在旧表里可能有多行（那时还没有坐标唯一约束）。`coordinate_key` 是主键，
+     * 一旦冲突整次迁移就回滚 —— 而迁移在打开库时跑，于是**每次启动都打不开这个库**，
+     * 也没有修复路径。落在后面的那一行退回按 `entityId` 生成的身份键：两张卡都留住，
+     * 坐标冲突交给既有的审计路径去报。`entity_id` 在旧表里是唯一的，所以这个键不会重。
+     */
+    if (used.has(key)) key = legacyCardStorageKey(entityId)
+    used.add(key)
     insert.run(
       key,
       entityId,
@@ -615,6 +626,8 @@ interface ColumnInfo {
   name: string
   notNull: boolean
   hasDefault: boolean
+  /** 主键里的序号（1 起）；0 = 不是主键的一部分。判「是不是同一行」要用它。 */
+  pk: number
 }
 
 /**
@@ -851,6 +864,8 @@ export class KnowledgeTx {
  */
 export class KnowledgeDb {
   private transactionSequence = 0
+  /** 距离上一次保留裁剪又提交了几次写事务。 */
+  private writesSincePrune = 0
   private constructor(private readonly db: SqliteDatabase, readonly file: string) {}
 
   /**
@@ -935,6 +950,8 @@ export class KnowledgeDb {
   }
 
   close(): void {
+    // 关库前收一次尾：否则「最后一次裁剪之后新增的行」会一直留到下次打开。
+    this.pruneRetention()
     try { this.db.close() } catch { /* already closed */ }
   }
 
@@ -971,6 +988,17 @@ export class KnowledgeDb {
       const result = fn(tx)
       this.raw('UPDATE tree SET manifest = ? WHERE op_id = ?').run(tx.manifestJson(), entry.opId)
       this.db.exec(`RELEASE ${savepoint}`)
+      /**
+       * 裁剪**每 50 次写入**做一次，不是每次。
+       *
+       * 每次都做的话，一次卡片写入要额外跑一遍 `ROW_NUMBER()` 按实体分区的窗口（水位以上
+       * 收敛到约 20 版/实体，5000 个实体就是十万行排序）外加一次 blob 引用集比对 ——
+       * 那是把维护成本摊到每一次交互上。每 50 次一次，界面上感觉不到，库也照样有界。
+       */
+      if (++this.writesSincePrune >= 50) {
+        this.writesSincePrune = 0
+        this.pruneRetention()
+      }
       return result
     } catch (cause) {
       try { this.db.exec(`ROLLBACK TO ${savepoint}; RELEASE ${savepoint}`) } catch { /* rollback of a dead tx */ }
@@ -978,6 +1006,47 @@ export class KnowledgeDb {
     }
   }
 
+  /**
+   * 保留上限（0070）。
+   *
+   * 文档里写了保留策略，代码里一条 `DELETE` 都没有。这里补上**新数据**的上限，
+   * 且只裁「水位以上」的行 —— 升级那一刻已有的历史一行不动（见 `retention.ts`）。
+   *
+   * - `revision`：机器版本（`auto`）每个实体留最近 20 版；**命名版本永不裁**
+   *   （`named` 是人对内容做的决定，保留策略里它是永久的）。
+   * - `pipeline_extractions`：抽取检查点同时是复用缓存，每份来源留最近 5 份；
+   *   `pipeline_sources` 指着的那两份（当前抽取 / 当前归一）绝不删 ——
+   *   删了会让那份来源显示成「还没抽取」。
+   * - `blob`：水位以上、已经没有任何 revision 引用的才删。水位以下的 blob 一律留着，
+   *   因为老版本可能还在引用它们。
+   * - `tree`：操作台账，与处理日志同一量级。
+   */
+  private pruneRetention(): void {
+    /*
+     * 每一张都要先问在不在：`pipeline_extractions` 与 `pipeline_sources` 是**管线模块**
+     * 懒建的（`PipelineStore` 的构造函数），而 knowledge.db 可能被别的模块先打开、
+     * 也可能根本没跑过管线。少了这一步，这里会以「no such table」把**每一次写入**都打挂。
+     *
+     * 整个方法包在 try 里还有一层理由：裁剪是**尽力而为**的维护动作，它绝不能成为
+     * 一次已提交写入的失败原因。真出错时宁可不裁（库继续变大），也不让用户写不进去。
+     */
+    try {
+      if (tableExists(this.db, 'revision')) {
+        applyRetention(this.db, 'revision', { table: 'revision', key: 'rowid', keep: 20, where: "kind = 'auto'", groupBy: "entity_kind || '/' || entity_id" })
+      }
+      if (tableExists(this.db, 'pipeline_extractions') && tableExists(this.db, 'pipeline_sources')) {
+        applyRetention(this.db, 'pipeline_extractions', {
+          table: 'pipeline_extractions', key: 'rowid', keep: 5, groupBy: 'source_id',
+          where: "id NOT IN (SELECT extracted_id FROM pipeline_sources WHERE extracted_id IS NOT NULL) AND id NOT IN (SELECT normalized_id FROM pipeline_sources WHERE normalized_id IS NOT NULL)",
+        })
+      }
+      if (tableExists(this.db, 'blob') && tableExists(this.db, 'revision')) {
+        applyRetention(this.db, 'blob', { table: 'blob', key: 'rowid', keep: 0, where: 'hash NOT IN (SELECT blob_hash FROM revision)' })
+      }
+      if (tableExists(this.db, 'tree')) applyRetention(this.db, 'tree', { table: 'tree', key: 'rowid', keep: 2000 })
+    } catch { /* 裁剪是尽力而为：不让它成为写入失败的原因 */ }
+  }
+
   /** 记一次**没有内容变更**的操作（迁移收尾、审核结论这一类）。 */
   recordOperation(entry: TreeEntry, manifest: Record<string, number> = {}): void {
     this.raw('INSERT OR REPLACE INTO tree(op_id, at, actor, summary, manifest) VALUES (?, ?, ?, ?, ?)')
@@ -1284,12 +1353,13 @@ export class KnowledgeDb {
    * 名字拼成语法错误。
    */
   private columnsOf(schema: 'main' | 'legacy', table: string): ColumnInfo[] {
-    const rows = this.raw('SELECT name, "notnull" AS not_null, dflt_value AS dflt FROM pragma_table_info(?, ?)')
+    const rows = this.raw('SELECT name, "notnull" AS not_null, dflt_value AS dflt, pk FROM pragma_table_info(?, ?)')
       .all(table, schema) as Array<Record<string, unknown>>
     return rows.map(row => ({
       name: String(row.name ?? ''),
       notNull: Number(row.not_null ?? 0) === 1,
       hasDefault: row.dflt !== null && row.dflt !== undefined,
+      pk: Number(row.pk ?? 0),
     }))
   }
 
@@ -1377,11 +1447,47 @@ export class KnowledgeDb {
           if (shared.length === 0) { problems.push(`${name} 与目标表没有同名的列，行搬不动`); continue }
           const columns = shared.map(quoteIdentifier).join(', ')
           const expected = Number((this.db.prepare(`SELECT count(*) AS c FROM legacy.${quoteIdentifier(name)}`).get() as { c?: unknown } | undefined)?.c ?? 0)
-          this.db.exec(`INSERT OR IGNORE INTO main.${quoteIdentifier(name)} (${columns}) SELECT ${columns} FROM legacy.${quoteIdentifier(name)}`)
+          /**
+           * 「有没有丢行」要按**三个账**算（0070）：`already`（插入**之前**主键就已存在）、
+           * `inserted`（本次真的插进去的）、以及两者之外的 `unaccounted`
+           * —— 被唯一索引 / 非空 / 检查约束挡掉的那些才是真的丢。
+           *
+           * **顺序很要紧**：`already` 必须在 `INSERT` 之前数。插完再数会把本次插入的行
+           * 也算进去，重复计数恰好把丢行掩盖成 0（试过，就是这样漏掉一行的）。
+           *
+           * 原来那条 `copied < expected`（拿目标**总行数**比旧文件行数）则**永远不成立** ——
+           * 每一次主键冲突都对应一行早就存在 —— 于是丢行之后调用方还会把旧库删掉。
+           */
+          const keyColumns = this.columnsOf('main', name).filter(column => column.pk > 0).map(column => column.name)
+          const comparable = shared.filter(column => !keyColumns.includes(column))
+          const already = keyColumns.length === 0 ? 0 : Number((this.db.prepare(
+            `SELECT COUNT(*) AS c FROM legacy.${quoteIdentifier(name)} l WHERE EXISTS (
+               SELECT 1 FROM main.${quoteIdentifier(name)} m WHERE ${keyColumns.map(column => `m.${quoteIdentifier(column)} IS l.${quoteIdentifier(column)}`).join(' AND ')}
+             )`,
+          ).get() as { c?: unknown } | undefined)?.c ?? 0)
+          const run = this.db.prepare(`INSERT OR IGNORE INTO main.${quoteIdentifier(name)} (${columns}) SELECT ${columns} FROM legacy.${quoteIdentifier(name)}`).run() as { changes?: unknown } | undefined
+          const inserted = Number(run?.changes ?? 0)
           const copied = Number((this.db.prepare(`SELECT count(*) AS c FROM main.${quoteIdentifier(name)}`).get() as { c?: unknown } | undefined)?.c ?? 0)
           tables[name] = copied
-          // 目标里原本可能已经有行（重跑、或者两个来源都写过），所以判据是「不少于」。
-          if (copied < expected) problems.push(`${name} 只拷进 ${copied} 行，原有 ${expected} 行`)
+          if (keyColumns.length === 0) {
+            if (inserted < expected) problems.push(`${name} 只拷进 ${inserted} 行（旧文件 ${expected} 行）：这张表没有主键，无法逐行核对，旧文件不删`)
+          } else {
+            const unaccounted = expected - already - inserted
+            if (unaccounted > 0) problems.push(`${name} 有 ${unaccounted} 行没能进来（主键之外还有唯一索引 / 非空 / 检查约束挡住的行）：旧文件不删`)
+            /**
+             * 纯主键表（例如 `entity_asset(entity_kind, entity_id, ref)`）没有可比的非键列：
+             * 主键相同就是同一行。重跑时报「无法比对内容」是误报，会让旧文件永久留在磁盘上。
+             */
+            if (comparable.length > 0) {
+              const onEq = keyColumns.map(column => `m.${quoteIdentifier(column)} = l.${quoteIdentifier(column)}`).join(' AND ')
+              // `IS NOT` 而不是 `<>`：NULL 与任何值都不相等，用 `<>` 会把「一边是 NULL」漏判。
+              const differs = Number((this.db.prepare(
+                `SELECT COUNT(*) AS c FROM legacy.${quoteIdentifier(name)} l JOIN main.${quoteIdentifier(name)} m ON ${onEq}
+                 WHERE ${comparable.map(column => `m.${quoteIdentifier(column)} IS NOT l.${quoteIdentifier(column)}`).join(' OR ')}`,
+              ).get() as { c?: unknown } | undefined)?.c ?? 0)
+              if (differs > 0) problems.push(`${name} 有 ${differs} 行与目标库主键相同但内容不同：旧文件不删`)
+            }
+          }
         } catch (cause) {
           problems.push(`${name} 的行没拷成：${cause instanceof Error ? cause.message : String(cause)}`)
         }

package/src/store/migrate.ts

@@ -525,7 +525,7 @@ export async function exportKnowledgeTree(input: {
   for (const item of db.sources()) {
     if (only !== undefined && item.record.sourceId !== only) continue
     const path = join(targetRoot, LEGACY_SOURCE, sourceName(item.record.title, item.record.sourceId))
-    if (await write(path, serialize(item.frontmatter, item.record.content))) sources += 1
+    if (await write(path, serialize({ ...item.frontmatter, source_id: item.record.sourceId }, item.record.content))) sources += 1
   }
   for (const item of db.cards()) {
     const path = join(targetRoot, LEGACY_WIKI, item.card.entityType, cardName(item.card.entityId))

package/src/trajectory-types.ts

@@ -0,0 +1,142 @@
+/**
+ * 三段轨迹的**传输形状**（抽取 / 归一 / 物化）。
+ *
+ * 抽取那段本来就有报告（`TrialReport`，见 `wiki-trial-types.ts`），形状没动。这一份只补
+ * 新分开的两段 —— 它们此前**没有轨迹**：只有任务里一段流式输出和一张结果表，跑完就查不到
+ * 「这条知识是怎么从模型给的名字变成库里的坐标的」「这张卡是按什么排出来的」。
+ *
+ * ## 为什么这些类型住在浏览器安全的一层
+ *
+ * 服务端按这个形状写，客户端按同一个形状渲染。写两份就会漂。它们不 import 任何
+ * `node:*`，所以可以直接被两边引用 —— 这与 `pipeline/types.ts` 是同一条规矩。
+ * （`client/wiki-trial.ts` 里那份手写镜像之所以必须手写，是因为它需要引用的服务端模块
+ * import 了 `node:fs`；这里没有那个问题，所以不重复。）
+ *
+ * ## 一份轨迹对应「一次工作」，不是一次任务
+ *
+ * - 抽取：一份来源 × 一次运行。
+ * - 归一：一份来源 × 一次运行（复用的那一次不落轨迹 —— 那一次什么都没做）。
+ * - 物化：一个卡片分组 × 一次运行。
+ *
+ * 粒度定在这里，是因为这三件事的失败与复用手忙脚乱的程度不同：一份文档抽取失败不影响
+ * 另一份；一张卡物化失败也不该让同批其它卡的轨迹看起来像没跑。
+ */
+
+/** 轨迹属于哪一段。与 `PipelineStage` 的前三段同形（`all` 不是轨迹）。 */
+export type TrajectoryStage = 'extract' | 'normalize' | 'materialize'
+
+/** 三个名字只在这里写一次：页标题、列表徽标、日志都用它。 */
+export const TRAJECTORY_STAGE_LABEL: Record<TrajectoryStage, string> = {
+  extract: '抽取轨迹',
+  normalize: '归一轨迹',
+  materialize: '物化轨迹',
+}
+
+/** 挤在行内时用的短名（列表徽标、筛选器）。 */
+export const TRAJECTORY_STAGE_SHORT: Record<TrajectoryStage, string> = {
+  extract: '抽取',
+  normalize: '归一',
+  materialize: '物化',
+}
+
+/** 每条轨迹都要有的那段公共头。 */
+export interface TrajectoryHead {
+  at: string
+  /** 模型接缝当时通不通。抽取以外的两段也可能根本没有模型调用。 */
+  model: { ok: boolean; why?: string; provider?: string; model?: string; reasoningEffort?: string }
+  warnings: string[]
+}
+
+/** 坐标三个分量在轨迹里只作为**展示文本**出现（真源是轴注册表的 id）。 */
+export type TrajectoryAxisKind = 'object' | 'action' | 'scene'
+
+/**
+ * 归一的坐标解析结论。
+ *
+ * `outcome` 的取值与 `TrialAxis.outcome` 同源：命中已有实体 / 新建候选 / 不唯一没猜 /
+ * 只做了文档内归一（`no-registry`）。
+ */
+export interface NormalizeAxisRow {
+  kind: TrajectoryAxisKind
+  /** 文档里的写法。 */
+  name: string
+  outcome: 'matched' | 'new' | 'ambiguous' | 'no-registry' | string
+  /** 落到的实体 id（新建的是候选 id）。歧义时没有。 */
+  id?: string
+  /** 判成这个结果的理由 / 途径，模型或规则给的。 */
+  how?: string
+  aliases: string[]
+  parentMention?: string
+}
+
+/** 一条写进库的 Knowledge 在轨迹里的投影。 */
+export interface NormalizeFactRow {
+  text: string
+  /** 「对象 · 动作 · 场景」的展示文本。 */
+  coordinate: string
+  /** 几条出处。 */
+  sources: number
+  /** 坐标仍有歧义：事实与出处都留着，但暂不进任何卡片分组。 */
+  unresolved: boolean
+}
+
+/** 归一轨迹：一份来源的 mention 名字 → 库内坐标，以及随之写入的事实。 */
+export interface NormalizeTrajectoryReport extends TrajectoryHead {
+  stage: 'normalize'
+  source: { id: string; title: string; version: number }
+  /** 依据哪一条抽取记录做的归一。 */
+  extractionId: string
+  /** 归一之后存下的指纹（下一份文档归一能不能复用，看它）。 */
+  fingerprint: string
+  /** 模型这次给了多少个坐标提及。 */
+  mentions: number
+  /**
+   * 解析结论的分布。`mechanical` = 这一轮没接注册表，只做了文档内归一
+   * （三个分量各自计数，所以它是「多少条提及只做了机械归一」而不是一个布尔）。
+   */
+  counts: { matched: number; created: number; ambiguous: number; mechanical: number }
+  axes: NormalizeAxisRow[]
+  knowledge: { saved: number; merged: number; skipped: number; failures: number; unresolved: number }
+  events: { saved: number; merged: number; skipped: number }
+  rows: NormalizeFactRow[]
+  /** 已有坐标有没有下发进提示词，以及发了多少（0068）。 */
+  axesContext?: { injected: number; totals: number; truncated: number; selection?: string }
+}
+
+/** 物化轨迹里的一节。 */
+export interface MaterializeSectionRow {
+  label: string
+  count: number
+}
+
+/** 物化轨迹：一个卡片分组 → 一张卡，以及它是怎么排出来的。 */
+export interface MaterializeTrajectoryReport extends TrajectoryHead {
+  stage: 'materialize'
+  group: { key: string; title: string; coordinate: string; state: string; fingerprint: string }
+  action: 'created' | 'updated' | 'withdrawn'
+  card: {
+    id: string
+    title: string
+    status: string
+    /** 正文规模，字符数。 */
+    characters: number
+    /** 进卡的知识条数 / 事件数 / 图数。 */
+    knowledge: number
+    events: number
+    images: number
+    sections: MaterializeSectionRow[]
+  }
+  /**
+   * 卡片组织用了没有。
+   *
+   * `used: false` = 这一库没开卡片组织（`cardOrganize` 关着），正文是按坐标机械拼的；
+   * 关着不是失败，但两件事的正文长得不一样，报告必须分得清。
+   */
+  organize: { used: boolean; origin?: 'model' | 'fallback'; layoutHash?: string }
+  /** 进卡的每一条知识（带出处数），让人对着原文核。 */
+  rows: Array<{ id: string; text: string; sources: number }>
+  /** 这一组的来源文档。 */
+  sources: string[]
+  /** 正文里可以指向的其它卡片，以及为什么（`coordinate` / `relation` / `source`）。 */
+  related: Array<{ title: string; reason: string }>
+}

package/src/types.ts

@@ -7,10 +7,8 @@ export type KnowledgeStatus = CardStatus
 /**
  * 知识卡片的 entity_type 白名单。
  *
- * **智能归因的五类也在这里**，这不是放宽而是纠错：排查思路本来就应该是一张 wiki 卡片
- * （0021 §6.4 定了五类实体与三段式卡片），但白名单里没有它们的时候，`writeCard` 会直接
- * 返回 `SCHEMA_TYPE_INVALID`，`readCards` 也会跳过 —— 于是排查思路**永远进不了 wikiNotes，
- * 也就永远召不回来**。列表本身在 `diagnosis/schema.ts` 里定义一次，这里只做联合。
+ * 诊断卡片类型留在联合里供历史数据兼容。当前排查记录落 SourceRaw，Case 是只读投影；
+ * 新运行不会创建 `diagnosis/case` WikiCard。列表本身在 `diagnosis/schema.ts` 里定义一次。
  */
 export type SchemaType =
   | 'concept' | 'metric' | 'table' | 'event' | 'playbook' | 'case'
@@ -28,6 +26,7 @@ export type RerankProvider = 'bert-python' | 'none'
  */
 export type CompileModelMode = 'default' | 'fixed'
 export interface CompileModelSelection {
+  reasoningEffort?: string
   mode: CompileModelMode
   provider?: string
   model?: string

package/src/wiki-finalize.ts

@@ -167,6 +167,34 @@ export function cardKey(card: { entityType: string; entityId: string }): string
  * 弱的那一类是有用的：知识库刚建起来时，关系一条都没有，而「这几张卡来自同一篇文章」
  * 恰好是人最需要的导航。
  */
+/**
+ * 把「按**卡片身份**」的相关推荐计划，映射到「按**分组键**」（0070）。
+ *
+ * 两个键空间不同：`planRelated` 的键是 `type:entityId`，而物化阶段的分组键是坐标
+ * （`objectId\u0001actionId\u0001sceneId`）。不映射会出现一个**静默的**退化：
+ * `organizeCard` 拿不到「可引用的邻居」，而模型一旦照样写出 `[[名字]]`，校验会判
+ * `ORGANIZE_UNKNOWN_REFERENCE`，整组物化失败、卡片永远写不出来。
+ *
+ * 只映射**已经有卡片**的分组：新建的卡片在相关计划里本来就不存在（与旧的
+ * `relatedForCard(existing)` 行为一致）。键用卡片自己的类型，也与旧路径一致。
+ */
+/** `T` 是相关推荐条目的形状：调用方按自己的投影传进来，这里只管键的映射。 */
+export function relatedByGroupKey<T>(
+  groups: ReadonlyArray<{ key: string; cardId?: string }>,
+  cardKeyOf: (groupKey: string) => string | undefined,
+  plan: ReadonlyMap<string, T[]>,
+): Map<string, T[]> {
+  const mapped = new Map<string, T[]>()
+  for (const group of groups) {
+    if (group.cardId === undefined) continue
+    const key = cardKeyOf(group.key)
+    if (key === undefined) continue
+    const entries = plan.get(key)
+    if (entries !== undefined) mapped.set(group.key, entries)
+  }
+  return mapped
+}
+
 export function planRelated(
   cards: Array<Pick<KnowledgeCard, 'entityType' | 'entityId' | 'title' | 'sourceRefs'>>,
   relations: Array<{ fromKey: string; toKey: string }>,

package/src/wiki-materialize.ts

@@ -153,21 +153,10 @@ export function candidatesFromReport(input: {
       ? input.eventIdsByCoordinate?.[coordinateKey]
         ?? card.events.map(id => input.eventIds?.[id]).filter((id): id is string => Boolean(id))
       : []
-    if (items.length === 0 && eventIds.length === 0) continue
-    const localEvents = completeCoordinate
-      ? report.events.filter(event => card.events.includes(event.id))
-      : []
-    const eventSection = localEvents.length > 0
-      ? `## 关联事件\n\n${localEvents.map(event => `- ${event.title}${event.summary ? `：${event.summary}` : ''}`).join('\n')}`
-      : ''
+    if (items.length === 0) continue
     const knowledgeBody = renderFallbackBody(card.placements, byId)
-    const body = [knowledgeBody, eventSection].filter(Boolean).join('\n\n')
-    const eventEvidence = localEvents.flatMap(event => [
-      ...event.sources,
-      ...event.timeline.flatMap(step => step.sources),
-    ]).find(source => source.found)
+    const body = knowledgeBody
     const evidence = evidenceOf(items, sourceId)
-    if (evidence.quote === undefined && eventEvidence) evidence.quote = eventEvidence.quote
 
     cards.push({
       candidate: {
@@ -178,7 +167,7 @@ export function candidatesFromReport(input: {
         aliases: [...new Set([legacyCardNameFor(card.object, card.action, card.scene)])]
           .filter(alias => alias !== card.name),
         body,
-        ...(items[0] ? { summary: items[0].text } : localEvents[0] ? { summary: localEvents[0].summary || localEvents[0].title } : {}),
+        ...(items[0] ? { summary: items[0].text } : {}),
         /**
          * 证据取这条卡里**第一条核对得上的引文**。
          *

package/src/wiki-trial-types.ts

@@ -338,6 +338,9 @@ export interface TrialReport {
    */
   model: {
     ok: boolean
+    /** Structural decoding succeeded, including a valid empty extraction. */
+    parsed?: boolean
+    outputFormat?: 'json' | 'table'
     why?: string
     /** 解析失败时的短摘录，保留旧界面的错误提示。 */
     raw?: string