autosnippet 3.3.7 → 3.3.8

package/dist/lib/repository/knowledge/KnowledgeUnitOfWork.d.ts

@@ -0,0 +1,61 @@
+/**
+ * KnowledgeUnitOfWork — 知识实体写操作的原子协调器
+ *
+ * 策略: "文件优先 + DB 补偿"
+ *
+ *   1. 收集所有 DB 变更意图（不执行）
+ *   2. 依次执行文件操作（writeFileSync 同步写入）
+ *   3. 若任何文件操作失败 → 回滚已完成的文件操作，整体中止
+ *   4. 全部文件操作成功 → 开启 SQLite 事务，提交所有 DB 变更
+ *   5. 若 DB 事务失败 → 文件已写入，下次 SyncService 扫描自动重建 DB
+ *
+ * 为何 "文件优先" 而非 "DB 优先"？
+ *   - .md 文件 = 唯一真相源（第一原则）
+ *   - 文件写成功 + DB 失败 → SyncService 可从文件重建 DB ✅
+ *   - DB 写成功 + 文件写失败 → DB 有记录但无对应文件
+ *     → SyncService 会标记 deprecated → 数据丢失 ❌
+ *   - 文件优先确保：无论哪步失败，.md 文件的存在性始终是判定真相的依据
+ *
+ * 当前代码现状（改造前）：
+ *   - KnowledgeService.create/update: DB 先 → file 后（不一致风险）
+ *   - KnowledgeService.delete: file 先 → DB 后（已是正确顺序）
+ *   - 本 UoW 统一所有操作为 file-first
+ */
+import type { KnowledgeEntry } from '../../domain/knowledge/KnowledgeEntry.js';
+import type { DrizzleDB } from '../../infrastructure/database/drizzle/index.js';
+import type { DrizzleTx } from '../base/RepositoryBase.js';
+import type { KnowledgeFileStore } from './KnowledgeFileStore.js';
+export interface PendingFileOp {
+    type: 'write' | 'move' | 'delete';
+    entry: KnowledgeEntry;
+    /** move 操作的旧路径（用于回滚时恢复） */
+    oldPath?: string;
+}
+export interface UnitOfWorkResult {
+    /** DB 事务是否成功提交 */
+    dbCommitted: boolean;
+    /** 完成的文件操作列表 */
+    fileOpsCompleted: number;
+}
+export declare class FileWriteError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export declare class KnowledgeUnitOfWork {
+    #private;
+    constructor(drizzle: DrizzleDB, fileStore: KnowledgeFileStore);
+    /** 注册 DB 变更意图（延迟执行） */
+    registerDbChange(fn: (tx: DrizzleTx) => void): void;
+    /** 注册文件操作意图 */
+    registerFileOp(op: PendingFileOp): void;
+    /**
+     * 提交：文件操作 → DB 事务
+     *
+     * 失败模式:
+     *   1. 文件写失败：中止，回滚已写文件，不触碰 DB → 干净状态
+     *   2. 文件全成功 + DB 失败：文件已持久化 → SyncService 下次扫描自动补 DB
+     *   3. 文件全成功 + DB 成功：完美一致
+     */
+    commit(): UnitOfWorkResult;
+    /** 回滚：清空所有挂起操作（不执行已注册但未提交的操作） */
+    rollback(): void;
+}

package/dist/lib/repository/knowledge/KnowledgeUnitOfWork.js

