@co-engram/core 0.1.5 → 0.1.6

package/dist/storage/bootstrap.d.ts

@@ -0,0 +1,31 @@
+import type { Language } from "../i18n/index.js";
+import { type SearchEngine, type SearchEngineType } from "../retrieval/search-engine.js";
+import { EngramRepository } from "./repository.js";
+import { IndexDb } from "./index-db.js";
+export interface BootstrapOptions {
+    readonly dataRoot: string;
+    readonly language?: Language;
+    /** 注入 env(测试用);默认 process.env */
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface BootstrapResult {
+    readonly repository: EngramRepository;
+    readonly searchEngine: SearchEngine;
+    readonly engineType: SearchEngineType;
+    /** SQLite 模式下的 indexDb 引用;memory 模式为 undefined。host 持有以在
+     *  关闭时显式 close()(进程退出时 OS 自动回收 fd,但测试 / 显式资源管理
+     *  需要确定性释放)。 */
+    readonly indexDb?: IndexDb;
+}
+/**
+ * 装配 EngramRepository + SearchEngine。
+ *
+ * Engine 选择:env.CO_ENGRAM_SEARCH_ENGINE=sqlite → SQLite FTS5 模式;
+ * 未设置 / 其他值 → 默认 memory(in-memory Intl.Segmenter)。
+ *
+ * Cold start 行为(sqlite 模式):db 为空时,从 repository.listEngrams()
+ * 枚举全量 engram,readEngram() 读详情,转 EngramIndexEntry[] 后
+ * rebuildFromEntries() 一次性灌入。已有数据的 db 不重建。
+ */
+export declare function bootstrapRepositoryAndSearch(opts: BootstrapOptions): BootstrapResult;
+//# sourceMappingURL=bootstrap.d.ts.map

package/dist/storage/bootstrap.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.d.ts","sourceRoot":"","sources":["../../src/storage/bootstrap.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,gBAAgB,EACtB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACnD,OAAO,EAAE,OAAO,EAAyB,MAAM,eAAe,CAAC;AAE/D,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC;IAC7B,iCAAiC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IACpC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC;IACtC;;oBAEgB;IAChB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;;;GASG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,gBAAgB,GACrB,eAAe,CAkDjB"}

package/dist/storage/bootstrap.js

@@ -0,0 +1,89 @@
+// packages/core/src/storage/bootstrap.ts
+//
+// 装配 EngramRepository + SearchEngine —— 把 host adapter(claude-code-mcp /
+// openclaw-plugin)共用的初始化逻辑抽到 core,避免双宿主行为漂移。
+//
+// 默认行为(memory 模式)完全等同此前各 host 内联的 new SearchOrchestrator()
+// + rebuildSearchIndex。sqlite 模式额外做:
+//   1. 打开 .co-engram/index.db(WAL,首次自动建 schema)
+//   2. 把 indexDb 注入 EngramRepository(开启 write-through)
+//   3. Cold start:db 为空时从 engrams/*.md 全量重建索引
+//   4. 用 SqliteSearchEngineAdapter 包装 SearchEngine
+//
+// @module @co-engram/core/storage
+import { existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { createSearchEngine, resolveSearchEngineType, } from "../retrieval/search-engine.js";
+import { EngramRepository } from "./repository.js";
+import { IndexDb } from "./index-db.js";
+/**
+ * 装配 EngramRepository + SearchEngine。
+ *
+ * Engine 选择:env.CO_ENGRAM_SEARCH_ENGINE=sqlite → SQLite FTS5 模式;
+ * 未设置 / 其他值 → 默认 memory(in-memory Intl.Segmenter)。
+ *
+ * Cold start 行为(sqlite 模式):db 为空时,从 repository.listEngrams()
+ * 枚举全量 engram,readEngram() 读详情,转 EngramIndexEntry[] 后
+ * rebuildFromEntries() 一次性灌入。已有数据的 db 不重建。
+ */
+export function bootstrapRepositoryAndSearch(opts) {
+    const engineType = resolveSearchEngineType(opts.env);
+    if (engineType === "sqlite") {
+        const dbDir = join(opts.dataRoot, ".co-engram");
+        if (!existsSync(dbDir))
+            mkdirSync(dbDir, { recursive: true });
+        const dbPath = join(dbDir, "index.db");
+        const indexDb = new IndexDb({ dbPath });
+        indexDb.open();
+        // 先构造 repository with indexDb,write-through 在后续所有写入路径生效
+        const repository = new EngramRepository({
+            rootPath: opts.dataRoot,
+            ...(opts.language ? { language: opts.language } : {}),
+        }, indexDb);
+        // Cold start:db 空时全量重建
+        const count = indexDb.prepare("SELECT count(*) as n FROM engrams").get();
+        if (count.n === 0) {
+            const entries = [];
+            // listEngrams 返回 EngramCatalogEntry[],取 .id 作为 readEngram 入参
+            for (const catalog of repository.listEngrams()) {
+                try {
+                    const engram = repository.readEngram(catalog.id);
+                    if (!engram)
+                        continue;
+                    entries.push(engramToIndexEntry(engram));
+                }
+                catch {
+                    // 跳过损坏 engram;doctor 自愈路径会单独处理
+                }
+            }
+            indexDb.rebuildFromEntries(entries);
+        }
+        const searchEngine = createSearchEngine({ type: "sqlite", indexDb });
+        return { repository, searchEngine, engineType, indexDb };
+    }
+    // memory 模式:行为与原 host 内联代码等价
+    const repository = new EngramRepository({
+        rootPath: opts.dataRoot,
+        ...(opts.language ? { language: opts.language } : {}),
+    });
+    const searchEngine = createSearchEngine({ type: "memory" });
+    return { repository, searchEngine, engineType };
+}
+/** Engram → EngramIndexEntry 投影(与 repository.syncEngramToIndex 同义) */
+function engramToIndexEntry(e) {
+    return {
+        id: e.id,
+        title: e.title,
+        kind: e.kind,
+        importance: e.importance,
+        confidence: e.confidence,
+        updatedAt: Date.parse(e.updatedAt),
+        contentSize: e.contentSize,
+        visibility: e.visibility,
+        status: e.status,
+        domainTags: [...e.domainTags],
+        summary: e.summary,
+        contentTokens: e.content,
+    };
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/storage/bootstrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bootstrap.js","sourceRoot":"","sources":["../../src/storage/bootstrap.ts"],"names":[],"mappings":"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"}

package/dist/storage/index-db-cursor.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 稳定排序键:importance DESC, updatedAt DESC, id ASC
+ *
+ * cursor 是 opaque base64url token,encode 当前页最后一条的 sort key,
+ * 让下一页查询能"接着"这个位置往后取(避免 offset 漂移导致的数据跳过/重复)。
+ *
+ * 选择 base64url 而非 base64:cursor 经常出现在 URL query string,
+ * base64url 无需 URL encode(+ / = 等特殊字符)。
+ */
+export interface SortKey {
+    readonly importance: number;
+    readonly updatedAt: number;
+    readonly id: string;
+}
+export declare function encodeCursor(key: SortKey): string;
+export declare function decodeCursor(cursor: string): SortKey;
+/**
+ * 比较两个 sort key,返回 -1 / 0 / 1。
+ * 返回 -1 表示 a 排在 b 前面;1 表示 a 排在 b 后面;0 表示相等。
+ *
+ * 顺序:importance 大→小;同分 updatedAt 新→旧;再同分 id 字典序升序(稳定)。
+ *
+ * 用于 cursor 分页:取出 cursor 之后,过滤掉所有 compareSortKey(key, cursor) <= 0 的项
+ * (cursor 之前或等于的项跳过),从下一个开始取。
+ */
+export declare function compareSortKey(a: SortKey, b: SortKey): number;
+//# sourceMappingURL=index-db-cursor.d.ts.map

package/dist/storage/index-db-cursor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-db-cursor.d.ts","sourceRoot":"","sources":["../../src/storage/index-db-cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,OAAO;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACpB;AAED,wBAAgB,YAAY,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAIjD;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAwBpD;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,GAAG,MAAM,CAK7D"}

package/dist/storage/index-db-cursor.js

@@ -0,0 +1,59 @@
+/**
+ * 稳定排序键:importance DESC, updatedAt DESC, id ASC
+ *
+ * cursor 是 opaque base64url token,encode 当前页最后一条的 sort key,
+ * 让下一页查询能"接着"这个位置往后取(避免 offset 漂移导致的数据跳过/重复)。
+ *
+ * 选择 base64url 而非 base64:cursor 经常出现在 URL query string,
+ * base64url 无需 URL encode(+ / = 等特殊字符)。
+ */
+export function encodeCursor(key) {
+    // 用数组而非 object:更紧凑,且避免 key 顺序歧义
+    const json = JSON.stringify([key.importance, key.updatedAt, key.id]);
+    return Buffer.from(json, "utf8").toString("base64url");
+}
+export function decodeCursor(cursor) {
+    if (!cursor)
+        throw new Error("invalid cursor: empty");
+    let json;
+    try {
+        json = Buffer.from(cursor, "base64url").toString("utf8");
+    }
+    catch {
+        throw new Error("invalid cursor: base64 decode failed");
+    }
+    let arr;
+    try {
+        arr = JSON.parse(json);
+    }
+    catch {
+        throw new Error("invalid cursor: JSON parse failed");
+    }
+    if (!Array.isArray(arr) ||
+        arr.length !== 3 ||
+        typeof arr[0] !== "number" ||
+        typeof arr[1] !== "number" ||
+        typeof arr[2] !== "string") {
+        throw new Error("invalid cursor: shape mismatch");
+    }
+    return { importance: arr[0], updatedAt: arr[1], id: arr[2] };
+}
+/**
+ * 比较两个 sort key,返回 -1 / 0 / 1。
+ * 返回 -1 表示 a 排在 b 前面;1 表示 a 排在 b 后面;0 表示相等。
+ *
+ * 顺序:importance 大→小;同分 updatedAt 新→旧;再同分 id 字典序升序(稳定)。
+ *
+ * 用于 cursor 分页:取出 cursor 之后,过滤掉所有 compareSortKey(key, cursor) <= 0 的项
+ * (cursor 之前或等于的项跳过),从下一个开始取。
+ */
+export function compareSortKey(a, b) {
+    if (a.importance !== b.importance)
+        return a.importance > b.importance ? -1 : 1;
+    if (a.updatedAt !== b.updatedAt)
+        return a.updatedAt > b.updatedAt ? -1 : 1;
+    if (a.id !== b.id)
+        return a.id < b.id ? -1 : 1;
+    return 0;
+}
+//# sourceMappingURL=index-db-cursor.js.map

package/dist/storage/index-db-cursor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-db-cursor.js","sourceRoot":"","sources":["../../src/storage/index-db-cursor.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAQH,MAAM,UAAU,YAAY,CAAC,GAAY;IACxC,gCAAgC;IAChC,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,UAAU,EAAE,GAAG,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC;IACrE,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;AACxD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,MAAc;IAC1C,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC;IACtD,IAAI,IAAY,CAAC;IACjB,IAAI,CAAC;QACJ,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACR,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;IACzD,CAAC;IACD,IAAI,GAAY,CAAC;IACjB,IAAI,CAAC;QACJ,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACR,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;IACtD,CAAC;IACD,IACC,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QACnB,GAAG,CAAC,MAAM,KAAK,CAAC;QAChB,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,QAAQ;QAC1B,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,QAAQ;QAC1B,OAAO,GAAG,CAAC,CAAC,CAAC,KAAK,QAAQ,EACzB,CAAC;QACF,MAAM,IAAI,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACnD,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;AAC9D,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,CAAU,EAAE,CAAU;IACpD,IAAI,CAAC,CAAC,UAAU,KAAK,CAAC,CAAC,UAAU;QAAE,OAAO,CAAC,CAAC,UAAU,GAAG,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,IAAI,CAAC,CAAC,SAAS,KAAK,CAAC,CAAC,SAAS;QAAE,OAAO,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E,IAAI,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,EAAE;QAAE,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,OAAO,CAAC,CAAC;AACV,CAAC"}

package/dist/storage/index-db.d.ts

@@ -0,0 +1,112 @@
+declare const DatabaseSync: typeof import("node:sqlite").DatabaseSync;
+type SqliteDb = InstanceType<typeof DatabaseSync>;
+type Statement = ReturnType<SqliteDb["prepare"]>;
+export interface IndexDbOptions {
+    readonly dbPath: string;
+    /** true = 删除现有 db 文件后重建(plan Task 1.3 暂未实现 reset 逻辑,占位字段) */
+    readonly reset?: boolean;
+}
+/**
+ * engram 在索引层的一份精简投影(只含搜索/排序/FTS 需要的字段)。
+ *
+ * domainTags 是多值字段,在 SQLite 端拆 engram_domains 表;其余标量字段直接落 engrams 主表。
+ * contentTokens 是已切分的纯文本(可能含空格分隔的 token),用于 FTS5 trigram 倒排。
+ */
+export interface EngramIndexEntry {
+    readonly id: string;
+    readonly title: string;
+    readonly kind: string;
+    readonly importance: number;
+    readonly confidence: number;
+    /** epoch ms */
+    readonly updatedAt: number;
+    readonly contentSize: number;
+    readonly visibility: string;
+    readonly status: string;
+    readonly domainTags: readonly string[];
+    readonly summary: string;
+    readonly contentTokens: string;
+}
+/**
+ * 突触(synapse)索引条目。外键 from_id / to_id 引用 engrams 主表,
+ * 删除任一端 engram 时由 ON DELETE CASCADE 自动清空。
+ */
+export interface SynapseIndexEntry {
+    readonly id: string;
+    readonly fromId: string;
+    readonly toId: string;
+    readonly kind: string;
+    readonly weight: number;
+}
+/**
+ * SQLite 索引库封装:打开 / schema 初始化 / 显式事务。
+ *
+ * 设计要点:
+ * - WAL 模式:多读单写,显著降低并发读写冲突,适合 engram write-through 场景。
+ * - 显式 BEGIN/COMMIT/ROLLBACK:node:sqlite 默认隐式事务,显式包裹保证多语句原子性。
+ * - schema 通过外部 .sql 文件管理,便于审计和迁移工具比对。
+ */
+export declare class IndexDb {
+    private db;
+    private readonly opts;
+    constructor(opts: IndexDbOptions);
+    open(): void;
+    close(): void;
+    prepare(sql: string): Statement;
+    exec(sql: string): void;
+    /**
+     * 在事务中执行回调,失败 rollback。
+     * 注意:node:sqlite 的 DatabaseSync 默认每条语句隐式事务,
+     * 但我们用 BEGIN/COMMIT/ROLLBACK 显式包裹,确保多语句原子性。
+     */
+    transaction<T>(fn: () => T): T;
+    private requireOpen;
+    /**
+     * UPSERT 一个 engram 索引条目:主表 + domains(全量替换)+ FTS(delete+insert)。
+     *
+     * 实现要点:
+     * - 整体在事务内,任一步失败 rollback,保证主表/domains/FTS 三地一致。
+     * - domains 用 DELETE+INSERT 而非 ON CONFLICT:语义上是"全量替换 tag 集合",
+     *   调用方传入的新集合就是真理源,旧 tag 不在该集合内就该被清掉。
+     * - FTS5 不支持 ON CONFLICT,只能 delete + insert;否则会有重复倒排项。
+     */
+    upsertEngram(entry: EngramIndexEntry): void;
+    /**
+     * 内部 UPSERT(无事务包裹)。调用方必须已在外层 transaction 内。
+     *
+     * 单条写入走 upsertEngram;批量 cold start rebuild 走 rebuildFromEntries,
+     * 后者在单个 transaction 里循环调用本方法,避免每条都 BEGIN/COMMIT。
+     */
+    private upsertEngramUnsafe;
+    /**
+     * Cold start 重建:用 entries 全量替换 SQLite 索引内容。
+     *
+     * 用例:host 启动时检测到 .co-engram/index.db 缺失或损坏 → 扫描所有
+     * engrams/*.md → 调本方法一次性灌入。
+     *
+     * 实现:
+     * - 单个 transaction 内:DELETE engrams(CASCADE 清 domains + synapses)
+     *   + DELETE engram_fts(FTS 不参与外键,手动清)+ 批量 upsertEngramUnsafe。
+     * - 中途任一步失败 → rollback,SQLite 保持原状(数据可能旧但一致)。
+     * - 调用方决定是否清空 synapses:本方法不重建 synapses(它们由 synapse
+     *   create 路径单独维护),CASCADE 会把它们一并清掉,rebuild 期间 synapse
+     *   数据丢失是可接受的(可以从 markdown frontmatter 重新解析)。
+     */
+    rebuildFromEntries(entries: readonly EngramIndexEntry[]): void;
+    /**
+     * UPSERT 一条 synapse。无 FTS,单语句即可,不需要事务包裹。
+     */
+    upsertSynapse(s: SynapseIndexEntry): void;
+    /**
+     * 删除一个 engram 及其所有派生数据。
+     *
+     * - engrams 主表:显式 DELETE。
+     * - engram_domains / synapses(from/to):外键 ON DELETE CASCADE 自动清。
+     * - engram_fts:FTS5 表不参与外键,必须显式 DELETE。
+     *
+     * 包在事务里:即便 FTS 删除失败,主表删除也会 rollback,保持一致。
+     */
+    deleteEngram(engramId: string): void;
+}
+export {};
+//# sourceMappingURL=index-db.d.ts.map

package/dist/storage/index-db.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-db.d.ts","sourceRoot":"","sources":["../../src/storage/index-db.ts"],"names":[],"mappings":"AAiBA,QAAA,MAAM,YAAY,2CAA4B,CAAC;AAI/C,KAAK,QAAQ,GAAG,YAAY,CAAC,OAAO,YAAY,CAAC,CAAC;AAClD,KAAK,SAAS,GAAG,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;AAKjD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,eAAe;IACf,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;;;;GAOG;AACH,qBAAa,OAAO;IAClB,OAAO,CAAC,EAAE,CAAyB;IACnC,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAiB;gBAE1B,IAAI,EAAE,cAAc;IAIhC,IAAI,IAAI,IAAI;IAaZ,KAAK,IAAI,IAAI;IAMb,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS;IAK/B,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAKvB;;;;OAIG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAiB9B,OAAO,CAAC,WAAW;IAMnB;;;;;;;;OAQG;IACH,YAAY,CAAC,KAAK,EAAE,gBAAgB,GAAG,IAAI;IAI3C;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;IAuC1B;;;;;;;;;;;;;OAaG;IACH,kBAAkB,CAAC,OAAO,EAAE,SAAS,gBAAgB,EAAE,GAAG,IAAI;IAU9D;;OAEG;IACH,aAAa,CAAC,CAAC,EAAE,iBAAiB,GAAG,IAAI;IAYzC;;;;;;;;OAQG;IACH,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;CAMrC"}

package/dist/storage/index-db.js

@@ -0,0 +1,183 @@
+// packages/core/src/storage/index-db.ts
+// 用 createRequire 绕过 Vite 静态分析:`import { DatabaseSync } from "node:sqlite"`
+// 在 vitest 2.x 下会被 Vite resolver 拦截,报 `Failed to load url sqlite`
+// (stripping `node:` prefix)。createRequire 在运行时调用,Vite 无法静态解析,
+// 直接走 Node builtin resolver —— 同 test/storage/node-sqlite-smoke.test.ts 的 workaround。
+//
+// 字符串拼接 `"node:" + "sqlite"` 进一步防止 Vite 把整个 require 调用静态化为
+// bare import 解析。type import 在编译时被擦除,不被 resolver 拦截,可以安全使用。
+import { createRequire } from "node:module";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const require = createRequire(import.meta.url);
+const SQLITE_MODULE = "node:" + "sqlite";
+const sqliteModule = require(SQLITE_MODULE);
+const DatabaseSync = sqliteModule.DatabaseSync;
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const SCHEMA_PATH = join(__dirname, "index-db-schema.sql");
+/**
+ * SQLite 索引库封装:打开 / schema 初始化 / 显式事务。
+ *
+ * 设计要点:
+ * - WAL 模式:多读单写,显著降低并发读写冲突,适合 engram write-through 场景。
+ * - 显式 BEGIN/COMMIT/ROLLBACK:node:sqlite 默认隐式事务,显式包裹保证多语句原子性。
+ * - schema 通过外部 .sql 文件管理,便于审计和迁移工具比对。
+ */
+export class IndexDb {
+    db = null;
+    opts;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    open() {
+        if (this.db)
+            return;
+        this.db = new DatabaseSync(this.opts.dbPath);
+        // WAL 模式 + 外键 + 性能调优
+        this.db.exec("PRAGMA journal_mode = WAL");
+        this.db.exec("PRAGMA synchronous = NORMAL");
+        this.db.exec("PRAGMA foreign_keys = ON");
+        this.db.exec("PRAGMA busy_timeout = 5000");
+        // 初始化 schema
+        const schema = readFileSync(SCHEMA_PATH, "utf8");
+        this.db.exec(schema);
+    }
+    close() {
+        if (!this.db)
+            return;
+        this.db.close();
+        this.db = null;
+    }
+    prepare(sql) {
+        this.requireOpen();
+        return this.db.prepare(sql);
+    }
+    exec(sql) {
+        this.requireOpen();
+        this.db.exec(sql);
+    }
+    /**
+     * 在事务中执行回调,失败 rollback。
+     * 注意:node:sqlite 的 DatabaseSync 默认每条语句隐式事务,
+     * 但我们用 BEGIN/COMMIT/ROLLBACK 显式包裹,确保多语句原子性。
+     */
+    transaction(fn) {
+        this.requireOpen();
+        this.db.exec("BEGIN");
+        try {
+            const result = fn();
+            this.db.exec("COMMIT");
+            return result;
+        }
+        catch (err) {
+            try {
+                this.db.exec("ROLLBACK");
+            }
+            catch {
+                // ignore rollback failure
+            }
+            throw err;
+        }
+    }
+    requireOpen() {
+        if (!this.db) {
+            throw new Error("IndexDb not opened. Call open() first.");
+        }
+    }
+    /**
+     * UPSERT 一个 engram 索引条目:主表 + domains(全量替换)+ FTS(delete+insert)。
+     *
+     * 实现要点:
+     * - 整体在事务内,任一步失败 rollback,保证主表/domains/FTS 三地一致。
+     * - domains 用 DELETE+INSERT 而非 ON CONFLICT:语义上是"全量替换 tag 集合",
+     *   调用方传入的新集合就是真理源,旧 tag 不在该集合内就该被清掉。
+     * - FTS5 不支持 ON CONFLICT,只能 delete + insert;否则会有重复倒排项。
+     */
+    upsertEngram(entry) {
+        this.transaction(() => this.upsertEngramUnsafe(entry));
+    }
+    /**
+     * 内部 UPSERT(无事务包裹)。调用方必须已在外层 transaction 内。
+     *
+     * 单条写入走 upsertEngram;批量 cold start rebuild 走 rebuildFromEntries,
+     * 后者在单个 transaction 里循环调用本方法,避免每条都 BEGIN/COMMIT。
+     */
+    upsertEngramUnsafe(entry) {
+        this.prepare(`
+      INSERT INTO engrams (id, title, kind, importance, confidence, updated_at, content_size, visibility, status)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        title = excluded.title,
+        kind = excluded.kind,
+        importance = excluded.importance,
+        confidence = excluded.confidence,
+        updated_at = excluded.updated_at,
+        content_size = excluded.content_size,
+        visibility = excluded.visibility,
+        status = excluded.status
+    `).run(entry.id, entry.title, entry.kind, entry.importance, entry.confidence, entry.updatedAt, entry.contentSize, entry.visibility, entry.status);
+        // domains 全量替换
+        this.prepare("DELETE FROM engram_domains WHERE engram_id = ?").run(entry.id);
+        const insertDomain = this.prepare("INSERT OR IGNORE INTO engram_domains (engram_id, domain) VALUES (?, ?)");
+        for (const d of entry.domainTags) {
+            insertDomain.run(entry.id, d);
+        }
+        // FTS5 不支持 ON CONFLICT,delete + insert
+        this.prepare("DELETE FROM engram_fts WHERE id = ?").run(entry.id);
+        this.prepare("INSERT INTO engram_fts (id, title, summary, content_tokens) VALUES (?, ?, ?, ?)").run(entry.id, entry.title, entry.summary, entry.contentTokens);
+    }
+    /**
+     * Cold start 重建:用 entries 全量替换 SQLite 索引内容。
+     *
+     * 用例:host 启动时检测到 .co-engram/index.db 缺失或损坏 → 扫描所有
+     * engrams/*.md → 调本方法一次性灌入。
+     *
+     * 实现:
+     * - 单个 transaction 内:DELETE engrams(CASCADE 清 domains + synapses)
+     *   + DELETE engram_fts(FTS 不参与外键,手动清)+ 批量 upsertEngramUnsafe。
+     * - 中途任一步失败 → rollback,SQLite 保持原状(数据可能旧但一致)。
+     * - 调用方决定是否清空 synapses:本方法不重建 synapses(它们由 synapse
+     *   create 路径单独维护),CASCADE 会把它们一并清掉,rebuild 期间 synapse
+     *   数据丢失是可接受的(可以从 markdown frontmatter 重新解析)。
+     */
+    rebuildFromEntries(entries) {
+        this.transaction(() => {
+            this.exec("DELETE FROM engrams");
+            this.exec("DELETE FROM engram_fts");
+            for (const e of entries) {
+                this.upsertEngramUnsafe(e);
+            }
+        });
+    }
+    /**
+     * UPSERT 一条 synapse。无 FTS,单语句即可,不需要事务包裹。
+     */
+    upsertSynapse(s) {
+        this.prepare(`
+      INSERT INTO synapses (id, from_id, to_id, kind, weight)
+      VALUES (?, ?, ?, ?, ?)
+      ON CONFLICT(id) DO UPDATE SET
+        from_id = excluded.from_id,
+        to_id = excluded.to_id,
+        kind = excluded.kind,
+        weight = excluded.weight
+    `).run(s.id, s.fromId, s.toId, s.kind, s.weight);
+    }
+    /**
+     * 删除一个 engram 及其所有派生数据。
+     *
+     * - engrams 主表:显式 DELETE。
+     * - engram_domains / synapses(from/to):外键 ON DELETE CASCADE 自动清。
+     * - engram_fts:FTS5 表不参与外键,必须显式 DELETE。
+     *
+     * 包在事务里:即便 FTS 删除失败,主表删除也会 rollback,保持一致。
+     */
+    deleteEngram(engramId) {
+        this.transaction(() => {
+            this.prepare("DELETE FROM engrams WHERE id = ?").run(engramId);
+            this.prepare("DELETE FROM engram_fts WHERE id = ?").run(engramId);
+        });
+    }
+}
+//# sourceMappingURL=index-db.js.map

package/dist/storage/index-db.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-db.js","sourceRoot":"","sources":["../../src/storage/index-db.ts"],"names":[],"mappings":"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"}

package/dist/storage/index.d.ts

@@ -13,4 +13,7 @@ export * from "./engram-index.js";
 export * from "./repository.js";
 export * from "./infra-doctor.js";
 export * from "./index-cleanup.js";
+export { IndexDb } from "./index-db.js";
+export type { SynapseIndexEntry } from "./index-db.js";
+export * from "./bootstrap.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/storage/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AAInC,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AACxC,YAAY,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACvD,cAAc,gBAAgB,CAAC"}

package/dist/storage/index.js

@@ -13,4 +13,9 @@ export * from "./engram-index.js";
 export * from "./repository.js";
 export * from "./infra-doctor.js";
 export * from "./index-cleanup.js";
+// index-db.js 显式 re-export:EngramIndexEntry 与 types/repository-types 的同名,
+// 不能 export *;只 re-export 公共符号,需要 EngramIndexEntry 类型时直接从
+// ./index-db.js import(避免命名冲突 + 保持 SQLite 索引层类型在受控范围)。
+export { IndexDb } from "./index-db.js";
+export * from "./bootstrap.js";
 //# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,cAAc,WAAW,CAAC;AAC1B,cAAc,WAAW,CAAC;AAC1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,UAAU,CAAC;AACzB,cAAc,gBAAgB,CAAC;AAC/B,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,0EAA0E;AAC1E,0DAA0D;AAC1D,uDAAuD;AACvD,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAExC,cAAc,gBAAgB,CAAC"}

package/dist/storage/repository.d.ts

@@ -17,6 +17,7 @@ import type { EngramIndexEntry, DoctorReport, PathTreeNode } from "../types/repo
 import { type Language } from "../i18n/index.js";
 import { type EngramFile } from "./engram-store.js";
 import { type EngramIndexMap } from "./engram-index.js";
+import { IndexDb } from "./index-db.js";
 /** Repository 配置 */
 export interface RepositoryConfig {
     /** 仓库根目录(~/team-memory/) */
@@ -61,7 +62,6 @@ export type ExternalMarkdownHook = (params: ExternalMarkdownHookParams) => void;
  * 所有读取方法接受 stable id (ULID)。从 path 读 engram 用 readEngramByPath。
  */
 export declare class EngramRepository {
-    private readonly config;
     private indexCache;
     /**
      * 当前 indexCache 对应的 engram-index.json 磁盘 mtime。
@@ -107,8 +107,36 @@ export declare class EngramRepository {
      * 未设置时 → watcher 发现新 .md 仅记录 orphan,不自动接受(noop)。
      */
     private externalMarkdownHook;
+    private readonly config;
     private readonly language;
-    constructor(config: RepositoryConfig);
+    /**
+     * 可选 SQLite 索引层(用于 FTS 召回 / 排序)。
+     *
+     * 由 host adapter(claude-code-mcp / openclaw-plugin)在装配阶段注入。
+     * 未注入时(向后兼容)所有写入路径行为不变;注入后,createEngram /
+     * updateEngram / deleteEngram / mutateFrontmatter 在文件落盘成功后会
+     * 透明地把 engram 投影 upsert / delete 到 SQLite。
+     *
+     * 写失败由调用方决定是否致命:本 repository 默认 fail-silent(SQLite 是
+     * 派生数据,文件源真理仍然有效;doctor 自愈 + cold start rebuild 最终会
+     * 修复 SQLite 与文件的不一致)。
+     */
+    private readonly indexDb?;
+    constructor(config: RepositoryConfig, indexDb?: IndexDb);
+    /**
+     * 把 EngramFrontmatter + content 投影成 EngramIndexEntry,同步到 SQLite。
+     *
+     * 字段映射决策:
+     *   - contentTokens = content 全文。FTS5 trigram 主要用于召回,词频统计
+     *     不影响排序;SQLite page cache 自管索引大小。content 通常 < 2KB,
+     *     直接全量灌入。
+     *   - updatedAt 由 ISO string 转 epoch ms(Date.parse),与 IndexDb 的
+     *     INTEGER 列对齐。
+     *   - status / visibility / kind 等 union 类型直接 stringify 落 VARCHAR。
+     *
+     * Fail-silent:SQLite 是派生层,任何写失败都不阻塞文件源真理。
+     */
+    private syncEngramToIndex;
     /** 当前写入语言(读取时自动兼容任意语言格式) */
     get currentLanguage(): Language;
     get rootPath(): string;