dsh-data-domain-knowledge 0.1.0-alpha.9 → 0.1.1-alpha.2

package/src/store/knowledge-db.ts

@@ -31,8 +31,10 @@ 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'
 
 /** 知识库里那个文件的名字。定义在 `layout.ts`（布局的唯一真源），这里只是本模块的别名。 */
 export { KNOWLEDGE_DB_FILE }
@@ -236,7 +238,32 @@ function looksLikeAssetRef(ref: string): boolean {
   return /(?:^|\/)_?assets\//.test(ref)
 }
 
-/** 表结构。建库与迁移共用一份，避免两处 DDL 漂移。 */
+/** Event 与坐标 WikiCard 之间的表结构。 */
+const EVENT_SCHEMA_SQL = `
+CREATE TABLE IF NOT EXISTS event (
+  id             TEXT PRIMARY KEY,
+  identity_key   TEXT NOT NULL UNIQUE,
+  identity_type  TEXT NOT NULL,
+  external_id    TEXT,
+  object_id      TEXT NOT NULL DEFAULT '',
+  action_id      TEXT NOT NULL DEFAULT '',
+  scene_id       TEXT NOT NULL DEFAULT '',
+  occurred_at    TEXT,
+  payload        TEXT NOT NULL,
+  created_at     TEXT NOT NULL,
+  updated_at     TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS event_coordinate_idx ON event(object_id, action_id, scene_id);
+CREATE INDEX IF NOT EXISTS event_occurred_at_idx ON event(occurred_at);
+CREATE TABLE IF NOT EXISTS card_event (
+  card_id    TEXT NOT NULL,
+  event_id   TEXT NOT NULL,
+  ordinal    INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (card_id, event_id)
+);
+CREATE INDEX IF NOT EXISTS card_event_event_idx ON card_event(event_id);
+`
+
 function schemaSql(): string {
   return `
 CREATE TABLE IF NOT EXISTS blob (
@@ -310,6 +337,8 @@ CREATE TABLE IF NOT EXISTS card_knowledge (
 );
 CREATE INDEX IF NOT EXISTS card_knowledge_knowledge_idx ON card_knowledge(knowledge_id);
 
+${EVENT_SCHEMA_SQL}
+
 CREATE TABLE IF NOT EXISTS revision (
   entity_kind    TEXT NOT NULL,
   entity_id      TEXT NOT NULL,
@@ -417,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,
@@ -587,6 +626,8 @@ interface ColumnInfo {
   name: string
   notNull: boolean
   hasDefault: boolean
+  /** 主键里的序号（1 起）；0 = 不是主键的一部分。判「是不是同一行」要用它。 */
+  pk: number
 }
 
 /**
@@ -685,7 +726,7 @@ export class KnowledgeTx {
    * 会把「只改备注」「只补图」那几条路径变成一次静默的关联丢失 —— 它们本来就不该
    * 碰落位（那件事只有编译知道）。
    */
-  putCard(card: KnowledgeCard, frontmatter: Record<string, unknown>, journal: Journal, placements?: CardKnowledgeRow[]): WriteOutcome {
+  putCard(card: KnowledgeCard, frontmatter: Record<string, unknown>, journal: Journal, placements?: CardKnowledgeRow[], allowCoordinateMove = false): WriteOutcome {
     const outcome = this.putEntity('card', card.entityId, card.content, frontmatter, journal, () => {
       const existing = this.raw('SELECT coordinate_key, object_id, action_id, scene_id FROM card WHERE entity_id = ?').get(card.entityId) as Record<string, unknown> | undefined
       /*
@@ -698,7 +739,7 @@ export class KnowledgeTx {
         : cardCoordinateKey(storedCoordinate)
       const oldKey = typeof existing?.coordinate_key === 'string' ? existing.coordinate_key : undefined
       if (existing !== undefined) {
-        if (oldKey !== undefined && oldKey !== coordinateKey && !oldKey.startsWith('legacy:')) {
+        if (!allowCoordinateMove && oldKey !== undefined && oldKey !== coordinateKey && !oldKey.startsWith('legacy:')) {
           throw new Error(`CARD_COORDINATE_IMMUTABLE: ${card.entityId} 已绑定坐标，不能直接改主键`)
         }
         this.raw(`UPDATE card SET coordinate_key = ?, entity_type = ?, title = ?, status = ?, owner = ?,
@@ -739,6 +780,7 @@ export class KnowledgeTx {
   /** 删掉一张卡时它的关联行一起走（**代码责任**，这里没有外键）。 */
   dropPlacements(cardId: string): void {
     this.raw('DELETE FROM card_knowledge WHERE card_id = ?').run(cardId)
+    this.raw('DELETE FROM card_event WHERE card_id = ?').run(cardId)
   }
 
   /**
@@ -804,7 +846,7 @@ export class KnowledgeTx {
      * 下一次编译会把这批行当成「这张卡引用的知识」，而那张卡已经不存在了：表现是
      * 对账里冒出一批 `missingCard`，以及一条知识的「属于哪张卡」指向 404。
      */
-    if (kind === 'card') this.raw('DELETE FROM card_knowledge WHERE card_id = ?').run(id)
+    if (kind === 'card') this.dropPlacements(id)
     this.manifest.set(`${kind}/${id}`, 0)
   }
 
@@ -821,6 +863,9 @@ export class KnowledgeTx {
  * 短事务。异步化只会把调用方的顺序打散，换不到任何东西。
  */
 export class KnowledgeDb {
+  private transactionSequence = 0
+  /** 距离上一次保留裁剪又提交了几次写事务。 */
+  private writesSincePrune = 0
   private constructor(private readonly db: SqliteDatabase, readonly file: string) {}
 
   /**
@@ -849,7 +894,6 @@ export class KnowledgeDb {
       return { ok: false, code: 'OPEN_FAILED', message: `打开失败：${cause instanceof Error ? cause.message : String(cause)}` }
     }
     try {
-      db.exec('PRAGMA journal_mode = WAL')
       const owner = readPragma(db, 'application_id')
       const version = readPragma(db, 'user_version')
       /*
@@ -873,11 +917,12 @@ export class KnowledgeDb {
        * 先开的那个模块就会让另一个模块判成「这不是知识库」—— 表现是 `addSource` 报
        * 知识库不可用，而文件明明好好的。
        */
-      const ownTables = ['knowledge', 'knowledge_sources', 'axis_entities', 'axis_aliases']
+      const ownTables = ['knowledge', 'knowledge_sources', 'axis_entities', 'axis_aliases', 'event', 'card_event']
       const hasUserTables = userTableCount(db) > 0
-      const fresh = version === 0 && !hasUserTables
-      const unmarkedKnowledgeDb = version === 0 && ownTables.some(name => tableExists(db, name))
+      const fresh = owner === 0 && version === 0 && !hasUserTables
+      const unmarkedKnowledgeDb = owner === 0 && version === 0 && ownTables.some(name => tableExists(db, name))
       if (fresh) {
+        db.exec('PRAGMA journal_mode = WAL')
         db.exec(schemaSql())
         db.exec(`PRAGMA application_id = ${KNOWLEDGE_DB_APPLICATION_ID}`)
         db.exec(`PRAGMA user_version = ${KNOWLEDGE_DB_SCHEMA}`)
@@ -891,9 +936,12 @@ export class KnowledgeDb {
         db.close()
         return { ok: false, code: 'SCHEMA_TOO_NEW', message: `知识库的 schema 是 ${version}，本版本只认到 ${KNOWLEDGE_DB_SCHEMA}：${file}` }
       }
+      db.exec('PRAGMA journal_mode = WAL')
       if (version < KNOWLEDGE_DB_SCHEMA) {
         migrateSchema(db, version)
       }
+      // 确保知识库包含 Event 实体表和 WikiCard 聚合关系表。
+      db.exec(EVENT_SCHEMA_SQL)
       return { ok: true, db: new KnowledgeDb(db, file) }
     } catch (cause) {
       try { db.close() } catch { /* already closed */ }
@@ -902,11 +950,16 @@ export class KnowledgeDb {
   }
 
   close(): void {
+    // 关库前收一次尾：否则「最后一次裁剪之后新增的行」会一直留到下次打开。
+    this.pruneRetention()
     try { this.db.close() } catch { /* already closed */ }
   }
 
   raw(sql: string): SqliteStatement { return this.db.prepare(sql) }
 
+  /** Repositories share this validated connection; only its owner closes it. */
+  connection(): SqliteDatabase { return this.db }
+
   /**
    * 一次操作 = 一个事务 = 一行 `tree` + 若干行 `revision`。
    *
@@ -920,7 +973,8 @@ export class KnowledgeDb {
   transact<T>(entry: TreeEntry, fn: (tx: KnowledgeTx) => T): T {
     const tx = new KnowledgeTx(this)
     const at = entry.at ?? new Date().toISOString()
-    this.db.exec('BEGIN')
+    const savepoint = `knowledge_op_${++this.transactionSequence}`
+    this.db.exec(`SAVEPOINT ${savepoint}`)
     try {
       /*
        * `INSERT OR REPLACE`：`op_id` 是**幂等键**。
@@ -933,14 +987,66 @@ export class KnowledgeDb {
         .run(entry.opId, at, entry.actor, entry.summary, '{}')
       const result = fn(tx)
       this.raw('UPDATE tree SET manifest = ? WHERE op_id = ?').run(tx.manifestJson(), entry.opId)
-      this.db.exec('COMMIT')
+      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') } catch { /* rollback of a dead tx */ }
+      try { this.db.exec(`ROLLBACK TO ${savepoint}; RELEASE ${savepoint}`) } catch { /* rollback of a dead tx */ }
       throw cause
     }
   }
 
+  /**
+   * 保留上限（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 (?, ?, ?, ?, ?)')
@@ -1008,6 +1114,93 @@ export class KnowledgeDb {
   sources(): SourceRecord[] { return this.readEntities('source') as SourceRecord[] }
   cards(): CardRecord[] { return this.readEntities('card') as CardRecord[] }
 
+  /** Knowledge 的同层事实实体。事件正文是结构化 JSON，不经过 WikiCard 的内容版本表。 */
+  events(): EventEntity[] {
+    const rows = this.raw('SELECT payload FROM event ORDER BY occurred_at DESC, id').all() as Array<{ payload?: unknown }>
+    const out: EventEntity[] = []
+    for (const row of rows) {
+      if (typeof row.payload !== 'string') continue
+      try {
+        const parsed: unknown = JSON.parse(row.payload)
+        if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) out.push({ ...(parsed as EventEntity), kind: 'case', version: (parsed as EventEntity).version ?? 1 })
+      } catch { /* 单条坏记录不阻断其他 Event 的读取 */ }
+    }
+    return out
+  }
+
+  event(id: string): EventEntity | undefined {
+    const row = this.raw('SELECT payload FROM event WHERE id = ?').get(id) as { payload?: unknown } | undefined
+    if (typeof row?.payload !== 'string') return undefined
+    try {
+      const parsed: unknown = JSON.parse(row.payload)
+      return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed) ? { ...(parsed as EventEntity), kind: 'case', version: (parsed as EventEntity).version ?? 1 } : undefined
+    } catch { return undefined }
+  }
+
+  writeEvent(event: EventEntity): void {
+    const previous = this.event(event.id)
+    const contentOf = (value: EventEntity): string => JSON.stringify({ ...value, kind: 'case', version: undefined, createdAt: undefined, updatedAt: undefined })
+    event.kind = 'case'
+    const latest = this.raw("SELECT MAX(version) AS v FROM revision WHERE entity_kind='case' AND entity_id=?").get(event.id) as { v?: number } | undefined
+    event.version = previous && contentOf(previous) === contentOf(event) ? previous.version ?? 1 : Math.max(previous?.version ?? 0, latest?.v ?? 0) + 1
+    const sql = this.connection()
+    sql.exec('SAVEPOINT write_case')
+    try {
+    this.raw(`INSERT INTO event(id, identity_key, identity_type, external_id, object_id, action_id, scene_id, occurred_at, payload, created_at, updated_at)
+              VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+              ON CONFLICT(id) DO UPDATE SET
+                identity_key = excluded.identity_key,
+                identity_type = excluded.identity_type,
+                external_id = excluded.external_id,
+                object_id = excluded.object_id,
+                action_id = excluded.action_id,
+                scene_id = excluded.scene_id,
+                occurred_at = excluded.occurred_at,
+                payload = excluded.payload,
+                updated_at = excluded.updated_at`)
+      .run(
+        event.id, event.identityKey, event.identityType, event.externalId,
+        event.coordinateIds.objectId, event.coordinateIds.actionId, event.coordinateIds.sceneId,
+        event.occurredAt, JSON.stringify(event), event.createdAt, event.updatedAt,
+      )
+      const alreadySaved = this.raw("SELECT 1 FROM revision WHERE entity_kind='case' AND entity_id=? AND version=?").get(event.id, event.version)
+      if (!alreadySaved) {
+      const body = JSON.stringify(event)
+      const blobHash = createHash('sha256').update(body).digest('hex')
+      this.raw('INSERT OR IGNORE INTO blob(hash,body,bytes) VALUES (?,?,?)').run(blobHash, body, Buffer.byteLength(body))
+      this.raw("INSERT OR IGNORE INTO revision(entity_kind,entity_id,version,blob_hash,actor,kind,summary,at,parent_version,frontmatter) VALUES ('case',?,?,?,?,?,?,?,?,?)")
+        .run(event.id, event.version, blobHash, 'compiler', 'auto', '保存 Case 过程与证据', event.updatedAt, previous?.version ?? null, '{}')
+      }
+      sql.exec('RELEASE write_case')
+    } catch (cause) { sql.exec('ROLLBACK TO write_case; RELEASE write_case'); throw cause }
+  }
+
+  caseVersion(id: string, version: number): EventEntity | undefined {
+    const row = this.raw("SELECT b.body FROM revision r JOIN blob b ON b.hash=r.blob_hash WHERE r.entity_kind='case' AND r.entity_id=? AND r.version=?").get(id, version) as { body?: unknown } | undefined
+    if (typeof row?.body !== 'string') return undefined
+    try { return JSON.parse(row.body) as EventEntity } catch { return undefined }
+  }
+
+  removeEvent(id: string): void {
+    this.raw('DELETE FROM card_event WHERE event_id = ?').run(id)
+    this.raw('DELETE FROM event WHERE id = ?').run(id)
+  }
+
+  cardEventIds(cardId: string): string[] {
+    return (this.raw('SELECT event_id FROM card_event WHERE card_id = ? ORDER BY ordinal, event_id').all(cardId) as Array<{ event_id?: unknown }>)
+      .flatMap(row => typeof row.event_id === 'string' ? [row.event_id] : [])
+  }
+
+  setCardEvents(cardId: string, eventIds: string[]): boolean {
+    const next = [...new Set(eventIds)].sort()
+    const current = this.cardEventIds(cardId)
+    if (JSON.stringify(current) === JSON.stringify(next)) return false
+    this.raw('DELETE FROM card_event WHERE card_id = ?').run(cardId)
+    const insert = this.raw('INSERT INTO card_event(card_id, event_id, ordinal) VALUES (?, ?, ?)')
+    next.forEach((eventId, ordinal) => insert.run(cardId, eventId, ordinal))
+    return true
+  }
+
   source(id: string): SourceRecord | undefined {
     return (this.readEntities('source', id) as SourceRecord[])[0]
   }
