@soleri/core 9.0.4 → 9.3.0

package/src/vault/vault-branching.test.ts

@@ -0,0 +1,252 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { VaultBranching } from './vault-branching.js';
+import type { PersistenceProvider, RunResult } from '../persistence/types.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+
+// ─── In-memory mock persistence ──────────────────────────────────────
+
+function makeEntry(id: string): IntelligenceEntry {
+  return {
+    id,
+    type: 'pattern',
+    domain: 'test',
+    title: `Entry ${id}`,
+    severity: 'suggestion',
+    description: `Description for ${id}`,
+    tags: ['test'],
+  };
+}
+
+class BranchingMockDB implements PersistenceProvider {
+  readonly backend = 'sqlite' as const;
+  private meta: Array<{ name: string; created_at: number; merged_at: number | null }> = [];
+  private ops: Array<{
+    id: number;
+    branch_name: string;
+    entry_id: string;
+    action: string;
+    entry_data: string | null;
+    created_at: number;
+  }> = [];
+  private nextId = 1;
+
+  execSql(): void {}
+
+  run(sql: string, params?: Record<string, unknown> | unknown[]): RunResult {
+    const p = this.norm(params);
+
+    if (sql.includes('INSERT INTO vault_branch_meta')) {
+      this.meta.push({ name: p.name as string, created_at: Date.now(), merged_at: null });
+      return { changes: 1, lastInsertRowid: this.meta.length };
+    }
+    if (sql.includes('INSERT INTO vault_branch_ops')) {
+      this.ops.push({
+        id: this.nextId++,
+        branch_name: p.branchName as string,
+        entry_id: p.entryId as string,
+        action: p.action as string,
+        entry_data: (p.entryData as string) ?? null,
+        created_at: Date.now(),
+      });
+      return { changes: 1, lastInsertRowid: this.nextId - 1 };
+    }
+    if (sql.includes('UPDATE vault_branch_meta SET merged_at')) {
+      const m = this.meta.find((r) => r.name === p.branchName);
+      if (m) m.merged_at = Date.now();
+      return { changes: 1, lastInsertRowid: 0 };
+    }
+    if (sql.includes('DELETE FROM vault_branch_ops')) {
+      const name = (p.branchName ?? p.name) as string;
+      const before = this.ops.length;
+      this.ops = this.ops.filter((o) => o.branch_name !== name);
+      return { changes: before - this.ops.length, lastInsertRowid: 0 };
+    }
+    if (sql.includes('DELETE FROM vault_branch_meta')) {
+      const name = (p.branchName ?? p.name) as string;
+      const before = this.meta.length;
+      this.meta = this.meta.filter((m) => m.name !== name);
+      return { changes: before - this.meta.length, lastInsertRowid: 0 };
+    }
+    return { changes: 0, lastInsertRowid: 0 };
+  }
+
+  get<T>(sql: string, params?: Record<string, unknown> | unknown[]): T | undefined {
+    const p = this.norm(params);
+    const name = (p.name ?? p.branchName) as string;
+    if (sql.includes('vault_branch_meta')) {
+      const m = this.meta.find((r) => r.name === name);
+      return m as T | undefined;
+    }
+    return undefined;
+  }
+
+  all<T>(sql: string, params?: Record<string, unknown> | unknown[]): T[] {
+    const p = this.norm(params);
+    if (sql.includes('vault_branch_ops') && p.branchName) {
+      return this.ops.filter((o) => o.branch_name === p.branchName) as T[];
+    }
+    if (sql.includes('vault_branch_meta')) {
+      return this.meta.map((m) => ({
+        ...m,
+        entry_count: this.ops.filter((o) => o.branch_name === m.name).length,
+      })) as T[];
+    }
+    return [];
+  }
+
+  transaction<T>(fn: () => T): T {
+    return fn();
+  }
+
+  ftsSearch<T>(): T[] {
+    return [];
+  }
+  ftsRebuild(): void {}
+  close(): void {}
+
+  private norm(params?: Record<string, unknown> | unknown[]): Record<string, unknown> {
+    if (!params || Array.isArray(params)) return {};
+    return params;
+  }
+}
+
+// ─── Mock Vault facade ───────────────────────────────────────────────
+
+function makeMockVault(provider: BranchingMockDB) {
+  return {
+    getProvider: () => provider,
+    add: vi.fn(),
+    remove: vi.fn(),
+  } as unknown;
+}
+
+describe('VaultBranching', () => {
+  let db: BranchingMockDB;
+  let branching: VaultBranching;
+
+  beforeEach(() => {
+    db = new BranchingMockDB();
+    branching = new VaultBranching(makeMockVault(db));
+  });
+
+  // ── branch ──────────────────────────────────────────────────────────
+
+  it('creates a new branch', () => {
+    expect(branching.branch('feature-x')).toBe(true);
+  });
+
+  it('throws when creating duplicate active branch', () => {
+    branching.branch('feature-x');
+    expect(() => branching.branch('feature-x')).toThrow('already exists');
+  });
+
+  // ── addOperation ────────────────────────────────────────────────────
+
+  it('adds an add operation with entry data', () => {
+    branching.branch('b1');
+    branching.addOperation('b1', 'e1', 'add', makeEntry('e1'));
+    const ops = branching.listEntries('b1');
+    expect(ops).toHaveLength(1);
+    expect(ops[0].action).toBe('add');
+    expect(ops[0].entryId).toBe('e1');
+  });
+
+  it('adds a remove operation without entry data', () => {
+    branching.branch('b1');
+    branching.addOperation('b1', 'e1', 'remove');
+    const ops = branching.listEntries('b1');
+    expect(ops).toHaveLength(1);
+    expect(ops[0].action).toBe('remove');
+  });
+
+  it('throws when adding to non-existent branch', () => {
+    expect(() => branching.addOperation('missing', 'e1', 'add', makeEntry('e1'))).toThrow(
+      'does not exist',
+    );
+  });
+
+  it('throws when add/modify has no entry data', () => {
+    branching.branch('b1');
+    expect(() => branching.addOperation('b1', 'e1', 'add')).toThrow('Entry data required');
+    expect(() => branching.addOperation('b1', 'e1', 'modify')).toThrow('Entry data required');
+  });
+
+  // ── listEntries ─────────────────────────────────────────────────────
+
+  it('returns empty list for branch with no ops', () => {
+    branching.branch('b1');
+    expect(branching.listEntries('b1')).toEqual([]);
+  });
+
+  // ── listBranches ────────────────────────────────────────────────────
+
+  it('lists all branches with summary info', () => {
+    branching.branch('b1');
+    branching.branch('b2');
+    branching.addOperation('b1', 'e1', 'add', makeEntry('e1'));
+    const branches = branching.listBranches();
+    expect(branches).toHaveLength(2);
+    const b1 = branches.find((b) => b.name === 'b1');
+    expect(b1!.entryCount).toBe(1);
+    expect(b1!.merged).toBe(false);
+  });
+
+  // ── merge ───────────────────────────────────────────────────────────
+
+  it('merges a branch applying add operations', () => {
+    const mockVault = makeMockVault(db);
+    branching = new VaultBranching(mockVault);
+    branching.branch('b1');
+    branching.addOperation('b1', 'e1', 'add', makeEntry('e1'));
+    const result = branching.merge('b1');
+    expect(result.merged).toBe(true);
+    expect(result.added).toBe(1);
+    expect(result.total).toBe(1);
+    expect(mockVault.add).toHaveBeenCalled();
+  });
+
+  it('merges with remove operations', () => {
+    const mockVault = makeMockVault(db);
+    branching = new VaultBranching(mockVault);
+    branching.branch('b1');
+    branching.addOperation('b1', 'e1', 'remove');
+    const result = branching.merge('b1');
+    expect(result.removed).toBe(1);
+    expect(mockVault.remove).toHaveBeenCalledWith('e1');
+  });
+
+  it('collapses multiple ops for same entry (last wins)', () => {
+    const mockVault = makeMockVault(db);
+    branching = new VaultBranching(mockVault);
+    branching.branch('b1');
+    branching.addOperation('b1', 'e1', 'add', makeEntry('e1'));
+    branching.addOperation('b1', 'e1', 'remove');
+    const result = branching.merge('b1');
+    // Last op is remove, so add shouldn't happen on this entry
+    expect(result.removed).toBe(1);
+    expect(result.added).toBe(0);
+  });
+
+  it('throws when merging non-existent branch', () => {
+    expect(() => branching.merge('missing')).toThrow('does not exist');
+  });
+
+  it('throws when merging already-merged branch', () => {
+    branching.branch('b1');
+    branching.merge('b1');
+    expect(() => branching.merge('b1')).toThrow('already merged');
+  });
+
+  // ── deleteBranch ────────────────────────────────────────────────────
+
+  it('deletes an existing branch', () => {
+    branching.branch('b1');
+    branching.addOperation('b1', 'e1', 'add', makeEntry('e1'));
+    expect(branching.deleteBranch('b1')).toBe(true);
+    expect(branching.listBranches()).toHaveLength(0);
+  });
+
+  it('returns false when deleting non-existent branch', () => {
+    expect(branching.deleteBranch('nonexistent')).toBe(false);
+  });
+});