@@ -0,0 +1,156 @@
+/**
+ * KnowledgeUnitOfWork — 知识实体写操作的原子协调器
+ *
+ * 策略: "文件优先 + DB 补偿"
+ *
+ *   1. 收集所有 DB 变更意图（不执行）
+ *   2. 依次执行文件操作（writeFileSync 同步写入）
+ *   3. 若任何文件操作失败 → 回滚已完成的文件操作，整体中止
+ *   4. 全部文件操作成功 → 开启 SQLite 事务，提交所有 DB 变更
+ *   5. 若 DB 事务失败 → 文件已写入，下次 SyncService 扫描自动重建 DB
+ *
+ * 为何 "文件优先" 而非 "DB 优先"？
+ *   - .md 文件 = 唯一真相源（第一原则）
+ *   - 文件写成功 + DB 失败 → SyncService 可从文件重建 DB ✅
+ *   - DB 写成功 + 文件写失败 → DB 有记录但无对应文件
+ *     → SyncService 会标记 deprecated → 数据丢失 ❌
+ *   - 文件优先确保：无论哪步失败，.md 文件的存在性始终是判定真相的依据
+ *
+ * 当前代码现状（改造前）：
+ *   - KnowledgeService.create/update: DB 先 → file 后（不一致风险）
+ *   - KnowledgeService.delete: file 先 → DB 后（已是正确顺序）
+ *   - 本 UoW 统一所有操作为 file-first
+ */
+import Logger from '../../infrastructure/logging/Logger.js';
+export class FileWriteError extends Error {
+    constructor(message, options) {
+        super(message, options);
+        this.name = 'FileWriteError';
+    }
+}
+/* ═══ UnitOfWork 实现 ═══ */
+export class KnowledgeUnitOfWork {
+    #drizzle;
+    #fileStore;
+    #pendingFileOps = [];
+    #dbChanges = [];
+    #completedFileOps = [];
+    #logger = Logger.getInstance();
+    constructor(drizzle, fileStore) {
+        this.#drizzle = drizzle;
+        this.#fileStore = fileStore;
+    }
+    /** 注册 DB 变更意图（延迟执行） */
+    registerDbChange(fn) {
+        this.#dbChanges.push(fn);
+    }
+    /** 注册文件操作意图 */
+    registerFileOp(op) {
+        this.#pendingFileOps.push(op);
+    }
+    /**
+     * 提交：文件操作 → DB 事务
+     *
+     * 失败模式:
+     *   1. 文件写失败：中止，回滚已写文件，不触碰 DB → 干净状态
+     *   2. 文件全成功 + DB 失败：文件已持久化 → SyncService 下次扫描自动补 DB
+     *   3. 文件全成功 + DB 成功：完美一致
+     */
+    commit() {
+        // Phase 1: 文件操作 (must-succeed)
+        this.#completedFileOps = [];
+        for (const op of this.#pendingFileOps) {
+            try {
+                this.#executeFileOp(op);
+                this.#completedFileOps.push(op);
+            }
+            catch (err) {
+                // 回滚已完成的文件操作
+                this.#rollbackFileOps();
+                this.#reset();
+                throw new FileWriteError(`File operation failed: ${op.type} for ${op.entry.id}`, {
+                    cause: err,
+                });
+            }
+        }
+        // Phase 2: DB 事务（文件已安全落盘）
+        let dbCommitted = false;
+        if (this.#dbChanges.length > 0) {
+            try {
+                this.#drizzle.transaction((tx) => {
+                    for (const change of this.#dbChanges) {
+                        change(tx);
+                    }
+                });
+                dbCommitted = true;
+            }
+            catch (err) {
+                // DB 失败但文件已写入 → 最终一致性
+                // SyncService.reconcile() 下次运行时会从文件重建 DB 记录
+                this.#logger.warn('UoW: DB transaction failed after file success', {
+                    fileOpsCompleted: this.#completedFileOps.length,
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+        else {
+            dbCommitted = true; // 无 DB 变更时视为成功
+        }
+        const result = {
+            dbCommitted,
+            fileOpsCompleted: this.#completedFileOps.length,
+        };
+        this.#reset();
+        return result;
+    }
+    /** 回滚：清空所有挂起操作（不执行已注册但未提交的操作） */
+    rollback() {
+        this.#reset();
+    }
+    #executeFileOp(op) {
+        switch (op.type) {
+            case 'write':
+                this.#fileStore.persist(op.entry);
+                break;
+            case 'move':
+                this.#fileStore.moveOnLifecycleChange(op.entry);
+                break;
+            case 'delete':
+                this.#fileStore.remove(op.entry);
+                break;
+        }
+    }
+    /** 尽力回滚已完成的文件操作 */
+    #rollbackFileOps() {
+        for (const op of [...this.#completedFileOps].reverse()) {
+            try {
+                switch (op.type) {
+                    case 'write':
+                        this.#fileStore.remove(op.entry); // 回滚写入 → 删除
+                        break;
+                    case 'delete':
+                        this.#fileStore.persist(op.entry); // 回滚删除 → 重写
+                        break;
+                    case 'move':
+                        // move 回滚较复杂，记录日志等 SyncService 修复
+                        this.#logger.warn('UoW: Cannot auto-rollback move op', {
+                            entryId: op.entry.id,
+                        });
+                        break;
+                }
+            }
+            catch {
+                // 回滚失败不再抛出，记录日志
+                this.#logger.error('UoW: File rollback failed', {
+                    type: op.type,
+                    entryId: op.entry.id,
+                });
+            }
+        }
+    }
+    #reset() {
+        this.#dbChanges = [];
+        this.#pendingFileOps = [];
+        this.#completedFileOps = [];
+    }
+}