@@ -1184,12 +1377,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),
     }))
   }
 
@@ -1266,7 +1460,8 @@ export class KnowledgeDb {
           const mainNames = new Set(mainColumns.map(column => column.name))
           const legacyNames = new Set(legacyColumns.map(column => column.name))
           const shared = legacyColumns.filter(column => mainNames.has(column.name)).map(column => column.name)
-          const dropped = legacyColumns.filter(column => !mainNames.has(column.name)).map(column => column.name)
+          const dropped = legacyColumns.filter(column => !mainNames.has(column.name)
+            && !((name === 'knowledge_sources' || name === 'source') && column.name === 'source_type')).map(column => column.name)
           const required = mainColumns.filter(column => !legacyNames.has(column.name) && column.notNull && !column.hasDefault)
           if (dropped.length > 0) problems.push(`${name} 的这几列在目标表里没有，内容搬不过来：${dropped.join('、')}`)
           if (required.length > 0) {
@@ -1276,11 +1471,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

@@ -35,7 +35,7 @@
 import { existsSync } from 'node:fs'
 import { cp, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises'
 import { basename, dirname, join, relative } from 'node:path'
-import { ASSETS_DIR, SOURCE_RAW_DIR } from '../layout.js'
+import { ASSETS_DIR, PUBLISHED_IMAGE_MARKER, SOURCE_RAW_DIR } from '../layout.js'
 import type { KnowledgeCard, SourceRaw } from '../types.js'
 import type { KnowledgeDb } from './knowledge-db.js'
 
@@ -240,7 +240,17 @@ export async function migrateKnowledgeTree(input: MigrationInput): Promise<Migra
       })
     }
     db.transact({ opId: sourceOp(opId, 'source', sourceId), actor: 'migration', summary: '迁移来源', at: record.updatedAt }, tx => {
-      tx.putSource(record, parsed.frontmatter, { actor: 'migration', kind: 'named', at: record.createdAt })
+      const frontmatter = { ...parsed.frontmatter }
+      const origin = typeof record.metadata.source_url === 'string' ? record.metadata.source_url.trim() : ''
+      if (origin) {
+        frontmatter.resource ??= origin
+        frontmatter.sources ??= [{ id: 'origin', resource: origin, title: record.title }]
+      }
+      const parser = typeof record.metadata.parser === 'string' ? record.metadata.parser.trim() : ''
+      if (parser && typeof parsed.frontmatter.created_at === 'string') {
+        frontmatter.generated ??= { by: parser.startsWith('convert/') ? parser : `convert/${parser}`, at: parsed.frontmatter.created_at }
+      }
+      tx.putSource(record, frontmatter, { actor: 'migration', kind: 'named', at: record.createdAt })
     })
     report.sources += 1
   }
