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

package/src/knowledge.ts

@@ -1,9 +1,10 @@
 /**
  * Knowledge（0063 §2）：**事实真源**。一条可独立检索、可由来源验证的原子语义单元。
  *
- * ## 只有 `text` 是内容
+ * ## `text` 与结构化内容共同构成知识
  *
- * `object` / `action` / `scene` 是三个轴实体的引用，`sources` 是出处 —— 它们都是索引。
+ * `text` 保存可读内容，`data` 保存条件及 Procedure 的方法、检查与限制。
+ * `object` / `action` / `scene` 是轴实体引用，`sources` 是出处。
  * 把索引当知识，是这套模型最常见的误解。
  *
  * ## 判重与冲突（§5.2.2）
@@ -21,22 +22,22 @@
  * 还把两个来源都抹了。**也不许删掉任何一条** —— 删了就没有「冲突」这件事了，
  * 而冲突本身是要给人看的信号。
  *
- * ## 身份就是判重键
+ * ## 稳定身份与判重键
  *
- * `id = k_<归一化文本的哈希>`。同一个事实无论来自哪份文档都得到同一个 id，于是
- * 「多来源支持」是**往同一行追加 sources**，而不是靠一条知识挂多个坐标。
- * 文本改了就是一个新 id —— 旧的那条**留着**（不许删），两条之间可以记一条 redirect。
+ * 新行使用 `k_<归一化文本的 SHA-256>`，存量 ID 保留。判重先比较归一化文本，
+ * 不把哈希相同当作事实相同。「多来源支持」往同一行追加版本证据。
+ * 人工编辑正文保留 ID 并增加内容版本；重新抽出不同文本则保留为另一条知识。
  *
  * ## 为什么存在记忆段
  *
  * Knowledge 不可重建：它是抽取产物 + 人的裁决。重跑一次抽取不会得到同样的结果，
- * 而人的裁决根本没有第二次。所以它和轴注册表同一个库（`<memoryDir>/knowledge.sqlite`）。
+ * 而人的裁决根本没有第二次。所以它与轴注册表共享经过属主、版本校验的 `knowledge.db`。
  */
 
-import { mkdir } from 'node:fs/promises'
-import { dirname } from 'node:path'
 import { createHash } from 'node:crypto'
 import { loadSqlite, type SqliteDatabase } from './fts.js'
+import { KnowledgeDb } from './store/knowledge-db.js'
+import type { KnowledgeKind, KnowledgeContent } from './knowledge-contract.js'
 
 /**
  * 一条 Knowledge 的**真值状态**。
@@ -93,15 +94,20 @@ export interface KnowledgeSource {
    * 「这条知识依据的是第 3 版，而那版已经被人改过了」。
    */
   toVersion?: number