package/dist/lib/repository/memory/MemoryRepository.d.ts

@@ -0,0 +1,90 @@
+/**
+ * MemoryRepository — Agent 语义记忆的仓储实现
+ *
+ * 从 MemoryStore 提取的数据操作，
+ * 使用 Drizzle 类型安全 API 操作 semantic_memories 表。
+ * embedding 已迁移到 JSON sidecar (MemoryEmbeddingStore)。
+ */
+import { semanticMemories } from '../../infrastructure/database/drizzle/schema.js';
+import { RepositoryBase } from '../base/RepositoryBase.js';
+export interface SemanticMemoryEntity {
+    id: string;
+    type: string;
+    content: string;
+    source: string;
+    importance: number;
+    accessCount: number;
+    lastAccessedAt: string | null;
+    createdAt: string;
+    updatedAt: string;
+    expiresAt: string | null;
+    relatedEntities: string[];
+    relatedMemories: string[];
+    sourceDimension: string | null;
+    sourceEvidence: string | null;
+    bootstrapSession: string | null;
+    tags: string[];
+}
+export interface SemanticMemoryInsert {
+    id: string;
+    type?: string;
+    content: string;
+    source?: string;
+    importance?: number;
+    expiresAt?: string | null;
+    relatedEntities?: string[];
+    sourceDimension?: string | null;
+    sourceEvidence?: string | null;
+    bootstrapSession?: string | null;
+    tags?: string[];
+}
+export interface SemanticMemoryUpdate {
+    content?: string;
+    importance?: number;
+    accessCount?: number;
+    relatedEntities?: string[];
+    relatedMemories?: string[];
+    tags?: string[];
+}
+export interface MemoryStats {
+    total: number;
+    byType: Record<string, number>;
+    bySource: Record<string, number>;
+    avgImportance: number;
+}
+export declare class MemoryRepositoryImpl extends RepositoryBase<typeof semanticMemories, SemanticMemoryEntity> {
+    #private;
+    constructor(drizzle: ConstructorParameters<typeof RepositoryBase<typeof semanticMemories, SemanticMemoryEntity>>[0]);
+    findById(id: string): Promise<SemanticMemoryEntity | null>;
+    create(data: SemanticMemoryInsert): Promise<SemanticMemoryEntity>;
+    delete(id: string): Promise<boolean>;
+    /** 动态字段更新 */
+    update(id: string, updates: SemanticMemoryUpdate): Promise<boolean>;
+    /** 更新访问计数 */
+    touchAccess(id: string): Promise<void>;
+    /** 获取所有活跃记忆 (未过期) */
+    getAllActive(filters?: {
+        source?: string;
+        type?: string;
+    }): Promise<SemanticMemoryEntity[]>;
+    /** 获取候选记忆 (用于相似度搜索) */
+    getCandidates(type: string | null, limit?: number): Promise<SemanticMemoryEntity[]>;
+    /** 记忆总数 */
+    size(filters?: {
+        source?: string;
+    }): Promise<number>;
+    /**
+     * 执行维护: 清理过期记忆 + 自然遗忘 + 重要度衰减
+     */
+    compact(): Promise<{
+        expired: number;
+        forgotten: number;
+        archived: number;
+        remaining: number;
+    }>;
+    /** 容量控制 */
+    enforceCapacity(maxMemories?: number): Promise<number>;
+    getStats(): Promise<MemoryStats>;
+    /** 清除所有 bootstrap 来源的记忆 */
+    clearBootstrapMemories(): Promise<number>;
+}