@@ -290,7 +300,7 @@ export async function migrateKnowledgeTree(input: MigrationInput): Promise<Migra
     const to = join(kbRoot, ASSETS_DIR, bucket)
     report.assetBuckets += 1
     if (dryRun) {
-      report.assetFiles += (await listFiles(from, '')).length
+      report.assetFiles += (await listFiles(from, '')).filter(path => basename(path) !== PUBLISHED_IMAGE_MARKER).length
       continue
     }
     try {
@@ -306,7 +316,7 @@ export async function migrateKnowledgeTree(input: MigrationInput): Promise<Migra
        */
       if (!existsSync(to)) await rename(from, to)
       else await mergeAssetBucket(from, to)
-      report.assetFiles += (await listFiles(to, '')).length
+      report.assetFiles += (await listFiles(to, '')).filter(path => basename(path) !== PUBLISHED_IMAGE_MARKER).length
     } catch (cause) {
       problems.push(`搬不动图片桶 ${bucket}：${cause instanceof Error ? cause.message : String(cause)}`)
     }
@@ -515,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))
@@ -555,7 +565,7 @@ async function copyContentTree(from: string, to: string, overwrite: boolean): Pr
     if (!overwrite && existsSync(target)) continue
     await mkdir(dirname(target), { recursive: true })
     await cp(source, target, { force: true })
-    copied += 1
+    if (basename(source) !== PUBLISHED_IMAGE_MARKER) copied += 1
   }
   return copied
 }

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 }>
+}