package/src/{__tests__ → vault}/vault-connect.test.ts

@@ -3,7 +3,7 @@
  */
 
 import { describe, test, expect, afterEach } from 'vitest';
-import { VaultManager } from '../vault/vault-manager.js';
+import { VaultManager } from './vault-manager.js';
 import type { IntelligenceEntry } from '../intelligence/types.js';
 
 function makeEntry(id: string, title: string, domain = 'general'): IntelligenceEntry {

package/src/vault/vault-entries.ts

@@ -0,0 +1,426 @@
+/**
+ * Vault entry CRUD operations — search, seed, get, update, delete, tags, etc.
+ * Extracted from vault.ts as part of Wave 0C decomposition.
+ */
+import type { PersistenceProvider } from '../persistence/types.js';
+import type { IntelligenceEntry } from '../intelligence/types.js';
+import type { LinkManager } from './linking.js';
+import { computeContentHash } from './content-hash.js';
+import type { SearchResult, VaultStats } from './vault.js';
+
+export interface AutoLinkConfig {
+  linkManager: LinkManager | null;
+  enabled: boolean;
+  maxLinks: number;
+}
+
+/** Updatable fields on an entry. */
+export type EntryUpdateFields = Partial<
+  Pick<
+    IntelligenceEntry,
+    | 'title'
+    | 'description'
+    | 'context'
+    | 'example'
+    | 'counterExample'
+    | 'why'
+    | 'tags'
+    | 'appliesTo'
+    | 'severity'
+    | 'type'
+    | 'domain'
+    | 'validFrom'
+    | 'validUntil'
+  >
+>;
+
+/** Search/list filter options. */
+export interface EntryFilterOptions {
+  domain?: string;
+  type?: string;
+  severity?: string;
+  origin?: 'agent' | 'pack' | 'user';
+  limit?: number;
+  includeExpired?: boolean;
+}
+
+export function autoLink(entryId: string, config: AutoLinkConfig): void {
+  if (!config.linkManager || !config.enabled) return;
+  try {
+    const suggestions = config.linkManager.suggestLinks(entryId, config.maxLinks);
+    for (const s of suggestions) {
+      config.linkManager.addLink(entryId, s.entryId, s.suggestedType, `auto: ${s.reason}`);
+    }
+  } catch {
+    /* best-effort */
+  }
+}
+
+export function seed(
+  provider: PersistenceProvider,
+  entries: IntelligenceEntry[],
+  alc: AutoLinkConfig,
+): number {
+  const sql = `
+    INSERT INTO entries (id,type,domain,title,severity,description,context,example,counter_example,why,tags,applies_to,valid_from,valid_until,content_hash,tier,origin)
+    VALUES (@id,@type,@domain,@title,@severity,@description,@context,@example,@counterExample,@why,@tags,@appliesTo,@validFrom,@validUntil,@contentHash,@tier,@origin)
+    ON CONFLICT(id) DO UPDATE SET type=excluded.type,domain=excluded.domain,title=excluded.title,severity=excluded.severity,
+      description=excluded.description,context=excluded.context,example=excluded.example,counter_example=excluded.counter_example,
+      why=excluded.why,tags=excluded.tags,applies_to=excluded.applies_to,valid_from=excluded.valid_from,valid_until=excluded.valid_until,
+      content_hash=excluded.content_hash,tier=excluded.tier,origin=excluded.origin,updated_at=unixepoch()
+  `;
+  return provider.transaction(() => {
+    let count = 0;
+    for (const entry of entries) {
+      provider.run(sql, {
+        id: entry.id,
+        type: entry.type,
+        domain: entry.domain,
+        title: entry.title,
+        severity: entry.severity,
+        description: entry.description,
+        context: entry.context ?? null,
+        example: entry.example ?? null,
+        counterExample: entry.counterExample ?? null,
+        why: entry.why ?? null,
+        tags: JSON.stringify(entry.tags),
+        appliesTo: JSON.stringify(entry.appliesTo ?? []),
+        validFrom: entry.validFrom ?? null,
+        validUntil: entry.validUntil ?? null,
+        contentHash: computeContentHash(entry),
+        tier: entry.tier ?? 'agent',
+        origin: entry.origin ?? 'agent',
+      });
+      count++;
+    }
+    // Auto-link after insert; skip large batches (>100) — use relink_vault for bulk imports.
+    if (entries.length <= 100) {
+      for (const entry of entries) autoLink(entry.id, alc);
+    }
+    return count;
+  });
+}
+
+export function seedDedup(
+  provider: PersistenceProvider,
+  entries: IntelligenceEntry[],
+  alc: AutoLinkConfig,
+): Array<{ id: string; action: 'inserted' | 'duplicate'; existingId?: string }> {
+  return provider.transaction(() => {
+    const results: Array<{ id: string; action: 'inserted' | 'duplicate'; existingId?: string }> =
+      [];
+    for (const entry of entries) {
+      const hash = computeContentHash(entry);
+      const existing = findByContentHash(provider, hash);
+      if (existing && existing !== entry.id) {
+        results.push({ id: entry.id, action: 'duplicate', existingId: existing });
+      } else {
+        seed(provider, [entry], alc);
+        results.push({ id: entry.id, action: 'inserted' });
+      }
+    }
+    return results;
+  });
+}
+
+export function installPack(
+  provider: PersistenceProvider,
+  entries: IntelligenceEntry[],
+  alc: AutoLinkConfig,
+): { installed: number; skipped: number } {
+  let installed = 0,
+    skipped = 0;
+  const tagged = entries.map((e) => ({ ...e, origin: 'pack' as const }));
+  for (const r of seedDedup(provider, tagged, alc)) {
+    if (r.action === 'inserted') installed++;
+    else skipped++;
+  }
+  return { installed, skipped };
+}
+
+export function search(
+  provider: PersistenceProvider,
+  query: string,
+  options?: EntryFilterOptions,
+): SearchResult[] {
+  const limit = options?.limit ?? 10;
+  const filters: string[] = [];
+  const fp: Record<string, unknown> = {};
+  if (options?.domain) {
+    filters.push('e.domain = @domain');
+    fp.domain = options.domain;
+  }
+  if (options?.type) {
+    filters.push('e.type = @type');
+    fp.type = options.type;
+  }
+  if (options?.severity) {
+    filters.push('e.severity = @severity');
+    fp.severity = options.severity;
+  }
+  if (options?.origin) {
+    filters.push('e.origin = @origin');
+    fp.origin = options.origin;
+  }
+  if (!options?.includeExpired) {
+    const now = Math.floor(Date.now() / 1000);
+    filters.push('(e.valid_until IS NULL OR e.valid_until > @now)');
+    filters.push('(e.valid_from IS NULL OR e.valid_from <= @now)');
+    fp.now = now;
+  }
+  const wc = filters.length > 0 ? `AND ${filters.join(' AND ')}` : '';
+  const ftsQuery = buildFtsQuery(query);
+  try {
+    const rows = provider.all<Record<string, unknown>>(
+      `SELECT e.*, bm25(entries_fts, 5.0, 10.0, 3.0, 1.0, 2.0) as score FROM entries_fts fts JOIN entries e ON e.rowid = fts.rowid WHERE entries_fts MATCH @query ${wc} ORDER BY score ASC LIMIT @limit`,
+      { query: ftsQuery, limit, ...fp },
+    );
+    return rows.map(rowToSearchResult);
+  } catch {
+    try {
+      const rows = provider.all<Record<string, unknown>>(
+        `SELECT e.*, -rank as score FROM entries_fts fts JOIN entries e ON e.rowid = fts.rowid WHERE entries_fts MATCH @query ${wc} ORDER BY score DESC LIMIT @limit`,
+        { query, limit, ...fp },
+      );
+      return rows.map(rowToSearchResult);
+    } catch {
+      return [];
+    }
+  }
+}
+
+export function get(provider: PersistenceProvider, id: string): IntelligenceEntry | null {
+  const row = provider.get<Record<string, unknown>>('SELECT * FROM entries WHERE id = ?', [id]);
+  return row ? rowToEntry(row) : null;
+}
+
+export function list(
+  provider: PersistenceProvider,
+  options?: EntryFilterOptions & { tags?: string[]; offset?: number },
+): IntelligenceEntry[] {
+  const filters: string[] = [];
+  const params: Record<string, unknown> = {};
+  if (options?.domain) {
+    filters.push('domain = @domain');
+    params.domain = options.domain;
+  }
+  if (options?.type) {
+    filters.push('type = @type');
+    params.type = options.type;
+  }
+  if (options?.severity) {
+    filters.push('severity = @severity');
+    params.severity = options.severity;
+  }
+  if (options?.origin) {
+    filters.push('origin = @origin');
+    params.origin = options.origin;
+  }
+  if (options?.tags?.length) {
+    const c = options.tags.map((t, i) => {
+      params[`tag${i}`] = `%"${t}"%`;
+      return `tags LIKE @tag${i}`;
+    });
+    filters.push(`(${c.join(' OR ')})`);
+  }
+  if (!options?.includeExpired) {
+    const now = Math.floor(Date.now() / 1000);
+    filters.push('(valid_until IS NULL OR valid_until > @now)');
+    filters.push('(valid_from IS NULL OR valid_from <= @now)');
+    params.now = now;
+  }
+  const wc = filters.length > 0 ? `WHERE ${filters.join(' AND ')}` : '';
+  const rows = provider.all<Record<string, unknown>>(
+    `SELECT * FROM entries ${wc} ORDER BY severity, domain, title LIMIT @limit OFFSET @offset`,
+    { ...params, limit: options?.limit ?? 50, offset: options?.offset ?? 0 },
+  );
+  return rows.map(rowToEntry);
+}
+
+export function stats(provider: PersistenceProvider): VaultStats {
+  const total = provider.get<{ count: number }>('SELECT COUNT(*) as count FROM entries')!.count;
+  return {
+    totalEntries: total,
+    byType: gc(provider, 'type'),
+    byDomain: gc(provider, 'domain'),
+    bySeverity: gc(provider, 'severity'),
+  };
+}
+
+export function add(
+  provider: PersistenceProvider,
+  entry: IntelligenceEntry,
+  alc: AutoLinkConfig,
+): void {
+  seed(provider, [entry], alc);
+}
+
+export function remove(provider: PersistenceProvider, id: string): boolean {
+  return provider.run('DELETE FROM entries WHERE id = ?', [id]).changes > 0;
+}
+
+export function update(
+  provider: PersistenceProvider,
+  id: string,
+  fields: EntryUpdateFields,
+  alc: AutoLinkConfig,
+): IntelligenceEntry | null {
+  const existing = get(provider, id);
+  if (!existing) return null;
+  seed(provider, [{ ...existing, ...fields }], alc);
+  return get(provider, id);
+}
+
+export function setTemporal(
+  provider: PersistenceProvider,
+  id: string,
+  validFrom?: number,
+  validUntil?: number,
+): boolean {
+  const sets: string[] = [];
+  const params: Record<string, unknown> = { id };
+  if (validFrom !== undefined) {
+    sets.push('valid_from = @validFrom');
+    params.validFrom = validFrom;
+  }
+  if (validUntil !== undefined) {
+    sets.push('valid_until = @validUntil');
+    params.validUntil = validUntil;
+  }
+  if (sets.length === 0) return false;
+  sets.push('updated_at = unixepoch()');
+  return provider.run(`UPDATE entries SET ${sets.join(', ')} WHERE id = @id`, params).changes > 0;
+}
+
+export function findExpiring(
+  provider: PersistenceProvider,
+  withinDays: number,
+): IntelligenceEntry[] {
+  const now = Math.floor(Date.now() / 1000);
+  const cutoff = now + withinDays * 86400;
+  return provider
+    .all<Record<string, unknown>>(
+      'SELECT * FROM entries WHERE valid_until IS NOT NULL AND valid_until > @now AND valid_until <= @cutoff ORDER BY valid_until ASC',
+      { now, cutoff },
+    )
+    .map(rowToEntry);
+}
+
+export function findExpired(
+  provider: PersistenceProvider,
+  limit: number = 50,
+): IntelligenceEntry[] {
+  const now = Math.floor(Date.now() / 1000);
+  return provider
+    .all<Record<string, unknown>>(
+      'SELECT * FROM entries WHERE valid_until IS NOT NULL AND valid_until <= @now ORDER BY valid_until DESC LIMIT @limit',
+      { now, limit },
+    )
+    .map(rowToEntry);
+}
+
+export function bulkRemove(provider: PersistenceProvider, ids: string[]): number {
+  return provider.transaction(() => {
+    let count = 0;
+    for (const id of ids) count += provider.run('DELETE FROM entries WHERE id = ?', [id]).changes;
+    return count;
+  });
+}
+
+export function getTags(provider: PersistenceProvider): Array<{ tag: string; count: number }> {
+  const rows = provider.all<{ tags: string }>('SELECT tags FROM entries');
+  const counts = new Map<string, number>();
+  for (const row of rows) {
+    for (const tag of JSON.parse(row.tags || '[]') as string[]) {
+      counts.set(tag, (counts.get(tag) ?? 0) + 1);
+    }
+  }
+  return Array.from(counts.entries())
+    .map(([tag, count]) => ({ tag, count }))
+    .sort((a, b) => b.count - a.count);
+}
+
+export function getDomains(
+  provider: PersistenceProvider,
+): Array<{ domain: string; count: number }> {
+  return provider.all(
+    'SELECT domain, COUNT(*) as count FROM entries GROUP BY domain ORDER BY count DESC',
+  );
+}
+
+export function getRecent(provider: PersistenceProvider, limit: number = 20): IntelligenceEntry[] {
+  return provider
+    .all<Record<string, unknown>>('SELECT * FROM entries ORDER BY updated_at DESC LIMIT ?', [limit])
+    .map(rowToEntry);
+}
+
+export function findByContentHash(provider: PersistenceProvider, hash: string): string | null {
+  return (
+    provider.get<{ id: string }>('SELECT id FROM entries WHERE content_hash = @hash', { hash })
+      ?.id ?? null
+  );
+}
+
+export function contentHashStats(provider: PersistenceProvider): {
+  total: number;
+  hashed: number;
+  uniqueHashes: number;
+} {
+  const total = provider.get<{ c: number }>('SELECT COUNT(*) as c FROM entries')?.c ?? 0;
+  const hashed =
+    provider.get<{ c: number }>('SELECT COUNT(*) as c FROM entries WHERE content_hash IS NOT NULL')
+      ?.c ?? 0;
+  const uniqueHashes =
+    provider.get<{ c: number }>(
+      'SELECT COUNT(DISTINCT content_hash) as c FROM entries WHERE content_hash IS NOT NULL',
+    )?.c ?? 0;
+  return { total, hashed, uniqueHashes };
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────────
+
+function gc(provider: PersistenceProvider, col: string): Record<string, number> {
+  const rows = provider.all<{ key: string; count: number }>(
+    `SELECT ${col} as key, COUNT(*) as count FROM entries GROUP BY ${col}`,
+  );
+  return Object.fromEntries(rows.map((r) => [r.key, r.count]));
+}
+
+export function rowToEntry(row: Record<string, unknown>): IntelligenceEntry {
+  return {
+    id: row.id as string,
+    type: row.type as IntelligenceEntry['type'],
+    domain: row.domain as IntelligenceEntry['domain'],
+    title: row.title as string,
+    severity: row.severity as IntelligenceEntry['severity'],
+    description: row.description as string,
+    context: (row.context as string) ?? undefined,
+    example: (row.example as string) ?? undefined,
+    counterExample: (row.counter_example as string) ?? undefined,
+    why: (row.why as string) ?? undefined,
+    tags: JSON.parse((row.tags as string) || '[]'),
+    appliesTo: JSON.parse((row.applies_to as string) || '[]'),
+    tier: (row.tier as IntelligenceEntry['tier']) ?? undefined,
+    origin: (row.origin as IntelligenceEntry['origin']) ?? undefined,
+    validFrom: (row.valid_from as number) ?? undefined,
+    validUntil: (row.valid_until as number) ?? undefined,
+  };
+}
+
+export function rowToSearchResult(row: Record<string, unknown>): SearchResult {
+  const rawScore = row.score as number;
+  return { entry: rowToEntry(row), score: rawScore < 0 ? -rawScore : rawScore };
+}
+
+/** Build FTS5 query from natural language: terms joined with OR for broad matching. */
+export function buildFtsQuery(query: string): string {
+  const terms = query
+    .toLowerCase()
+    .split(/\s+/)
+    .filter((t) => t.length >= 2)
+    .map((t) => t.replace(/[^a-z0-9]/g, ''))
+    .filter(Boolean);
+  if (terms.length === 0) return query;
+  if (terms.length === 1) return terms[0];
+  return terms.join(' OR ');
+}