+  /** Evidence changes do not change the truth state of the Knowledge. */
+  currentVersion?: number
+  evidenceStatus?: 'current' | 'historical' | 'unversioned' | 'missing' | 'human'
+  quoteInCurrentVersion?: boolean
+  /** A completed newer extraction withdrew this document contribution. */
+  withdrawn?: boolean
   createdAt: string
 }
 
 export interface Knowledge {
-  /*
-   * 当前不把 Fact / Rule / Procedure / Constraint 做成 Knowledge 的列。它们只有在产生
-   * 不同召回、验证或执行策略时才值得结构化；现阶段由抽取/Card metadata 承载扩展信息。
-   */
   id: string
+  kind?: KnowledgeKind
+  data?: KnowledgeContent
+  /** Fact / Procedure 的结构化内容参与版本与判重；Case 使用共享库内的独立存储。 */
   text: string
   /** 三个轴实体的 id。空串 = 那个分量为空 —— 坐标可以是空的（§九）。 */
   objectId: string
@@ -112,7 +118,7 @@ export interface Knowledge {
   runId: string
   /** 被并进了哪一条。空串 = 它自己就是保留的那条。 */
   mergedInto: string
-  /** 当前正文版本。只有 `text` 的内容 hash 变化时才递增。 */
+  /** 当前内容版本。正文、类型或结构化条件变化时递增。 */
   version: number
   createdAt: string
   updatedAt: string
@@ -147,9 +153,12 @@ export interface KnowledgeCardRef {
  */
 export function normalizeKnowledge(text: string): string {
   return text
+    .normalize('NFKC')
     .toLowerCase()
     .replace(/\s+/g, '')
-    .replace(/[，。、；：？！,.;:?!"'“”‘’（）()【】\[\]《》<>—\-_/\\]/g, '')
+    // Operators, decimal points, signs and identifier separators carry meaning.
+    .replace(/[，。、；：？！,;:?!“”‘’]/g, '')
+    .replace(/\.$/g, '')
 }
 
 /** FNV-1a（32 位）：只用来生成稳定短 id，不用于任何安全目的。 */
@@ -172,10 +181,15 @@ function fnv1a(value: string): number {
  * 如果未来一个库混合多个 Scope 或有效期，必须先把 Scope/有效性纳入判重策略，再改变 id。
  */
 export function knowledgeId(text: string): string {
-  return `k_${fnv1a(normalizeKnowledge(text)).toString(36)}`
+  return `k_${createHash('sha256').update(normalizeKnowledge(text), 'utf8').digest('hex')}`
 }
 
 export interface KnowledgeIngest {
+  /** v2 records deduplicate only inside the same semantic coordinate; legacy IDs remain readable. */
+  scopeIdentity?: boolean
+  id?: string
+  kind?: KnowledgeKind
+  data?: KnowledgeContent
   text: string
   objectId?: string
   actionId?: string
@@ -221,6 +235,8 @@ export interface KnowledgeVersion {
  * 「`object_id` 这个参数不在」与「`object_id=` 空值」。
  */
 export interface KnowledgeQuery {
+  kind?: KnowledgeKind
+  excludeWithdrawn?: boolean
   objectId?: string
   actionId?: string
   sceneId?: string
@@ -375,6 +391,8 @@ CREATE TABLE IF NOT EXISTS knowledge (
   id TEXT PRIMARY KEY,
   text TEXT NOT NULL,
   normalized TEXT NOT NULL,
+  kind TEXT NOT NULL DEFAULT 'fact',
+  payload TEXT NOT NULL DEFAULT '{}',
   object_id TEXT NOT NULL DEFAULT '',
   action_id TEXT NOT NULL DEFAULT '',
   scene_id TEXT NOT NULL DEFAULT '',
@@ -458,8 +476,9 @@ CREATE INDEX IF NOT EXISTS revision_blob_idx ON revision(blob_hash);
  */
 export class KnowledgeStore {
   private db: SqliteDatabase | null = null
+  private owner: KnowledgeDb | null = null
 
-  constructor(private readonly file: string) {}
+  constructor(private readonly file: string, private readonly shared?: SqliteDatabase) {}
 
   /**
    * 这个文件里有没有某张表。
@@ -481,14 +500,25 @@ export class KnowledgeStore {
     const sqlite = await loadSqlite()
     if (sqlite === null) return false
     try {
-      await mkdir(dirname(this.file), { recursive: true })
-      this.db = new sqlite.DatabaseSync(this.file)
+      if (this.shared) this.db = this.shared
+      else {
+        const opened = await KnowledgeDb.open(this.file, sqlite.DatabaseSync)
+        if (!opened.ok) return false
+        this.owner = opened.db
+        this.db = opened.db.connection()
+      }
       this.db.exec(SCHEMA)
+      if (!hasColumn(this.db, 'knowledge', 'kind')) this.db.exec("ALTER TABLE knowledge ADD COLUMN kind TEXT NOT NULL DEFAULT 'fact'")
+      if (!hasColumn(this.db, 'knowledge', 'payload')) this.db.exec("ALTER TABLE knowledge ADD COLUMN payload TEXT NOT NULL DEFAULT '{}'")
+      // The retired source_type table can predate revision-bound evidence too.
+      if (!hasColumn(this.db, 'knowledge_sources', 'to_version')) {
+        this.db.exec('ALTER TABLE knowledge_sources ADD COLUMN to_version INTEGER')
+      }
       /*
        * 旧库的 `knowledge_sources` 带有已经撤掉的 `source_type NOT NULL` 列。
        * `CREATE TABLE IF NOT EXISTS` 不会改变旧表；如果直接继续，新的出处写入会因
        * 没有给这个列赋值而全部失败，表现成「抽取报告有知识，但 Knowledge 为 0」。
-       * 只重建这一张可派生关系表，保留正文与出处数据，并让迁移具备事务性。
+       * 只重建这一张出处表，保留原始证据数据，并让迁移具备事务性。
        */
       if (hasColumn(this.db, 'knowledge_sources', 'source_type')) {
         this.db.exec('BEGIN IMMEDIATE')
@@ -521,26 +551,27 @@ export class KnowledgeStore {
           throw cause
         }
       }
-      /*
-       * 0062 v2 补的列。老库（`CREATE TABLE IF NOT EXISTS` 对已存在的表是空操作）不会
-       * 自己长出它来，所以要显式 ALTER —— 与知识库文件「版本不符走迁移、不重建」同一政策。
-       */
-      if (!hasColumn(this.db, 'knowledge_sources', 'to_version')) {
-        this.db.exec('ALTER TABLE knowledge_sources ADD COLUMN to_version INTEGER')
-      }
+      if (!hasColumn(this.db, 'knowledge_sources', 'withdrawn')) this.db.exec('ALTER TABLE knowledge_sources ADD COLUMN withdrawn INTEGER NOT NULL DEFAULT 0')
       if (!hasColumn(this.db, 'knowledge', 'head_version')) {
         this.db.exec("ALTER TABLE knowledge ADD COLUMN head_version INTEGER NOT NULL DEFAULT 0")
       }
+      // Keep legacy IDs and references; replace only the lossy comparison key.
+      const reindex = this.db.prepare('UPDATE knowledge SET normalized = ? WHERE id = ?')
+      for (const row of this.db.prepare('SELECT id, text, normalized FROM knowledge').all() as Array<{ id: string; text: string; normalized: string }>) {
+        const normalized = normalizeKnowledge(row.text)
+        if (normalized !== row.normalized) reindex.run(normalized, row.id)
+      }
       this.backfillContentVersions()
       return true
     } catch {
+      this.owner?.close()
+      this.owner = null
       this.db = null
       return false
     }
   }
 
-  available(): boolean {    return this.db !== null
-  }
+  available(): boolean { return this.db !== null }
 
   /**
    * 为旧 Knowledge 行补首版。
@@ -612,13 +643,23 @@ export class KnowledgeStore {
     if (this.db === null) throw new Error('KNOWLEDGE_STORE_UNAVAILABLE')
     const text = input.text.trim()
     if (!text) throw new Error('KNOWLEDGE_TEXT_REQUIRED')
+    const kind = input.kind ?? 'fact'
+    if (kind === 'case') throw new Error('CASE_STORE_REQUIRED: Case 通过统一 Case 存储保存，不写入 Fact/Procedure 表')
+    const data = input.data ?? {}
+    const payload = JSON.stringify(data)
     const normalized = normalizeKnowledge(text)
-    const id = knowledgeId(text)
+    // Edited and migrated facts keep their identity. A hash is not proof of equality.
+    const coordinate = [(input.objectId ?? '').trim(), (input.actionId ?? '').trim(), (input.sceneId ?? '').trim()]
+    const match = input.scopeIdentity
+      ? this.db.prepare("SELECT id FROM knowledge WHERE normalized=? AND kind=? AND payload=? AND object_id=? AND action_id=? AND scene_id=? AND merged_into='' ORDER BY created_at,id LIMIT 1").get(normalized, kind, payload, ...coordinate) as { id: string } | undefined
+      : this.db.prepare("SELECT id FROM knowledge WHERE normalized=? AND kind=? AND payload=? AND merged_into='' ORDER BY created_at,id LIMIT 1").get(normalized, kind, payload) as { id: string } | undefined
+    const id = input.id ?? match?.id ?? (!input.scopeIdentity && kind === 'fact' && payload === '{}' ? knowledgeId(text) : `k_${createHash('sha256').update(JSON.stringify([kind, normalized, data, ...(input.scopeIdentity ? coordinate : [])])).digest('hex')}`)
     const now = new Date().toISOString()
-    const existing = await this.get(id)
+    const existing = this.read(id)
+    if (existing !== null && !input.id && (normalizeKnowledge(existing.text) !== normalized || (existing.kind ?? 'fact') !== kind)) throw new Error('KNOWLEDGE_ID_COLLISION')
 
     if (existing === null) {
-      this.db.exec('BEGIN')
+      this.db.exec('SAVEPOINT knowledge_ingest')
       try {
         this.db.prepare(
           'INSERT INTO knowledge (id, text, normalized, object_id, action_id, scene_id, status, run_id, merged_into, head_version, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
@@ -627,18 +668,19 @@ export class KnowledgeStore {
           (input.objectId ?? '').trim(), (input.actionId ?? '').trim(), (input.sceneId ?? '').trim(),
           input.status ?? 'candidate', (input.runId ?? '').trim(), '', 0, now, now,
         )
-        const added = await this.appendSources(id, input.sources ?? [])
-        this.appendContentVersion(id, text, {
+        this.db.prepare('UPDATE knowledge SET kind = ?, payload = ? WHERE id = ?').run(kind, payload, id)
+        const added = this.appendSources(id, input.sources ?? [])
+        this.appendContentVersion(id, kind === 'fact' && payload === '{}' ? text : JSON.stringify({ text, kind, data }), {
           actor: input.actor ?? 'compiler',
           kind: input.revisionKind ?? 'auto',
           summary: input.revisionSummary ?? '写入 Knowledge',
           at: now,
         })
         this.db.prepare('UPDATE knowledge SET head_version = 1 WHERE id = ?').run(id)
-        this.db.exec('COMMIT')
-        return { knowledge: (await this.get(id))!, merged: false, addedSources: added }
+        this.db.exec('RELEASE knowledge_ingest')
+        return { knowledge: this.read(id)!, merged: false, addedSources: added }
       } catch (cause) {
-        this.db.exec('ROLLBACK')
+        this.db.exec('ROLLBACK TO knowledge_ingest; RELEASE knowledge_ingest')
         throw cause
       }
     }
@@ -652,23 +694,33 @@ export class KnowledgeStore {
      * 所以只允许「旧坐标三项全空 → 本次坐标非空」这一种补齐；已有任意坐标的行仍走显式
      * `setCoordinate`，不会被合并流程覆盖。
      */
-    const incomingCoordinate = {
-      objectId: (input.objectId ?? '').trim(),
-      actionId: (input.actionId ?? '').trim(),
-      sceneId: (input.sceneId ?? '').trim(),
-    }
-    const existingHasCoordinate = existing.objectId !== '' || existing.actionId !== '' || existing.sceneId !== ''
-    const incomingHasCoordinate = incomingCoordinate.objectId !== '' || incomingCoordinate.actionId !== '' || incomingCoordinate.sceneId !== ''
-    if (!existingHasCoordinate && incomingHasCoordinate) {
-      this.db.prepare('UPDATE knowledge SET object_id = ?, action_id = ?, scene_id = ?, updated_at = ? WHERE id = ?').run(
-        incomingCoordinate.objectId, incomingCoordinate.actionId, incomingCoordinate.sceneId, now, id,
-      )
-    }
-    const added = await this.appendSources(id, input.sources ?? [])
-    if (existingHasCoordinate || !incomingHasCoordinate) {
-      this.db.prepare('UPDATE knowledge SET updated_at = ? WHERE id = ?').run(now, id)
-    }
-    return { knowledge: (await this.get(id))!, merged: true, addedSources: added }
+    this.db.exec('SAVEPOINT knowledge_update')
+    try {
+      if (input.id && (existing.text !== text || (existing.kind ?? 'fact') !== kind || JSON.stringify(existing.data ?? {}) !== payload)) {
+        this.db.prepare('UPDATE knowledge SET text = ?, normalized = ?, kind = ?, payload = ?, updated_at = ? WHERE id = ?').run(text, normalized, kind, payload, now, id)
+        const version = this.appendContentVersion(id, kind === 'fact' && payload === '{}' ? text : JSON.stringify({ text, kind, data }), { actor: input.actor ?? 'compiler', kind: 'auto', summary: '更新 Knowledge 内容与条件', at: now })
+        this.db.prepare('UPDATE knowledge SET head_version = ? WHERE id = ?').run(version, id)
+      }
+      const incomingCoordinate = {
+        objectId: (input.objectId ?? '').trim(),
+        actionId: (input.actionId ?? '').trim(),
+        sceneId: (input.sceneId ?? '').trim(),
+      }
+      const existingHasCoordinate = existing.objectId !== '' || existing.actionId !== '' || existing.sceneId !== ''
+      const incomingHasCoordinate = incomingCoordinate.objectId !== '' || incomingCoordinate.actionId !== '' || incomingCoordinate.sceneId !== ''
+      if (!existingHasCoordinate && incomingHasCoordinate) {
+        this.db.prepare('UPDATE knowledge SET object_id = ?, action_id = ?, scene_id = ?, updated_at = ? WHERE id = ?').run(
+          incomingCoordinate.objectId, incomingCoordinate.actionId, incomingCoordinate.sceneId, now, id,
+        )
+      }
+      const added = this.appendSources(id, input.sources ?? [])
+      if (existingHasCoordinate || !incomingHasCoordinate) {
+        this.db.prepare('UPDATE knowledge SET updated_at = ? WHERE id = ?').run(now, id)
+      }
+      const result = { knowledge: (await this.get(id))!, merged: true, addedSources: added }
+      this.db.exec('RELEASE knowledge_update')
+      return result
+    } catch (cause) { this.db.exec('ROLLBACK TO knowledge_update; RELEASE knowledge_update'); throw cause }
   }
 
   /**
@@ -692,6 +744,7 @@ export class KnowledgeStore {
     if (!text) throw new Error('KNOWLEDGE_TEXT_REQUIRED')
     const current = await this.get(id)
     if (current === null) return null
+    if (current.kind === 'procedure') throw new Error('PROCEDURE_STRUCTURED_EDIT_REQUIRED: 请同时修改 Procedure 的问题、方法、条件与验证字段，不能只改展示正文')
     const now = new Date().toISOString()
     this.db.exec('BEGIN')
     try {
@@ -713,24 +766,21 @@ export class KnowledgeStore {
   }
 
   /** 追加来源。返回这次真正加进去几条（去重之后）。 */
-  private async appendSources(id: string, sources: Array<Partial<KnowledgeSource>>): Promise<number> {
+  private appendSources(id: string, sources: Array<Partial<KnowledgeSource>>): number {
     if (sources.length === 0) return 0
-    const current = await this.get(id)
+    const current = this.read(id)
     const existingByKey = new Map((current?.sources ?? []).map(source => [sourceKey(source), source]))
     const seen = new Set(existingByKey.keys())
-    let ordinal = current?.sources.length ?? 0
+    let ordinal = Number((this.db!.prepare('SELECT COALESCE(MAX(ordinal), -1) + 1 AS n FROM knowledge_sources WHERE knowledge_id = ?').get(id) as { n: number }).n)
     let added = 0
     const now = new Date().toISOString()
     for (const source of sources) {
       const row = normalizeSource(source, now)
       const key = sourceKey(row)
       if (seen.has(key)) {
-        // 同一出处的来源版本是血缘元数据，不是新的 Knowledge 内容版本。
-        const previous = existingByKey.get(key)
-        if (row.toVersion !== undefined && previous?.toVersion !== row.toVersion) {
-          this.db!.prepare(
-            'UPDATE knowledge_sources SET to_version = ? WHERE knowledge_id = ? AND document_id = ? AND quote = ? AND author = ? AND statement = ?',
-          ).run(row.toVersion, id, row.documentId, row.quote, row.author, row.statement)
+        if (existingByKey.get(key)?.withdrawn) {
+          this.db!.prepare('UPDATE knowledge_sources SET withdrawn=0 WHERE knowledge_id=? AND document_id=? AND quote=? AND COALESCE(to_version,-1)=?')
+            .run(id, row.documentId, row.quote, row.toVersion ?? -1)
         }
         continue
       }
@@ -748,7 +798,10 @@ export class KnowledgeStore {
     return added
   }
 
-  async get(id: string): Promise<Knowledge | null> {    if (this.db === null) throw new Error('KNOWLEDGE_STORE_UNAVAILABLE')
+  async get(id: string): Promise<Knowledge | null> { return this.read(id) }
+
+  private read(id: string): Knowledge | null {
+    if (this.db === null) throw new Error('KNOWLEDGE_STORE_UNAVAILABLE')
     const row = this.db.prepare('SELECT * FROM knowledge WHERE id = ?').get(id) as Record<string, unknown> | undefined
     if (row === undefined) return null
     const sources = this.db.prepare(
@@ -773,7 +826,7 @@ export class KnowledgeStore {
       version: Number(row.version),
       contentHash: String(row.blob_hash ?? ''),
       bytes: Number(row.bytes ?? Buffer.byteLength(String(row.body ?? ''), 'utf8')),
-      text: String(row.body ?? ''),
+      text: (() => { const body = String(row.body ?? ''); try { const value = JSON.parse(body); return typeof value?.text === 'string' && value?.kind ? value.text : body } catch { return body } })(),
       actor: String(row.actor ?? 'system'),
       kind: String(row.kind ?? 'auto'),
       summary: String(row.summary ?? ''),
@@ -948,6 +1001,8 @@ export class KnowledgeStore {
   } {
     const where: string[] = [query.includeMerged === true ? '1 = 1' : "merged_into = ''"]
     const params: Record<string, unknown> = {}
+    if (query.kind !== undefined) { where.push('kind = :knowledgeKind'); params.knowledgeKind = query.kind }
+    if (query.excludeWithdrawn) where.push('EXISTS (SELECT 1 FROM knowledge_sources active_source WHERE active_source.knowledge_id = knowledge.id AND active_source.withdrawn = 0)')
     if (query.ids !== undefined) {
       // 空数组是一个**取值**（筛出空集），不能退化成「不过滤」—— 那会让一次失败的落位
       // 查询变成「把整库的知识塞进这次召回」。
@@ -961,7 +1016,17 @@ export class KnowledgeStore {
     if (!skip.has('status') && query.status !== undefined) { where.push('status = :status'); params.status = query.status }
     if (query.runId !== undefined) { where.push('run_id = :runId'); params.runId = query.runId }
     if (query.noCoordinate === true) where.push("object_id = '' AND action_id = '' AND scene_id = ''")
-    if (query.text) { where.push('normalized LIKE :text'); params.text = `%${normalizeKnowledge(query.text)}%` }
+    if (query.text) {
+      /**
+       * LIKE 的元字符必须转义（0070）。
+       *
+       * `normalizeKnowledge` 会保留 `%` 与 `_`，而 `?q=` 是用户能直接传的：查询 `%`
+       * 会拼成 `%%%`，命中整库并虚报 total；`a_b` 还会顺带匹配 `axb`。反斜杠自己也要
+       * 先转义 —— 否则用户输入的一个 `\` 会把后面的字符变成转义序列。
+       */
+      where.push("normalized LIKE :text ESCAPE '\\'")
+      params.text = `%${normalizeKnowledge(query.text).replace(/[\\%_]/g, char => `\\${char}`)}%`
+    }
     if (query.cardId !== undefined) {
       /*
        * `card_knowledge` 归**另一个模块**所有（`store/knowledge-db.ts`），而两个模块
@@ -1015,7 +1080,7 @@ export class KnowledgeStore {
      *
      * 联动只走一个方向：**矩阵 → 列表**。点一格筛列表，列表的筛选不动矩阵。
      */
-    const forMatrix = this.where({})
+    const forMatrix = this.where({ kind: query.kind })
     const rows = this.db.prepare(
       `SELECT object_id, action_id, scene_id, COUNT(*) AS n FROM knowledge ${forMatrix.clause}
        GROUP BY object_id, action_id, scene_id`,
@@ -1341,7 +1406,8 @@ export class KnowledgeStore {
   }
 
   close(): void {
-    this.db?.close()
+    this.owner?.close()
+    this.owner = null
     this.db = null
   }
 }
@@ -1447,7 +1513,7 @@ function hasColumn(db: { prepare: (sql: string) => { all: (...params: unknown[])
 
 function sourceKey(source: KnowledgeSource): string {
   return source.documentId
-    ? `d\u0001${source.documentId}\u0001${source.quote}`
+    ? `d\u0001${source.documentId}\u0001${source.toVersion ?? ''}\u0001${source.quote}`
     : `h\u0001${source.author}\u0001${source.statement}`
 }
 
@@ -1482,6 +1548,8 @@ function knowledgeSnapshot(row: Record<string, unknown>): Record<string, unknown
 function rowToKnowledge(row: Record<string, unknown>, sourceRows: Array<Record<string, unknown>>): Knowledge {
   return {
     id: String(row.id),
+    kind: (String(row.kind ?? 'fact')) as KnowledgeKind,
+    ...(row.payload && row.payload !== '{}' ? { data: JSON.parse(String(row.payload)) as KnowledgeContent } : {}),
     text: String(row.text),
     objectId: String(row.object_id ?? ''),
     actionId: String(row.action_id ?? ''),
@@ -1500,6 +1568,7 @@ function rowToKnowledge(row: Record<string, unknown>, sourceRows: Array<Record<s
       author: String(source.author ?? ''),
       statement: String(source.statement ?? ''),
       ...(source.to_version === null || source.to_version === undefined ? {} : { toVersion: Number(source.to_version) }),
+      ...(Number(source.withdrawn) === 1 ? { withdrawn: true } : {}),
       createdAt: String(source.created_at),
     })),
   }

package/src/layout.ts

@@ -115,7 +115,6 @@
 import { existsSync, mkdirSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { basename, dirname, join, resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
 
 /**
  * 根路径下固定存在的段。顺序即它们在文档与界面里出现的顺序。
@@ -129,7 +128,7 @@ import { fileURLToPath } from 'node:url'
  * **`output` 不在这里。** 交付物是**某个工作项目的产物**，不是这个 Agent 的固有状态：
  * 「分析华东区渠道压货」产出的那几张图属于那个项目，换一个项目打开就不该再看见它。
  * 所以它落在**当前工作区**的 `output/<日期>/` 下，而不是跟着 Agent 的家走。
- * 约定写在 preset 的人格提示词里（`preset/tita-data-agent/agent.cordis.yml` 的工作规则）。
+ * 约定写在知识插件追加到标准模式系统提示词的行为规则里。
  */
 export const AGENT_DIRS = ['domain_knowledge', 'memory', 'intent', 'tmp', 'resource'] as const
 export type AgentDirName = typeof AGENT_DIRS[number]
@@ -173,22 +172,26 @@ export const MEMORY_DIR = 'memory'
 export const INTENT_DIR = 'intent'
 
 /**
- * 默认根路径：`~/Desktop/titaagent`。
+ * 默认根路径：`~/.dsh/tita-agent`。
  *
- * 落在**桌面**是刻意的：这四段目录是用户自己的东西，放在一个他们看得见、能直接
- * 打开、能自己备份的位置，比藏进 `~/.tita-data-agent` 更诚实。这也正是 0029 之前
- * 默认知识树的位置（`~/Desktop/titaagent/domain_knowledge`），所以对没改过设置的
- * 用户来说，知识树**原地不动**。
+ * `.dsh` 是 DSH 的用户级数据根；`tita-agent` 是本插件的专属目录。知识、记忆、意图、
+ * 临时态与运行所需家当都收在这里，用户不需要再管理一条插件自己的路径。
  */
 export function defaultAgentRoot(): string {
-  return resolve(process.env.DSH_AGENT_ROOT || join(homedir(), 'Desktop', 'titaagent'))
+  const dshHome = process.env.DSH_HOME?.trim() || join(homedir(), '.dsh')
+  return resolve(join(dshHome, 'tita-agent'))
+}
+
+/** 旧版本默认的 Agent 根，只用于一次性迁移。 */
+export function legacyDefaultAgentRoot(): string {
+  return resolve(join(homedir(), 'Desktop', 'titaagent'))
 }
 
 /** 0029 之前的知识树根：用户显式设过的 `rootDir`，或旧默认位置。只用于迁移。 */
 export function legacyKnowledgeRoot(): string {
   const inRepo = join(process.cwd(), 'domain_knowledge')
   return resolve(process.env.DSH_KNOWLEDGE_ROOT
-    || (existsSync(inRepo) ? inRepo : join(defaultAgentRoot(), DOMAIN_KNOWLEDGE_DIR)))
+    || (existsSync(inRepo) ? inRepo : join(legacyDefaultAgentRoot(), DOMAIN_KNOWLEDGE_DIR)))
 }
 
 /**
@@ -199,7 +202,7 @@ export function legacyKnowledgeRoot(): string {
  * 按 cwd 决定搬谁太危险 —— 一个恰好放了对拍夹具的目录会被搬去桌面。
  */
 export function legacyDefaultKnowledgeRoot(): string {
-  return resolve(process.env.DSH_KNOWLEDGE_ROOT || join(defaultAgentRoot(), DOMAIN_KNOWLEDGE_DIR))
+  return resolve(process.env.DSH_KNOWLEDGE_ROOT || join(legacyDefaultAgentRoot(), DOMAIN_KNOWLEDGE_DIR))
 }
 
 /** `<agentRoot>/domain_knowledge`。 */
@@ -225,8 +228,8 @@ export function knowledgeBaseRoot(agentRoot: string, kbId: string): string {
  *
  * 二级目录按日期分桶（`output/<YYYY-MM-DD>/`），由转换内核的 `bucketByDay` 打开；
  * 再下一级是**文档的中文名**（`dsh-convert-core` 的 `deliveryDirName(label)`：取标题，
- * 没有标题取文件名，≤25 字，同名让路 `-2`）。Agent 自己写文件时的命名约定见 preset
- * 的人格提示词 —— 同一个规则有两处措辞（提示词约束 Agent、代码约束内核），改请一起改。
+ * 没有标题取文件名，≤25 字，同名让路 `-2`）。Agent 自己写文件时的命名约定见
+ * `agent-behavior-rules.ts` —— 提示词约束 Agent，代码约束内核，改动时一起更新。
  *
  * @param workspace - 当前工作项目的绝对路径。
  */
@@ -239,31 +242,6 @@ export function tmpRoot(agentRoot: string): string {
   return join(resolve(agentRoot), TMP_DIR)
 }
 
-/**
- * 随插件分发的 preset **真源目录**：`<包根>/preset/tita-data-agent/`。
- *
- * ## 它和「DSH 装好的 preset」不是一回事
- *
- * 0.1.7 起 DSH 那边 preset 不再是一个目录，而是 profile 组合里的一条声明行
- * （见 docs/current/06-Agent-preset的注入形态.md）。但**写提示词的人需要一个能编辑的地方**，那个地方就是这里：
- * `agent.cordis.yml` 的 `persona` 行是提示词的唯一真源，改完跑 `pnpm sync:preset`
- * 把它编译进 `cordis.patch.yml`。所以「打开 preset 目录」打开的是这个目录 ——
- * 不是 DSH 内部某个装好的副本（那种副本不存在，存在也会被下次编译覆盖）。
- *
- * 从 `lib/types/index.js` 回退两级就是包根，所以这个路径在源码仓库里跑和从
- * npm 安装后跑都成立。路径不存在时调用方应当如实说明，而不是弹一个空目录。
- */
-export function presetSourceDir(): string {
-  return resolve(dirname(fileURLToPath(import.meta.url)), '../../preset', TITA_PRESET_ID)
-}
-
-/**
- * 这个 preset 的 id。与 `src/client/agent-preset.ts` 的 `TITA_PRESET_ID`、
- * `scripts/install-agent-preset.mjs` 的 `PRESET_ID` 是同一个值 —— 三处各留一份
- * 是因为它们分属三个编译单元（宿主 / 浏览器 / 脚本），测试会钉住它们一致。
- */
-export const TITA_PRESET_ID = 'tita-data-agent'
-
 /** `<agentRoot>/resource`。 */
 export function resourceRoot(agentRoot: string): string {
   return join(resolve(agentRoot), RESOURCE_DIR)
@@ -377,6 +355,8 @@ export function intentRoot(agentRoot: string): string {
 export const KNOWLEDGE_DB_FILE = 'knowledge.db'
 export const DERIVED_DB_FILE = 'derived.db'
 export const ASSETS_DIR = 'assets'
+/** Hidden marker: standalone published images must survive source/card orphan sweeps. */
+export const PUBLISHED_IMAGE_MARKER = '.dsh-published-image'
 /**
  * 原始输入的落点（0067）。与 {@link ASSETS_DIR} **并列且同构**：一个装内容里提取出来的
  * 图，一个装用户送进来的原件 —— 两者都是「从这个知识库里能直接拿到手的东西」，

package/src/materialize-snapshot.ts

@@ -0,0 +1,46 @@
+/**
+ * 物化阶段的语料快照（0070）—— **只有服务端看得见**。
+ *
+ * 它刻意不放在 `pipeline/types.ts` 里：那个模块被客户端 import（`PIPELINE_ACTIVE_STATES`
+ * 这类值），而本文件的字段类型来自 `knowledge.ts` / `events.ts` / `source-images.ts` /
+ * `card-organize.ts`，它们全都 `import 'node:…'`。把服务端模块拉进客户端的类型程序，
+ * 浏览器与 Node 的类型边界就没了（这条规矩写在 `wiki-trial-types.ts` 里）。
+ * 引擎只把这个对象原样传回去，所以它在引擎那边是 `unknown`。
+ *
+ * ## 为什么是「一次阶段运行算一份」
+ *
+ * 物化是逐组的，而每一组都要用到全库的东西：别组的正文（图片分发）、全部卡片（相关推荐）、
+ * 全部事件、全部知识。每组现算一遍就是 O(组数 × 语料) —— 几百张卡时单线程跑不完。
+ *
+ * ## 快照的边界
+ *
+ * 语料在**同一条串行队列里**是不变的（归一排在物化后面）。但别的写入者（另一个进程、
+ * 同一个库的另一条路径）不受这条队列约束，所以写回之前仍然要**单独复查这一组**的
+ * 事实（`freshGroupFingerprint`）；而**人工裁决**从来不被快照 —— 卡片状态在每次写之前
+ * 重读并与旧值比对（见 `materializePipelineGroup`）。
+ */
+import type { OrganizeRelatedCandidate } from './card-organize.js'
+import type { EventEntity } from './events.js'
+import type { Knowledge } from './knowledge.js'
+import type { MaterializationGroup } from './pipeline/types.js'
+import type { SourceImage } from './source-images.js'
+
+export interface MaterializationSnapshot {
+  groups: MaterializationGroup[]
+  /** 坐标仍有歧义 + 等待归一，两部分的合计（分开的两个字段见下）。 */
+  blocked: number
+  /** 坐标仍有歧义的 Knowledge 条数。这些行不属于任何分组。 */
+  blockedAmbiguous: number
+  /** 来源已变化 / 新抽取尚未归一的 Knowledge 条数。 */
+  blockedAwaitingNormalize: number
+  /** key → 这一组参与成卡的知识。 */
+  knowledge: Map<string, Knowledge[]>
+  /** key → 这一组的 Event。 */
+  events: Map<string, EventEntity[]>
+  /** 图片分发：全部来源正文，阶段内只读一次。 */
+  sources: Array<{ sourceId: string; content: string }>
+  /** 图片分发计划：整库算一次，按组取。 */
+  images: Map<string, SourceImage[]>
+  /** 相关推荐计划：整库算一次，按组取（键是分组键，不是卡片身份）。 */
+  related: Map<string, OrganizeRelatedCandidate[]>
+}