package/dist/lib/repository/memory/MemoryRepository.js

@@ -0,0 +1,260 @@
+/**
+ * MemoryRepository — Agent 语义记忆的仓储实现
+ *
+ * 从 MemoryStore 提取的数据操作，
+ * 使用 Drizzle 类型安全 API 操作 semantic_memories 表。
+ * embedding 已迁移到 JSON sidecar (MemoryEmbeddingStore)。
+ */
+import { and, avg, count, desc, eq, isNull, or, sql } from 'drizzle-orm';
+import { semanticMemories } from '../../infrastructure/database/drizzle/schema.js';
+import { RepositoryBase } from '../base/RepositoryBase.js';
+/* ═══ 常量 ═══ */
+const MAX_MEMORIES = 500;
+const ARCHIVE_DAYS = 30;
+const FORGET_DAYS = 90;
+/* ═══ Repository 实现 ═══ */
+export class MemoryRepositoryImpl extends RepositoryBase {
+    constructor(drizzle) {
+        super(drizzle, semanticMemories);
+    }
+    /* ─── CRUD ─── */
+    async findById(id) {
+        const row = this.drizzle.select().from(this.table).where(eq(this.table.id, id)).limit(1).get();
+        return row ? this.#mapRow(row) : null;
+    }
+    async create(data) {
+        const now = new Date().toISOString();
+        this.drizzle
+            .insert(this.table)
+            .values({
+            id: data.id,
+            type: data.type ?? 'fact',
+            content: (data.content || '').trim().substring(0, 500),
+            source: data.source ?? 'bootstrap',
+            importance: Math.max(1, Math.min(10, data.importance ?? 5)),
+            accessCount: 0,
+            lastAccessedAt: now,
+            createdAt: now,
+            updatedAt: now,
+            expiresAt: data.expiresAt ?? null,
+            relatedEntities: JSON.stringify(data.relatedEntities ?? []),
+            relatedMemories: JSON.stringify([]),
+            sourceDimension: data.sourceDimension ?? null,
+            sourceEvidence: data.sourceEvidence ?? null,
+            bootstrapSession: data.bootstrapSession ?? null,
+            tags: JSON.stringify(data.tags ?? []),
+        })
+            .run();
+        return (await this.findById(data.id));
+    }
+    async delete(id) {
+        const result = this.drizzle.delete(this.table).where(eq(this.table.id, id)).run();
+        return result.changes > 0;
+    }
+    /** 动态字段更新 */
+    async update(id, updates) {
+        const existing = await this.findById(id);
+        if (!existing) {
+            return false;
+        }
+        const now = new Date().toISOString();
+        const setValues = { updatedAt: now };
+        if (updates.content !== undefined) {
+            setValues.content = updates.content.substring(0, 500);
+        }
+        if (updates.importance !== undefined) {
+            setValues.importance = Math.max(1, Math.min(10, updates.importance));
+        }
+        if (updates.accessCount !== undefined) {
+            setValues.accessCount = updates.accessCount;
+        }
+        if (updates.relatedEntities !== undefined) {
+            setValues.relatedEntities = JSON.stringify(updates.relatedEntities);
+        }
+        if (updates.relatedMemories !== undefined) {
+            setValues.relatedMemories = JSON.stringify(updates.relatedMemories);
+        }
+        if (updates.tags !== undefined) {
+            setValues.tags = JSON.stringify(updates.tags);
+        }
+        this.drizzle.update(this.table).set(setValues).where(eq(this.table.id, id)).run();
+        return true;
+    }
+    /* ─── 访问计数 ─── */
+    /** 更新访问计数 */
+    async touchAccess(id) {
+        this.drizzle
+            .update(this.table)
+            .set({
+            accessCount: sql `${this.table.accessCount} + 1`,
+            lastAccessedAt: new Date().toISOString(),
+        })
+            .where(eq(this.table.id, id))
+            .run();
+    }
+    /* ─── 批量查询 ─── */
+    /** 获取所有活跃记忆 (未过期) */
+    async getAllActive(filters = {}) {
+        const now = new Date().toISOString();
+        const conditions = [or(isNull(this.table.expiresAt), sql `${this.table.expiresAt} > ${now}`)];
+        if (filters.source) {
+            conditions.push(eq(this.table.source, filters.source));
+        }
+        if (filters.type) {
+            conditions.push(eq(this.table.type, filters.type));
+        }
+        const rows = this.drizzle
+            .select()
+            .from(this.table)
+            .where(and(...conditions))
+            .orderBy(desc(this.table.updatedAt))
+            .all();
+        return rows.map((r) => this.#mapRow(r));
+    }
+    /** 获取候选记忆 (用于相似度搜索) */
+    async getCandidates(type, limit = 50) {
+        const now = new Date().toISOString();
+        const conditions = [or(isNull(this.table.expiresAt), sql `${this.table.expiresAt} > ${now}`)];
+        if (type) {
+            conditions.push(eq(this.table.type, type));
+        }
+        const rows = this.drizzle
+            .select()
+            .from(this.table)
+            .where(and(...conditions))
+            .orderBy(desc(this.table.updatedAt))
+            .limit(limit)
+            .all();
+        return rows.map((r) => this.#mapRow(r));
+    }
+    /** 记忆总数 */
+    async size(filters = {}) {
+        const condition = filters.source ? eq(this.table.source, filters.source) : undefined;
+        const [row] = this.drizzle.select({ cnt: count() }).from(this.table).where(condition).all();
+        return row?.cnt ?? 0;
+    }
+    /* ─── 维护 ─── */
+    /**
+     * 执行维护: 清理过期记忆 + 自然遗忘 + 重要度衰减
+     */
+    async compact() {
+        const stats = { expired: 0, forgotten: 0, archived: 0, remaining: 0 };
+        const now = new Date().toISOString();
+        const nowMs = Date.now();
+        this.transaction(() => {
+            // 清理过期
+            const expiredResult = this.drizzle
+                .delete(this.table)
+                .where(and(sql `${this.table.expiresAt} IS NOT NULL`, sql `${this.table.expiresAt} < ${now}`))
+                .run();
+            stats.expired = expiredResult.changes;
+            // 自然遗忘: 90 天未访问 + importance < 7
+            const forgetThreshold = new Date(nowMs - FORGET_DAYS * 86400_000).toISOString();
+            const forgottenResult = this.drizzle
+                .delete(this.table)
+                .where(and(sql `${this.table.lastAccessedAt} < ${forgetThreshold}`, sql `${this.table.importance} < 7`))
+                .run();
+            stats.forgotten = forgottenResult.changes;
+            // 30 天未访问 + importance < 3 → 衰减
+            const archiveThreshold = new Date(nowMs - ARCHIVE_DAYS * 86400_000).toISOString();
+            const archiveResult = this.drizzle
+                .update(this.table)
+                .set({
+                importance: sql `MAX(1, ${this.table.importance} - 1)`,
+            })
+                .where(and(sql `${this.table.lastAccessedAt} < ${archiveThreshold}`, sql `${this.table.importance} < 3`))
+                .run();
+            stats.archived = archiveResult.changes;
+            // 剩余数量
+            const [row] = this.drizzle.select({ cnt: count() }).from(this.table).all();
+            stats.remaining = row?.cnt ?? 0;
+        });
+        return stats;
+    }
+    /** 容量控制 */
+    async enforceCapacity(maxMemories = MAX_MEMORIES) {
+        const currentSize = await this.size();
+        if (currentSize <= maxMemories) {
+            return 0;
+        }
+        const excess = currentSize - maxMemories;
+        const result = this.drizzle
+            .delete(this.table)
+            .where(sql `${this.table.id} IN (
+          SELECT ${this.table.id} FROM ${this.table}
+          ORDER BY ${this.table.importance} ASC,
+                   ${this.table.accessCount} ASC,
+                   ${this.table.updatedAt} ASC
+          LIMIT ${excess}
+        )`)
+            .run();
+        return result.changes;
+    }
+    /* ─── 统计 ─── */
+    async getStats() {
+        const [totalRow] = this.drizzle.select({ cnt: count() }).from(this.table).all();
+        const total = totalRow?.cnt ?? 0;
+        const byTypeRows = this.drizzle
+            .select({
+            type: this.table.type,
+            cnt: count(),
+        })
+            .from(this.table)
+            .groupBy(this.table.type)
+            .all();
+        const bySourceRows = this.drizzle
+            .select({
+            source: this.table.source,
+            cnt: count(),
+        })
+            .from(this.table)
+            .groupBy(this.table.source)
+            .all();
+        const [avgRow] = this.drizzle
+            .select({ avg: avg(this.table.importance) })
+            .from(this.table)
+            .all();
+        const avgImportance = avgRow?.avg ? Math.round(Number(avgRow.avg) * 10) / 10 : 0;
+        return {
+            total,
+            byType: Object.fromEntries(byTypeRows.map((r) => [r.type, r.cnt])),
+            bySource: Object.fromEntries(bySourceRows.map((r) => [r.source, r.cnt])),
+            avgImportance,
+        };
+    }
+    /** 清除所有 bootstrap 来源的记忆 */
+    async clearBootstrapMemories() {
+        const result = this.drizzle.delete(this.table).where(eq(this.table.source, 'bootstrap')).run();
+        return result.changes;
+    }
+    /* ─── 内部辅助 ─── */
+    #mapRow(row) {
+        return {
+            id: row.id,
+            type: row.type,
+            content: row.content,
+            source: row.source,
+            importance: row.importance,
+            accessCount: row.accessCount,
+            lastAccessedAt: row.lastAccessedAt ?? null,
+            createdAt: row.createdAt,
+            updatedAt: row.updatedAt,
+            expiresAt: row.expiresAt ?? null,
+            relatedEntities: safeParseJSON(row.relatedEntities, []),
+            relatedMemories: safeParseJSON(row.relatedMemories, []),
+            sourceDimension: row.sourceDimension ?? null,
+            sourceEvidence: row.sourceEvidence ?? null,
+            bootstrapSession: row.bootstrapSession ?? null,
+            tags: safeParseJSON(row.tags, []),
+        };
+    }
+}
+/* ═══ 辅助函数 ═══ */
+function safeParseJSON(str, fallback) {
+    try {
+        return str ? JSON.parse(str) : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}

package/dist/lib/repository/search/SearchRepoAdapter.d.ts

@@ -0,0 +1,92 @@
+/**
+ * SearchRepoAdapter — SearchEngine 用的轻量级仓储适配器
+ *
+ * 当完整的 KnowledgeRepositoryImpl / RecipeSourceRefRepositoryImpl 不可用时
+ * （例如单元测试中只传入 raw db），SearchEngine 自动使用这些适配器。
+ * 放在 lib/repository/ 下，允许使用 raw SQL（lint 白名单目录）。
+ */
+import type { SearchDb } from '../../service/search/SearchTypes.js';
+/** 解包 DatabaseConnection → raw SearchDb（若已是 raw db 则直接返回） */
+export declare function unwrapSearchDb(db: SearchDb & {
+    getDb?: () => SearchDb;
+}): SearchDb;
+/**
+ * 通用 db 解包：接受 raw db 或 { getDb() } wrapper，返回 raw db。
+ * 可用于 SearchDb、DatabaseLike 等不同 db 类型的构造函数。
+ */
+export declare function unwrapRawDb<T>(db: T | (T & {
+    getDb(): T;
+})): T;
+/** SearchEngine 需要的 KnowledgeRepo 最小接口 */
+export interface SearchKnowledgeRepo {
+    findNonDeprecatedSync(): Record<string, unknown>[];
+    keywordSearchSync(pattern: string, limit: number): Record<string, unknown>[];
+    findByIdsDetailSync(ids: string[]): Record<string, unknown>[];
+    findUpdatedSinceSync(sinceIso: string): Record<string, unknown>[];
+}
+/** SearchEngine 需要的 SourceRefRepo 最小接口 */
+export interface SearchSourceRefRepo {
+    findActiveByRecipeIds(ids: string[]): Array<{
+        recipeId: string;
+        sourcePath: string;
+        status: string;
+        newPath: string | null;
+    }>;
+}
+/**
+ * Raw-db 适配器：实现 SearchKnowledgeRepo 接口
+ * 仅在 KnowledgeRepositoryImpl 不可用时降级使用。
+ */
+export declare class RawDbKnowledgeAdapter implements SearchKnowledgeRepo {
+    #private;
+    constructor(db: SearchDb);
+    findNonDeprecatedSync(): import("../../service/search/SearchTypes.js").DbRow[];
+    keywordSearchSync(pattern: string, limit: number): import("../../service/search/SearchTypes.js").DbRow[];
+    findByIdsDetailSync(ids: string[]): import("../../service/search/SearchTypes.js").DbRow[];
+    findUpdatedSinceSync(sinceIso: string): import("../../service/search/SearchTypes.js").DbRow[];
+}
+/**
+ * Raw-db 适配器：实现 SearchSourceRefRepo 接口
+ * 仅在 RecipeSourceRefRepositoryImpl 不可用时降级使用。
+ */
+export declare class RawDbSourceRefAdapter implements SearchSourceRefRepo {
+    #private;
+    constructor(db: SearchDb);
+    findActiveByRecipeIds(ids: string[]): {
+        recipeId: string;
+        sourcePath: string;
+        status: string;
+        newPath: string | null;
+    }[];
+}
+/** GuardCheckEngine 需要的 KnowledgeRepo 最小接口 */
+export interface GuardKnowledgeRepo {
+    findGuardRulesSync(lifecycles: readonly string[]): Record<string, unknown>[];
+    incrementGuardHitsSync(id: string, hits: number): void;
+}
+/**
+ * Raw-db 适配器：实现 GuardKnowledgeRepo 接口
+ * 仅在 KnowledgeRepositoryImpl 不可用时降级使用。
+ */
+export declare class RawDbGuardAdapter implements GuardKnowledgeRepo {
+    #private;
+    constructor(db: {
+        prepare(sql: string): {
+            all(...args: unknown[]): Record<string, unknown>[];
+            run(...args: unknown[]): unknown;
+        };
+    });
+    findGuardRulesSync(lifecycles: readonly string[]): Record<string, unknown>[];
+    incrementGuardHitsSync(id: string, hits: number): void;
+}
+/** 从 raw db 查询非 deprecated 的基本条目信息（SyncCoordinator 对账用） */
+export declare function queryNonDeprecatedEntries(db: {
+    prepare(sql: string): {
+        all(): Array<Record<string, unknown>>;
+    };
+}): Array<{
+    id: string;
+    title?: string;
+    content?: string;
+    kind?: string;
+}>;