Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

163 KB
Raw Blame
/**
 * Memory Bridge — Routes CLI memory operations through ControllerRegistry + AgentDB v3
 *
 * Per ADR-053 Phases 1-6: Full controller activation pipeline.
 * CLI → ControllerRegistry → AgentDB v3 controllers.
 *
 * Phase 1: Core CRUD + embeddings + HNSW + controller access (complete)
 * Phase 2: BM25 hybrid search, TieredCache read/write, MutationGuard validation
 * Phase 3: ReasoningBank pattern store, recordFeedback, CausalMemoryGraph edges
 * Phase 4: SkillLibrary promotion, ExplainableRecall provenance, AttestationLog
 * Phase 5: ReflexionMemory session lifecycle, WitnessChain attestation
 * Phase 6: AgentDB MCP tools (separate file), COW branching
 *
 * Uses better-sqlite3 API (synchronous .all()/.get()/.run()) since that's
 * what AgentDB v3 uses internally.
 *
 * @module v3/cli/memory-bridge
 */
import { AppendConditionFailed, assertAppendConditions, validateAppendConditions, type AppendCondition } from './append-conditions.js';

import { liveMemoryRowSql } from './live-memory-row.js';
import { resolveAgentdbBetterSqlite3 } from './shared-sqlite.js';
import { DEFAULT_SEARCH_THRESHOLD } from './search-defaults.js';
import { encodeEmbeddingQ8, MAX_LIST_EMBEDDINGS } from './embedding-q8.js';
import * as path from 'path';
import * as crypto from 'crypto';
import { mkdirSync, realpathSync } from 'node:fs';
import { createRequire } from 'node:module';
import { AsyncLocalStorage } from 'node:async_hooks';
import { validateFeedbackPatterns } from './feedback-patterns.js';

// ===== Lazy registry cache, keyed by database path =====

/**
 * #3196: this cache is keyed by resolved database path, and that is the whole
 * point of it.
 *
 * It used to be a single global instance. The first caller to touch the bridge
 * decided which file the process would use, and every later caller's explicit
 * `dbPath` was accepted and then silently ignored — `getRegistry()` returned the
 * already-built instance without ever comparing paths. A `memory store --path A`
 * following an MCP write therefore read and wrote B, reported success, and left
 * two valid corpora that neither interface could see whole.
 *
 * Keying by path makes an explicit path mean what it says. Two paths in one
 * process are two registries, which is the behaviour the CLI's `--path` flag and
 * `CLAUDE_FLOW_DB_PATH` have always advertised.
 */
const registryPromises = new Map<string, Promise<any>>();
const registryInstances = new Map<string, any>();
// One lease spans an entire bridge operation, including its awaited controller
// effects and nested bridge calls. Initializer ownership alone is insufficient:
// a ReasoningBank write can still be pending after its registry has opened.
const operationContext = new AsyncLocalStorage<{ active: boolean }>();
let activeOperations = 0;
let drained: (() => void) | null = null;
let shutdownPromise: Promise<void> | null = null;

async function withBridgeOperation<T>(operation: () => Promise<T>): Promise<T> {
  if (operationContext.getStore()?.active) return operation();
  // New calls belong to the next lifecycle once retirement starts. A loop
  // also handles another shutdown requested before a queued call resumes.
  while (shutdownPromise) await shutdownPromise;
  const lease = { active: true };
  activeOperations++;
  try {
    return await operationContext.run(lease, operation);
  } finally {
    lease.active = false;
    if (--activeOperations === 0) {
      drained?.();
      drained = null;
    }
  }
}

/**
 * Test seam: when set, every path resolves to this registry.
 *
 * Kept separate from the path cache on purpose. A test installs a fake registry
 * and then calls a bridge function with its own temp `dbPath`; keying the
 * override by path would mean the seam only worked for callers that happened to
 * pass the same path the seam guessed, which is how #2968's fixture broke.
 */
let testRegistryOverride: any = null;
let testRegistryFactory: (() => any) | null = null;
// #2652/#2120: rows created before the status column existed receive NULL
// during migration. They are live rows, not tombstones. Every user-facing
// read/delete path must agree with list() about their visibility.
const ACTIVE_MEMORY_ROW_SQL = `(status = 'active' OR status IS NULL)`;
/**
 * A failed open must only affect its own database. A process can serve several
 * projects, and an error from one must not disable the native bridge for all.
 */
const bridgeFailureReasons = new Map<string, string>();

/** Resolve aliases even when the database file or some parent dirs do not exist yet. */
function canonicalDbPath(dbPath?: string): string {
  const resolved = dbPath === ':memory:' ? ':memory:' : path.resolve(dbPath ?? getAgentDbPath());
  if (resolved === ':memory:') return resolved;
  let ancestor = resolved;
  const suffix: string[] = [];
  for (;;) {
    try {
      return path.join(realpathSync(ancestor), ...suffix);
    } catch {
      const parent = path.dirname(ancestor);
      if (parent === ancestor) return resolved;
      suffix.unshift(path.basename(ancestor));
      ancestor = parent;
    }
  }
}

/**
 * #3024: AgentDB's optional native controller stack can abort the whole Node
 * process on Windows during registry initialization (a Rust allocation panic),
 * which cannot be caught by JavaScript. Keep the CLI/MCP server on the
 * sql.js + local-embedding path there until the native dependency is proven
 * safe. Advanced users and CI can opt back in explicitly for diagnosis.
 */
export function shouldDisableNativeBridge(
  platform: NodeJS.Platform = process.platform,
  env: NodeJS.ProcessEnv = process.env,
): boolean {
  if (env.CLAUDE_FLOW_DISABLE_BRIDGE === '1') return true;
  return platform === 'win32' && env.CLAUDE_FLOW_ENABLE_NATIVE_BRIDGE_ON_WINDOWS !== '1';
}

/**
 * ADR-323: reuse memory-initializer's provenance-type allowlist rather than
 * duplicating it (drift risk). Lazy CJS require for the same circular-ESM-
 * dependency reason as getDbPath() below.
 */
function isValidProvenanceType(value: unknown): boolean {
  try {
    const cjsRequire = createRequire(import.meta.url);
    const mod = cjsRequire('./memory-initializer.js') as { isValidProvenanceType?: (v: unknown) => boolean };
    if (typeof mod.isValidProvenanceType === 'function') {
      return mod.isValidProvenanceType(value);
    }
  } catch { /* memory-initializer not resolvable in this build */ }
  // Fallback allowlist — keep in sync with memory-initializer.ts's PROVENANCE_TYPES.
  return typeof value === 'string' && ['user_claim', 'agent_output', 'system_observation', 'tool_result', 'unknown'].includes(value);
}

/**
 * Resolve database path with path traversal protection.
 * Only allows paths within or below the project's working directory,
 * or the special ':memory:' path.
 *
 * #1945: the previous hard-coded `<cwd>/.swarm/memory.db` default ignored
 * `CLAUDE_FLOW_MEMORY_PATH` / `claude-flow.config.json#memory.persistPath`
 * — so users with non-default memory paths had `memory init` write to e.g.
 * `data/memory/memory.db` while `bridgeStoreEntry()` wrote to
 * `.swarm/memory.db`. CLI store reported success against the wrong file and
 * a fresh process reading the configured path saw nothing.
 *
 * Use `getMemoryRoot()` (from memory-initializer) so the bridge and the
 * initializer agree on the same file. Imported via require() to avoid a
 * circular ESM dep between memory-initializer.ts and memory-bridge.ts.
 */
function getDbPath(customPath?: string): string {
  let defaultDir = path.resolve(process.cwd(), '.swarm');
  try {
    // `getMemoryRoot()` honors $CLAUDE_FLOW_MEMORY_PATH, then the
    // claude-flow.config.json `memory.persistPath`, then defaults to `.swarm`.
    const cjsRequire = createRequire(import.meta.url);
    const mod = cjsRequire('./memory-initializer.js') as { getMemoryRoot?: () => string };
    if (typeof mod.getMemoryRoot === 'function') {
      defaultDir = mod.getMemoryRoot();
    }
  } catch {
    /* memory-initializer not resolvable in this build — keep `.swarm/` default */
  }
  if (!customPath) return path.join(defaultDir, 'memory.db');
  if (customPath === ':memory:') return ':memory:';
  const resolved = path.resolve(customPath);
  // Ensure the path doesn't escape the working directory.
  const cwd = process.cwd();
  if (!resolved.startsWith(cwd)) {
    return path.join(defaultDir, 'memory.db'); // fallback to safe default
  }
  return resolved;
}

/**
 * Resolve AgentDB's native better-sqlite3 database path (#2786).
 *
 * AgentDB is opened by ControllerRegistry via native better-sqlite3, which
 * requires a plaintext SQLite file. The sibling `memory.db` file written by
 * `memory-initializer.ts` (`writeFileRestricted(..., {encrypt: true})`) is
 * encrypted-at-rest when `CLAUDE_FLOW_ENCRYPT_AT_REST=1` — pointing native
 * better-sqlite3 at it fails with "file is not a database" and silently
 * disables `learningSystem`/`reasoningBank`.
 *
 * Give AgentDB a distinct filename in the same directory so both writers
 * coexist: sql.js keeps `memory.db` (possibly encrypted); AgentDB owns
 * `agentdb-memory.db`. Preserves the traversal protection in `getDbPath()`
 * because we derive from its already-validated return value.
 */
function getAgentDbPath(): string {
  const dbPath = getDbPath();
  if (dbPath === ':memory:') return ':memory:';
  return path.join(path.dirname(dbPath), 'agentdb-memory.db');
}

/**
 * Generate a secure random ID for memory entries.
 */
function generateId(prefix: string): string {
  return `${prefix}_${Date.now()}_${crypto.randomBytes(8).toString('hex')}`;
}

/** Noisy init banners that carry no operational signal. */
const INIT_LOG_NOISE = [
  'Transformers.js',
  'better-sqlite3',
  '[AgentDB]',
  '[HNSWLibBackend]',
  'RuVector graph',
];

/**
 * Should this init-time log line be swallowed?
 *
 * A DEGRADATION notice never is. AgentDB logs "[AgentDB] better-sqlite3 not
 * available, using sql.js WASM" when it falls back to WASM, and both the
 * '[AgentDB]' and 'better-sqlite3' entries above match it — so the one line
 * explaining why the native driver was not in use was being discarded as
 * noise. Suppress the banners, keep the bad news.
 */
export function shouldSuppressInitLog(msg: string): boolean {
  const degradation = msg.includes('not available')
    || msg.includes('falling back')
    || msg.includes('fallback');
  if (degradation) return false;
  return INIT_LOG_NOISE.some((needle) => msg.includes(needle));
}

/**
 * Lazily initialize the ControllerRegistry singleton.
 * Returns null if @claude-flow/memory is not available.
 */
async function getRegistry(dbPath?: string): Promise<any | null> {
  if (shouldDisableNativeBridge()) return null;
  if (testRegistryOverride) return testRegistryOverride;

  // Resolve before caching: relative, absolute and symlink paths to one file
  // must not open multiple native handles to the same database.
  const resolvedPath = canonicalDbPath(dbPath);

  const cached = registryInstances.get(resolvedPath);
  if (cached) return cached;

  let registryPromise = registryPromises.get(resolvedPath);
  if (!registryPromise) {
    registryPromise = (async () => {
      let registry: any;
      try {
        registry = testRegistryFactory
          ? testRegistryFactory()
          : new (await import('@claude-flow/memory')).ControllerRegistry();

        // Suppress noisy console.log during init — but never suppress a
        // DEGRADATION notice (see shouldSuppressInitLog).
        const origLog = console.log;
        console.log = (...args: unknown[]) => {
          const msg = String(args[0] ?? '');
          if (shouldSuppressInitLog(msg)) return;
          origLog.apply(console, args);
        };

        // #4132: better-sqlite3 cannot create a missing parent directory. In a
        // fresh checkout or worktree `.swarm/` does not exist yet, so AgentDB
        // failed to open, the degraded registry was cached for the server's
        // lifetime and hierarchical memory silently ran volatile.
        try {
          if (resolvedPath !== ':memory:') mkdirSync(path.dirname(resolvedPath), { recursive: true });
          await (registry as any).initialize({
            // #2786: use agentdb-memory.db (plaintext) so native better-sqlite3 doesn't hit the encrypted memory.db.
            dbPath: resolvedPath,
            embeddingModel: 'Xenova/all-MiniLM-L6-v2',
            dimension: 384,
            vectorBackend: 'auto',
            controllers: {
              reasoningBank: true,
              learningBridge: false,
              tieredCache: true,
              hierarchicalMemory: true,
              memoryConsolidation: true,
              memoryGraph: true,
              vectorBackend: true,
            },
          });
        } finally {
          console.log = origLog;
        }

        // Wire intelligence module as the learning backend.
        // AgentDB's ReasoningBank/LearningSystem need a better-sqlite3 db
        // handle which ControllerRegistry doesn't expose. Instead, use the
        // local intelligence module (SONA + LocalReasoningBank + file
        // persistence) for learning.
        //
        // PERF: parallelize the two independent post-init paths
        // (intelligence module load + agentdb import). Previously these
        // ran serially, adding ~50-150ms to cold start. Both can resolve
        // concurrently because they touch disjoint controller slots.
        try {
          const reg = registry as any;

          const intelligencePromise = (async () => {
            try {
              const intelligence = await import('./intelligence.js');
              const initResult = await intelligence.initializeIntelligence();

              if (initResult.reasoningBankEnabled) {
                const rb = intelligence.getReasoningBank();
                if (rb && !reg.get('reasoningBank')) {
                  if (typeof reg.set === 'function') reg.set('reasoningBank', rb);
                  else reg._controllers = { ...(reg._controllers || {}), reasoningBank: rb };
                }
              }

              if (initResult.sonaEnabled) {
                const sona = intelligence.getSonaCoordinator();
                if (sona && !reg.get('learningSystem')) {
                  if (typeof reg.set === 'function') reg.set('learningSystem', sona);
                  else reg._controllers = { ...(reg._controllers || {}), learningSystem: sona };
                }
              }
            } catch { /* intelligence module not available — learning stays unwired */ }
          })();

          const agentdbPromise = (async () => {
            // Single import shared across SkillLibrary + SemanticRouter probe.
            let agentdb: Record<string, unknown> | null = null;
            try { agentdb = (await import('agentdb')) as unknown as Record<string, unknown>; }
            catch { return; /* AgentDB not available */ }

            // SkillLibrary requires the same database and passage embedder as AgentDB.
            try {
              const SkillCtor = agentdb.SkillLibrary as (new (db: unknown, embedder: unknown) => unknown) | undefined;
              const backing = reg.getAgentDB?.();
              if (SkillCtor && !reg.get('skills') && backing?.database
                && typeof backing.embedder?.embedPassage === 'function') {
                const sk = new SkillCtor(backing.database, backing.embedder);
                if (typeof reg.set === 'function') reg.set('skills', sk);
                else reg._controllers = { ...(reg._controllers || {}), skills: sk };
              }
            } catch { /* SkillLibrary optional */ }

            // ADR-093 F9: probe multiple router class names across agentdb
            // alpha versions (alpha.10 had SemanticRouter; alpha.11+ removed
            // it in favor of @ruvector/router; future versions may
            // reintroduce). Wire only if .route() is callable.
            try {
              const candidates = ['SemanticRouter', 'IntentRouter', 'TaskRouter'] as const;
              let routerInstance: { route?: (input: string) => Promise<unknown> | unknown } | null = null;
              for (const name of candidates) {
                const Ctor = agentdb[name];
                if (typeof Ctor === 'function') {
                  try {
                    const inst = (() => {
                      try { return new (Ctor as new (cfg: { dimension: number }) => unknown)({ dimension: 384 }); }
                      catch { return new (Ctor as new () => unknown)(); }
                    })() as { route?: (input: string) => Promise<unknown> | unknown };
                    if (inst && typeof inst.route === 'function') {
                      routerInstance = inst;
                      break;
                    }
                  } catch { /* try next candidate */ }
                }
              }
              if (routerInstance && !reg.get('semanticRouter')) {
                if (typeof reg.set === 'function') reg.set('semanticRouter', routerInstance);
                else reg._controllers = { ...(reg._controllers || {}), semanticRouter: routerInstance };
              }
            } catch { /* router optional */ }

            // ADR-095 G7: load disabled-by-default controllers via direct
            // file:// URLs from the bundled agentdb. agentdb's exports
            // field doesn't expose these subpaths and we can't reliably
            // patch it across pnpm-hoisted multi-version trees, so we
            // sidestep the exports field entirely and import the file
            // by absolute URL. Only loads controllers whose constructor
            // is safe with no special prerequisites — others remain off
            // pending per-controller activation ADRs.
            try {
              const { createRequire } = await import('node:module');
              const { pathToFileURL } = await import('node:url');
              const path = await import('node:path');
              const fs = await import('node:fs');
              const cjsRequire = createRequire(import.meta.url);
              let adbPkgJsonPath: string | null = null;
              try { adbPkgJsonPath = cjsRequire.resolve('agentdb/package.json'); } catch { adbPkgJsonPath = null; }
              if (adbPkgJsonPath) {
                const adbDir = path.dirname(adbPkgJsonPath);
                const candidates: Array<{ name: string; relPath: string; configurable: boolean }> = [
                  // GNNService and RVFOptimizer can construct with no args
                  // in current agentdb — safe to activate as-is.
                  { name: 'gnnService', relPath: 'dist/src/services/GNNService.js', configurable: false },
                  { name: 'rvfOptimizer', relPath: 'dist/src/optimizations/RVFOptimizer.js', configurable: false },
                  // ADR-095 G7 follow-up: MutationGuard constructs cleanly
                  // with no args and exposes WASM-backed proof generation.
                  // No external deps; safe-default activation.
                  { name: 'mutationGuard', relPath: 'dist/src/security/MutationGuard.js', configurable: false },
                  // AttestationLog needs a sqlite db handle — wired below
                  // separately because we have to construct a db too.
                  // GuardedVectorBackend needs key material — leave for
                  // follow-up ADR.
                ];
                for (const cand of candidates) {
                  if (reg.get(cand.name)) continue;
                  const abs = path.join(adbDir, cand.relPath);
                  if (!fs.existsSync(abs)) continue;
                  try {
                    const url = pathToFileURL(abs).href;
                    const mod = await import(url) as Record<string, unknown>;
                    // Look for a default export, named export matching the
                    // file basename, or any class-typed export.
                    const baseName = path.basename(cand.relPath, '.js');
                    const Ctor = (mod[baseName] || mod.default ||
                      Object.values(mod).find(v => typeof v === 'function')) as (new () => unknown) | undefined;
                    if (typeof Ctor !== 'function') continue;
                    const inst = new Ctor();
                    if (typeof reg.set === 'function') reg.set(cand.name, inst);
                    else reg._controllers = { ...(reg._controllers || {}), [cand.name]: inst };
                  } catch { /* skip controllers that fail to construct */ }
                }

                // AttestationLog activation — needs a better-sqlite3
                // database. We open a dedicated file at .swarm/attestation.db
                // (separate from the main memory.db so the audit trail
                // is isolated). Best-effort: if better-sqlite3 isn't
                // resolvable in this env, skip cleanly.
                let attestationInst: unknown = null;
                if (!reg.get('attestationLog')) {
                  try {
                    const attestationFile = path.join(adbDir, 'dist/src/security/AttestationLog.js');
                    if (fs.existsSync(attestationFile)) {
                      // #3693: same better-sqlite3 copy AgentDB uses, so closing this handle cannot disturb its WAL.
                      const Database = ((resolveAgentdbBetterSqlite3() ?? cjsRequire('better-sqlite3')) as unknown) as new (p: string) => unknown;
                      const swarmDir = path.resolve(process.cwd(), '.swarm');
                      if (!fs.existsSync(swarmDir)) fs.mkdirSync(swarmDir, { recursive: true });
                      const dbPath = path.join(swarmDir, 'attestation.db');
                      const db = new Database(dbPath);
                      const url = pathToFileURL(attestationFile).href;
                      const mod = await import(url) as Record<string, unknown>;
                      const Ctor = mod.AttestationLog as (new (cfg: { db: unknown }) => unknown) | undefined;
                      if (typeof Ctor === 'function') {
                        const inst = new Ctor({ db });
                        attestationInst = inst;
                        if (typeof reg.set === 'function') reg.set('attestationLog', inst);
                        else reg._controllers = { ...(reg._controllers || {}), attestationLog: inst };
                      }
                    }
                  } catch { /* better-sqlite3 missing or schema init failed — skip silently */ }
                }

                // ADR-095 G7 follow-up: GuardedVectorBackend wraps the
                // existing vectorBackend with mutationGuard + attestationLog
                // for proof-gated state mutations (ADR-060). All three
                // dependencies are reachable here — vectorBackend is in
                // the baseline init, mutationGuard was just activated, and
                // attestationLog is constructed above. Skip if any piece
                // is missing rather than constructing with undefined.
                if (!reg.get('guardedVectorBackend')) {
                  try {
                    const gvbFile = path.join(adbDir, 'dist/src/backends/ruvector/GuardedVectorBackend.js');
                    if (fs.existsSync(gvbFile)) {
                      const inner = reg.get('vectorBackend');
                      const guard = reg.get('mutationGuard');
                      const log = attestationInst ?? reg.get('attestationLog');
                      if (inner && guard) {
                        const url = pathToFileURL(gvbFile).href;
                        const mod = await import(url) as Record<string, unknown>;
                        const Ctor = mod.GuardedVectorBackend as (new (i: unknown, g: unknown, l: unknown) => unknown) | undefined;
                        if (typeof Ctor === 'function') {
                          const inst = new Ctor(inner, guard, log);
                          if (typeof reg.set === 'function') reg.set('guardedVectorBackend', inst);
                          else reg._controllers = { ...(reg._controllers || {}), guardedVectorBackend: inst };
                        }
                      }
                    }
                  } catch { /* GuardedVectorBackend optional */ }
                }
              }
            } catch { /* G7 wiring optional */ }
          })();

          // Run both in parallel; settle either way so a single failing
          // path doesn't tear down the rest of the post-init wiring.
          await Promise.allSettled([intelligencePromise, agentdbPromise]);

          // Remaining disabled controllers tracked in ADR-095 G7 for
          // per-controller activation ADRs:
          //   - graphAdapter (graph DB adapter — needs graph DB connection)
        } catch {
          // Top-level catch — registry stays usable even if post-init wiring fails wholesale.
        }

        registryInstances.set(resolvedPath, registry);
        bridgeFailureReasons.delete(resolvedPath);
        return registry;
      } catch (err) {
        // initialize() may have opened a native handle before it failed.
        try { await registry?.shutdown(); } catch { /* best-effort cleanup */ }
        // Keep the failed promise for this path only. Other databases can
        // still initialize; shutdownBridge() clears the latch for a retry.
        bridgeFailureReasons.set(resolvedPath, err instanceof Error ? err.message : String(err));
        return null;
      }
    })();
    registryPromises.set(resolvedPath, registryPromise);
  }

  return registryPromise;
}

/** Test seam: forget cached registries so a test can exercise a fresh open. */
export function _resetRegistryCacheForTest(): void {
  registryPromises.clear();
  registryInstances.clear();
  testRegistryOverride = null;
  testRegistryFactory = null;
  bridgeFailureReasons.clear();
}

/** Inject registry construction without requiring the optional native package in tests. */
export function __setMemoryBridgeRegistryFactoryForTests(factory: (() => any) | null): void {
  testRegistryFactory = factory;
}

/** #3196: the sibling store AgentDB owns next to a given sql.js database. */
export function siblingAgentDbPath(dbPath: string): string | null {
  if (!dbPath || dbPath === ':memory:') return null;
  const sibling = path.join(path.dirname(path.resolve(dbPath)), 'agentdb-memory.db');
  return path.resolve(dbPath) === sibling ? null : sibling;
}

// ===== Phase 2: BM25 hybrid scoring =====

/**
 * BM25 scoring for keyword-based search.
 * Replaces naive String.includes() with proper information retrieval scoring.
 * Parameters tuned for short memory entries (k1=1.2, b=0.75).
 */
function bm25Score(
  queryTerms: string[],
  docWords: string[],
  docLength: number,
  avgDocLength: number,
  docCount: number,
  termDocFreqs: Map<string, number>,
): number {
  const k1 = 1.2;
  const b = 0.75;

  let score = 0;
  for (const term of queryTerms) {
    const tf = docWords.filter(w => w === term || w.includes(term)).length;
    if (tf === 0) continue;

    const df = termDocFreqs.get(term) || 1;
    const idf = Math.log((docCount - df + 0.5) / (df + 0.5) + 1);
    const tfNorm = (tf * (k1 + 1)) / (tf + k1 * (1 - b + b * (docLength / Math.max(1, avgDocLength))));
    score += idf * tfNorm;
  }

  return score;
}

/**
 * Tokenize a corpus once per query. Each row is lowercased + split a single
 * time; the resulting `{ contentLower, words }` feed BM25 term-frequency,
 * per-doc BM25 scoring, and the #2558 coverage floor — which previously each
 * re-lowercased+re-split the same content (3× string scans per row).
 * Bit-identical to the prior split-per-consumer path.
 */
interface TokenizedDoc { contentLower: string; words: string[] }
function tokenizeCorpus(rows: Array<{ content: string }>): TokenizedDoc[] {
  return rows.map(row => {
    const contentLower = (row.content || '').toLowerCase();
    return { contentLower, words: contentLower.split(/\s+/) };
  });
}

/**
 * Compute BM25 term document frequencies over an already-tokenized corpus.
 */
function computeTermDocFreqs(
  queryTerms: string[],
  docs: TokenizedDoc[],
): { termDocFreqs: Map<string, number>; avgDocLength: number } {
  const termDocFreqs = new Map<string, number>();
  let totalLength = 0;

  for (const doc of docs) {
    totalLength += doc.words.length;
    for (const term of queryTerms) {
      if (doc.contentLower.includes(term)) {
        termDocFreqs.set(term, (termDocFreqs.get(term) || 0) + 1);
      }
    }
  }

  return { termDocFreqs, avgDocLength: docs.length > 0 ? totalLength / docs.length : 1 };
}

// ===== Phase 2: TieredCache helpers =====

/** Preserve the exact namespace/key tuple; punctuation is valid memory data. */
function entryCacheKey(namespace: string, key: string): string {
  return `entry:${JSON.stringify([namespace, key])}`;
}


/**
 * Try to read from TieredCache before hitting DB.
 * Returns cached value or null if cache miss.
 */
async function cacheGet(registry: any, cacheKey: string): Promise<any | null> {
  try {
    const cache = registry.get('tieredCache');
    if (!cache || typeof cache.get !== 'function') return null;
    return cache.get(cacheKey) ?? null;
  } catch {
    return null;
  }
}

/**
 * Cross-process cache coherence.
 *
 * The TieredCache lives in this process, but the database file is shared:
 * Claude Code, Codex and Grok each run their own `mcp start` against the
 * same `.swarm/` store, and each process only invalidates entries on its
 * OWN writes. A key another process updated or deleted kept coming back
 * from this process's cache — old value, `found: true` — until the cached
 * entry expired (TieredCache TTL, 5 minutes by default; reads don't extend
 * it).
 *
 * SQLite's `PRAGMA data_version` changes whenever a DIFFERENT connection has
 * committed to the database file since this connection last asked, and never
 * for this connection's own writes (https://sqlite.org/pragma.html#pragma_data_version).
 * Checking it before a cached read is an exact "has anyone else written?"
 * test that costs one pragma call. When it moves, drop the whole cache:
 * every cached shape was derived from the old database state. The first
 * check on a handle records its baseline and clears: a no-op for a fresh
 * handle, and the right thing if a handle is ever replaced under a live
 * cache.
 *
 * Native better-sqlite3 handles only. agentdb's sql.js fallback works on a
 * private in-memory image that never sees another process's commits, so
 * there is nothing to detect; it is skipped rather than probed. A handle
 * that cannot prepare the check is remembered and never probed again; a
 * check that fails on a given read (e.g. SQLITE_BUSY) clears the cache for
 * safety and is simply retried on the next read.
 */
const _cacheDataVersionStmts = new WeakMap<object, { get(): { data_version?: unknown } | undefined }>();
const _cacheDataVersions = new WeakMap<object, number>();
const _cacheDataVersionUnsupported = new WeakSet<object>();

function dropCacheIfDbChangedElsewhere(registry: any, ctx: { db: any; agentdb?: any }): void {
  // Never let this check break the read it guards: any throw falls back to
  // the pre-fix behaviour (a possibly stale hit).
  try {
    const db = ctx.db;
    if (!db || ctx.agentdb?.isWasm === true || !('inTransaction' in db)) return;
    if (_cacheDataVersionUnsupported.has(db)) return;
    let stmt = _cacheDataVersionStmts.get(db);
    if (!stmt) {
      try {
        stmt = db.prepare('PRAGMA data_version');
        _cacheDataVersionStmts.set(db, stmt!);
      } catch {
        _cacheDataVersionUnsupported.add(db); // structural: this handle can't answer
        return;
      }
    }
    let cache: any = null;
    try { cache = registry.get('tieredCache'); } catch { /* no cache, nothing to drop */ }
    try {
      const version = stmt!.get()?.data_version;
      if (typeof version !== 'number') {
        // #3360: an unusable answer is not evidence the store is unchanged.
        // Same posture as the catch below — a check we cannot validate drops
        // the cache rather than trusting it, and leaves the baseline alone so
        // the next read re-checks.
        if (cache && typeof cache.clear === 'function') cache.clear();
        return;
      }
      if (_cacheDataVersions.get(db) === version) return;
      if (cache && typeof cache.clear === 'function') cache.clear();
      _cacheDataVersions.set(db, version);
    } catch {
      // Transient (e.g. SQLITE_BUSY): don't trust the cache for this read.
      if (cache && typeof cache.clear === 'function') cache.clear();
    }
  } catch {
    // Non-fatal.
  }
}

/**
 * Write to TieredCache after DB write.
 */
async function cacheSet(registry: any, cacheKey: string, value: any): Promise<void> {
  try {
    const cache = registry.get('tieredCache');
    if (cache && typeof cache.set === 'function') {
      cache.set(cacheKey, value);
    }
  } catch {
    // Non-fatal
  }
}

/**
 * Invalidate a cache key after mutation.
 */
async function cacheInvalidate(registry: any, cacheKey: string): Promise<void> {
  try {
    const cache = registry.get('tieredCache');
    if (cache && typeof cache.delete === 'function') {
      cache.delete(cacheKey);
    }
  } catch {
    // Non-fatal
  }
}

// ===== Phase 2: MutationGuard helpers =====

/**
 * Validate a mutation through MutationGuard before executing.
 * Returns true if the mutation is allowed, false if rejected.
 * When guard is unavailable (not installed), mutations are allowed.
 * When guard is present but throws, mutations are DENIED (fail-closed).
 */
async function guardValidate(
  registry: any,
  operation: string,
  params: Record<string, unknown>,
): Promise<{ allowed: boolean; reason?: string }> {
  try {
    const guard = registry.get('mutationGuard');
    if (!guard || typeof guard.validate !== 'function') {
      return { allowed: true }; // No guard installed = allow (degraded mode)
    }
    const result = guard.validate({ operation, params, timestamp: Date.now() });
    return { allowed: result?.allowed === true, reason: result?.reason };
  } catch {
    return { allowed: false, reason: 'MutationGuard validation error' }; // Fail-closed
  }
}

// ===== Phase 3: AttestationLog helpers =====

/**
 * Log a write operation to AttestationLog/WitnessChain.
 */
async function logAttestation(
  registry: any,
  operation: string,
  entryId: string,
  metadata?: Record<string, unknown>,
): Promise<void> {
  try {
    const attestation = registry.get('attestationLog');
    if (!attestation) return;

    if (typeof attestation.record === 'function') {
      attestation.record({ operation, entryId, timestamp: Date.now(), ...metadata });
    } else if (typeof attestation.log === 'function') {
      attestation.log(operation, entryId, metadata);
    }
  } catch {
    // Non-fatal — attestation is observability, not correctness
  }
}

// Tracks db handles whose schema DDL has already been ensured, so getDb()
// runs the CREATE…IF NOT EXISTS block at most once per handle instead of on
// every bridge call. WeakSet so handles GC without leaking.
const _schemaEnsuredDbs = new WeakSet<object>();

/**
 * Create/migrate the bridge's `memory_entries` table on `db`.
 *
 * Returns true when the schema is known-good, false when the database was not
 * writable (caller then leaves it un-ensured so a later writable call retries).
 *
 * Exported so the ADR-323 column migration can be tested directly: the bug it
 * fixes was invisible end-to-end, because the resulting error was swallowed and
 * reported as an unrelated WAL-sidecar refusal.
 */
export function ensureBridgeSchema(db: { exec: (sql: string) => unknown }): boolean {
  try {
    db.exec(`CREATE TABLE IF NOT EXISTS memory_entries (
      id TEXT PRIMARY KEY,
      key TEXT NOT NULL,
      namespace TEXT DEFAULT 'default',
      content TEXT NOT NULL,
      type TEXT DEFAULT 'semantic',
      embedding TEXT,
      embedding_model TEXT DEFAULT 'local',
      embedding_dimensions INTEGER,
      tags TEXT,
      metadata TEXT,
      owner_id TEXT,
      created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
      updated_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now') * 1000),
      expires_at INTEGER,
      last_accessed_at INTEGER,
      access_count INTEGER DEFAULT 0,
      status TEXT DEFAULT 'active',
      provenance_type TEXT DEFAULT 'unknown',
      UNIQUE(namespace, key)
    )`);
    // ADR-323 added provenance_type to bridgeStoreEntry's INSERT, and
    // ensureSchemaColumns() backfills it on the sql.js path — the bridge path
    // had no equivalent. `CREATE TABLE IF NOT EXISTS` is a no-op on a table
    // created before ADR-323, so on any pre-existing database every bridge
    // write threw "table memory_entries has no column named provenance_type",
    // was swallowed by the catch at the end of bridgeStoreEntry(), and demoted
    // the caller to the sql.js whole-image path — which then refused with a
    // WAL-sidecar error naming an unrelated cause. Silent, total write loss.
    try {
      db.exec(`ALTER TABLE memory_entries ADD COLUMN provenance_type TEXT DEFAULT 'unknown'`);
    } catch (err) {
      // Already present is the common case. SQLite has no ADD COLUMN IF NOT
      // EXISTS, so attempt-and-ignore only that exact condition. Treating a
      // read-only, locked, or corrupt database as migrated would cache a
      // schema that bridgeStoreEntry() still cannot use.
      const msg = err instanceof Error ? err.message : String(err);
      if (!/duplicate column name:\s*provenance_type/i.test(msg)) {
        throw err;
      }
    }
    // Reads now enforce TTL, including on stores created before expires_at
    // existed. A missing expiration means the legacy row does not expire.
    try {
      db.exec('ALTER TABLE memory_entries ADD COLUMN expires_at INTEGER');
    } catch (error) {
      if (!/duplicate column name:\s*expires_at/i.test(error instanceof Error ? error.message : String(error))) throw error;
    }
    db.exec(`CREATE INDEX IF NOT EXISTS idx_bridge_ns ON memory_entries(namespace)`);
    db.exec(`CREATE INDEX IF NOT EXISTS idx_bridge_key ON memory_entries(key)`);
    db.exec(`CREATE INDEX IF NOT EXISTS idx_bridge_status ON memory_entries(status)`);
    return true;
  } catch {
    // Read-only database — leave it un-ensured so a writable call can retry.
    return false;
  }
}


/**
 * Get the AgentDB database handle and ensure memory_entries table exists.
 * Returns null if not available.
 */
function getDb(registry: any): any | null {
  const agentdb = registry.getAgentDB();
  if (!agentdb?.database) return null;

  const db = agentdb.database;

  // Ensure memory_entries table exists (idempotent). The DDL is run at most
  // once per db handle — re-parsing 4× CREATE…IF NOT EXISTS on every bridge
  // call (store/search/get) was pure per-op overhead. Keyed by handle via a
  // WeakSet so a new db instance re-ensures without a stale global flag.
  if (!_schemaEnsuredDbs.has(db)) {
    if (ensureBridgeSchema(db)) _schemaEnsuredDbs.add(db);
  }

  // ─── #2256-followup: rescue agentdb.embedder when its transformers.js
  // path fell through to mock embeddings.
  //
  // What was happening: agentdb's `EmbeddingService.initialize()` always
  // tries `@xenova/transformers` first, which transitively requires `sharp`
  // → `libvips`. On macOS arm64 systems without `brew install vips`, sharp
  // fails to load and agentdb silently falls back to MOCK EMBEDDINGS
  // (random vectors). The bridge then calls `agentdb.embedder.embed(...)`
  // and gets garbage; semantic search returns no useful matches.
  //
  // In our process, `memory-initializer.ts::loadEmbeddingModel()` already
  // tried this same chain and ALSO has a working ruvector-ONNX fallback
  // that the user typically reaches before the bridge initialises. The
  // ruvector ONNX model has been loaded; the agentdb instance just doesn't
  // know about it. We monkey-patch `embed`/`embedBatch` to delegate to our
  // `generateEmbedding()` so the bridge gets real vectors.
  //
  // Detection signal: `embedder.pipeline === null` after init means
  // transformers failed and agentdb would otherwise use mockEmbedding().
  // Patch is idempotent (`__ruvectorRescued` sentinel) and a no-op if
  // ruvector is also unavailable.
  rescueAgentdbEmbedder(agentdb).catch(() => { /* non-fatal */ });

  return { db, agentdb };
}

// The rescue is idempotent per embedder via __ruvectorRescued. A process-wide
// flag would skip later dbPath registries and leave their embedder on mock (#4410).
/** @internal Exported for the multi-store rescue regression test. */
export async function rescueAgentdbEmbedder(agentdb: { embedder?: { pipeline?: unknown; embed?: (t: string) => Promise<Float32Array>; embedBatch?: (ts: string[]) => Promise<Float32Array[]>; __ruvectorRescued?: boolean } }): Promise<void> {
  const emb = agentdb?.embedder;
  if (!emb || emb.__ruvectorRescued) return;

  // Only rescue when transformers.js initialisation failed: that's
  // signalled by a null pipeline. If transformers IS working, agentdb's
  // own embed() does the right thing and we should not interpose.
  if (emb.pipeline) return;

  // #2312: delegate to generateLOCALEmbedding, NOT generateEmbedding.
  // generateEmbedding is bridge-first — routing the rescued embed through it
  // closes a cycle (generateEmbedding → bridgeGenerateEmbedding →
  // embedder.embed [patched] → generateEmbedding → …) that allocated
  // unboundedly via microtasks until V8 hit the heap limit (~4 GB on the CI
  // runner, SIGABRT 134). The local chain never consults the bridge, so the
  // rescued embedder is a leaf. If the running memory-initializer build
  // predates generateLocalEmbedding, decline the rescue entirely — a stale
  // pairing must fail safe, not recurse.
  type EmbedFn = (text: string) => Promise<{ embedding: number[] | Float32Array; dimensions: number; model: string; backend?: 'onnx' | 'mock' }>;
  let localEmbed: EmbedFn | null = null;
  try {
    const mod = (await import('./memory-initializer.js')) as unknown as { generateLocalEmbedding?: EmbedFn };
    localEmbed = mod.generateLocalEmbedding ?? null;
  } catch {
    return; // can't import the rescuer — leave the mock fallback alone
  }
  if (!localEmbed) return;
  const embed: EmbedFn = localEmbed;

  // Probe once to confirm the rescuer actually returns REAL ONNX vectors
  // (#2312: the old probe only checked non-zero, which the deterministic
  // hash fallback also satisfies — so it "rescued" agentdb's mock with our
  // own mock and reported it as real). Require backend === 'onnx'.
  try {
    const probe = await embed('rescue-probe');
    const arr = probe?.embedding ? Array.from(probe.embedding as ArrayLike<number>) : [];
    const hasSignal = arr.length > 0 && arr.some((v: number) => Math.abs(v) > 1e-9);
    if (!hasSignal || probe.backend !== 'onnx') {
      // Local chain is also degraded — leave agentdb's embedder alone, but
      // tag it so bridgeGenerateEmbedding's AUDIT-#3 isMock check reports
      // backend='mock' truthfully instead of labeling mock vectors 'onnx'.
      try { (emb as { backend?: string }).backend = 'mock'; } catch { /* frozen */ }
      return;
    }
  } catch {
    return;
  }

  const newEmbed = async (text: string): Promise<Float32Array> => {
    const out = await embed(text);
    return out.embedding instanceof Float32Array
      ? out.embedding
      : new Float32Array((out.embedding as number[]) ?? []);
  };
  emb.embed = newEmbed;
  emb.embedBatch = async (texts: string[]): Promise<Float32Array[]> =>
    Promise.all(texts.map(t => newEmbed(t)));
  emb.__ruvectorRescued = true;
}

/** AgentDB uses a null pipeline while its transformer failed and it serves mock vectors. */
function isMockAgentdbEmbedder(embedder: {
  isMock?: boolean;
  backend?: string;
  pipeline?: unknown;
  __ruvectorRescued?: boolean;
} | null | undefined): boolean {
  return embedder?.isMock === true || embedder?.backend === 'mock'
    || (embedder?.pipeline === null && embedder.__ruvectorRescued !== true);
}

/**
 * #3325: embed text for a bridge row or query.
 *
 * AgentDB's embedder is tried first. If it is absent or throws, fall back to
 * the LOCAL chain — `generateLocalEmbedding`, never the bridge-first
 * `generateEmbedding`, which would re-enter this bridge (#2312). Only a real
 * ONNX vector is accepted from the local chain; a hash vector would make the
 * row look embedded while carrying no meaning. Previously both failure modes
 * were a bare `catch {}` that stored embedding=NULL and reported nothing.
 */
async function embedForBridge(
  agentdb: { embedder?: { embed?: (t: string) => Promise<ArrayLike<number> | null | undefined>; isMock?: boolean; backend?: string; pipeline?: unknown; __ruvectorRescued?: boolean } } | null | undefined,
  text: string,
): Promise<{ vector: number[]; model: string } | { vector: null; reason: string }> {
  let agentdbProblem: string;
  const embedder = agentdb?.embedder;
  // Same mock signal bridgeGenerateEmbedding honours (AUDIT #3): the rescue
  // tags a degraded embedder backend='mock' when it cannot replace it.
  // The rescue launched by getDb() is fire-and-forget. Do not persist mock
  // vectors during that window just because they happen to be 384-dimension.
  const agentdbIsMock = isMockAgentdbEmbedder(embedder);
  if (agentdbIsMock) {
    agentdbProblem = 'agentdb embedder is serving mock vectors';
  } else if (embedder && typeof embedder.embed === 'function') {
    try {
      const emb = await embedder.embed(text);
      if (emb && emb.length > 0) {
        return { vector: Array.from(emb), model: 'Xenova/all-MiniLM-L6-v2' };
      }
      agentdbProblem = 'agentdb embedder returned no vector';
    } catch (err) {
      agentdbProblem = `agentdb embedder threw: ${err instanceof Error ? err.message : String(err)}`;
    }
  } else {
    agentdbProblem = 'agentdb embedder unavailable';
  }

  try {
    const { generateLocalEmbedding } = await import('./memory-initializer.js');
    const local = await generateLocalEmbedding(text);
    if (local.backend === 'onnx' && local.embedding.length > 0) {
      return { vector: Array.from(local.embedding), model: local.model };
    }
    return { vector: null, reason: `${agentdbProblem}; local embedding chain has no real model (backend=${local.backend})` };
  } catch (err) {
    return { vector: null, reason: `${agentdbProblem}; local embedding chain failed: ${err instanceof Error ? err.message : String(err)}` };
  }
}

// ===== Bridge functions — match memory-initializer.ts signatures =====

/**
 * Store an entry via AgentDB v3.
 * Phase 2-5: Routes through MutationGuard → TieredCache → DB → AttestationLog.
 * Returns null to signal fallback to sql.js.
 */
export async function bridgeStoreEntry(options: {
  key: string;
  value: string;
  namespace?: string;
  generateEmbeddingFlag?: boolean;
  tags?: string[];
  ttl?: number;
  dbPath?: string;
  upsert?: boolean;
  requireNative?: boolean;
  appendOnly?: boolean;
  appendConditions?: AppendCondition[];
  /** ADR-323: defaults to 'unknown' when omitted. */
  provenanceType?: string;
}): Promise<{
  success: boolean;
  id: string;
  embedding?: { dimensions: number; model: string };
  rawEmbedding?: number[];
  guarded?: boolean;
  cached?: boolean;
  attested?: boolean;
  error?: string;
  /** #2968: set when the post-write checkpoint failed in a way that
   *  indicates this connection may not durably persist writes at all
   *  (the sql.js fallback driver, engaged when better-sqlite3's native
   *  binding is missing). The write above still ran and `success` is
   *  still true — this is advisory, not a failure — but callers should
   *  surface it instead of only printing an unconditional success message. */
  persistWarning?: string;
  /** #3325: set when an embedding was requested but none could be produced
   *  (agentdb embedder absent/threw AND no real local model). The row was
   *  written without a vector, so semantic search cannot find it. */
  embeddingError?: string;
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeStoreEntry(options));
  // ADR-323 — validated once in storeEntry() before this is reached on that
  // path, but bridgeStoreEntry() also has direct internal callers, so check
  // again here rather than trust every call site.
  if (options.provenanceType !== undefined && !isValidProvenanceType(options.provenanceType)) {
    return {
      success: false,
      id: '',
      error: `Invalid provenance type "${options.provenanceType}"`,
    };
  }

  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;

  const ctx = getDb(registry);
  if (!ctx) return null;

  if (options.appendOnly && !options.requireNative) {
    return { success: false, id: '', error: 'Immutable append requires a native writer' };
  }
  if (options.appendConditions && (!options.requireNative || !options.appendOnly)) {
    return { success: false, id: "", error: "Conditional append requires native append-only storage" };
  }
  if (options.requireNative && (ctx.agentdb?.isWasm === true || typeof ctx.db.inTransaction !== 'boolean'
    || typeof ctx.db.transaction !== 'function' || ctx.db.memory !== false || typeof ctx.db.name !== 'string'
    || !ctx.db.name || canonicalDbPath(ctx.db.name) !== canonicalDbPath(options.dbPath))) {
    return { success: false, id: '', error: 'Native memory writer required; refusing non-native bridge driver' };
  }

  try {
    const { key, value, namespace = 'default', tags = [], ttl } = options;
    let provenanceType = options.provenanceType ?? 'unknown';
    // An omitted type on an upsert means "update the value", not "erase the
    // existing trust label". New rows still receive the backward-compatible
    // unknown default.
    if (options.upsert && !options.appendOnly && options.provenanceType === undefined) {
      try {
        const existing = ctx.db.prepare(
          'SELECT provenance_type FROM memory_entries WHERE namespace = ? AND key = ? LIMIT 1'
        ).get(namespace, key);
        provenanceType = existing?.provenance_type || 'unknown';
      } catch { /* legacy schema or new row — keep unknown */ }
    }
    const id = generateId('entry');
    const now = Date.now();

    // #2245 — record the activity so signalsProcessed stops being a dead
    // zero. Fire-and-forget; never blocks the write path.
    try {
      const intel = await import('./intelligence.js');
      intel.recordSignalProcessed();
    } catch { /* intelligence module not yet initialised */ }

    // Phase 5: MutationGuard validation before write
    const guardResult = await guardValidate(registry, 'store', { key, namespace, size: value.length });
    if (!guardResult.allowed) {
      return { success: false, id, error: `MutationGuard rejected: ${guardResult.reason}` };
    }

    // Generate embedding via AgentDB's embedder, falling back to the local
    // chain (#3325). If neither can produce one, the row is still written but
    // the result says why instead of silently storing embedding=NULL.
    let embeddingJson: string | null = null;
    let embeddingArr: number[] | null = null;
    let dimensions = 0;
    let model = 'local';
    let embeddingError: string | undefined;

    if (options.generateEmbeddingFlag !== false && value.length > 0) {
      const emb = await embedForBridge(ctx.agentdb, value);
      if (emb.vector) {
        embeddingArr = emb.vector;
        embeddingJson = JSON.stringify(embeddingArr);
        dimensions = embeddingArr.length;
        model = emb.model;
      } else {
        embeddingError = emb.reason;
      }
    }

    // #2775: strict-insert path now auto-resurrects soft-deleted tombstones
    // via ON CONFLICT DO UPDATE ... WHERE status='deleted'. Rationale:
    // `bridgeDeleteEntry` performs a soft delete (status='deleted'), so the
    // `UNIQUE(namespace, key)` slot stays occupied — before this fix, a
    // natural `delete → store` sequence hit UNIQUE, the catch below returned
    // `null`, `storeEntry` fell back to the sql.js whole-image path, and the
    // #2735 -wal/-shm sidecar guard refused with a message about a "native
    // WAL connection" that had nothing to do with the actual failure.
    //
    // Semantics under the new strict-insert SQL:
    //   • no existing row               → INSERT succeeds, changes = 1
    //   • existing row, status='deleted' → resurrected in-place, changes = 1
    //   • existing row, status='active'  → ON CONFLICT WHERE=false suppresses
    //                                       the update, changes = 0 (checked
    //                                       below → typed "already exists"
    //                                       error, NEVER a null demotion).
    // Upsert path (INSERT OR REPLACE) is unchanged.
    const immutableInsertSql = `INSERT INTO memory_entries (
          id, key, namespace, content, type,
          embedding, embedding_dimensions, embedding_model,
          tags, metadata, provenance_type, created_at, updated_at, expires_at, status
        ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active')`;
    const insertSql = options.appendOnly ? immutableInsertSql : options.upsert
      ? `INSERT OR REPLACE INTO memory_entries (
          id, key, namespace, content, type,
          embedding, embedding_dimensions, embedding_model,
          tags, metadata, provenance_type, created_at, updated_at, expires_at, status
        ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active')`
      : `INSERT INTO memory_entries (
          id, key, namespace, content, type,
          embedding, embedding_dimensions, embedding_model,
          tags, metadata, provenance_type, created_at, updated_at, expires_at, status
        ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, ?, ?, ?, ?, ?, ?, ?, 'active')
        ON CONFLICT(namespace, key) DO UPDATE SET
          id                    = excluded.id,
          content               = excluded.content,
          embedding             = excluded.embedding,
          embedding_dimensions  = excluded.embedding_dimensions,
          embedding_model       = excluded.embedding_model,
          tags                  = excluded.tags,
          metadata              = excluded.metadata,
          provenance_type       = excluded.provenance_type,
          created_at            = excluded.created_at,
          updated_at            = excluded.updated_at,
          expires_at            = excluded.expires_at,
          status                = 'active'
        WHERE memory_entries.status = 'deleted'`;

    // #1941: provision a `vector_indexes` row for this namespace before the
    // entry insert. AgentDB's HNSW/router keys lookups by namespace via this
    // table — if it has no row for e.g. `claude-memories`, `memory_search`
    // returns 0 results even when memory_entries holds hundreds of rows for
    // that namespace. INSERT OR IGNORE so existing index rows are preserved.
    try {
      ctx.db
        .prepare(`INSERT OR IGNORE INTO vector_indexes (id, name, dimensions) VALUES (?, ?, ?)`)
        .run(namespace, namespace, dimensions || 384);
    } catch { /* vector_indexes may not exist on legacy DBs — fall through */ }

    const stmt = ctx.db.prepare(insertSql);
    const insert = () => stmt.run(
      id, key, namespace, value,
      embeddingJson, dimensions || null, model,
      tags.length > 0 ? JSON.stringify(tags) : null,
      '{}',
      provenanceType,
      now, now,
      ttl ? now + (ttl * 1000) : null
    );

    let runResult;
    try {
      runResult = options.appendOnly
        ? ctx.db.transaction(() => {
            // Legacy native tables may predate UNIQUE(namespace,key). Serialize the exact
            // logical-slot check with INSERT, including tombstones, instead of trusting DDL.
            if (ctx.db.prepare('SELECT key FROM memory_entries WHERE namespace = ? AND key = ?').all(namespace, key).length) {
              throw new AppendConditionFailed('immutable append rejected: logical key already exists');
            }
            if (options.appendConditions) assertAppendConditions(ctx.db, validateAppendConditions(options.appendConditions));
            return insert();
          }).immediate()
        : insert();
    } catch (error) {
      if (error instanceof AppendConditionFailed || error instanceof TypeError) {
        return { success: false, id: '', error: error.message };
      }
      throw error;
    }

    // A completed native write proves the bridge is currently healthy. Do not
    // retain a diagnostic from an earlier transient failure and append it to a
    // later, unrelated sql.js fallback refusal.
    bridgeFailureReasons.delete(canonicalDbPath(options.dbPath));

    // #2775: strict insert against an ACTIVE existing row → changes === 0
    // (the ON CONFLICT WHERE clause above suppressed the update). Surface
    // this as a typed data-level error rather than a bridge failure —
    // returning non-null so the caller does NOT demote to sql.js and does
    // NOT trip the #2735 whole-image guard with a misleading message.
    if (!options.upsert && (runResult?.changes ?? 0) === 0) {
      return {
        success: false,
        id,
        error: `key "${key}" already exists in namespace "${namespace}" — pass upsert=true (--upsert on the CLI) to update it`,
      };
    }

    // A non-vector immutable INSERT cannot change the vector count, even with concurrent
    // writers. Unlike historical strict mode, it never resurrects a vector tombstone.
    // #2558: keep `vector_indexes.total_vectors` accurate so status/tooling
    // stop reporting "HNSW index: 0 vectors" while embedded entries exist.
    if (!(options.appendOnly && embeddingJson === null)) try {
      ctx.db
        .prepare(
          `UPDATE vector_indexes SET
             total_vectors = (SELECT COUNT(*) FROM memory_entries
                              WHERE namespace = ? AND embedding IS NOT NULL),
             updated_at = ?
           WHERE name = ?`,
        )
        .run(namespace, now, namespace);
    } catch { /* vector_indexes may not exist on legacy DBs — non-fatal */ }

    // #2558: better-sqlite3 opens the DB in WAL mode and, for the small write
    // volumes typical of CLI usage, may never reach the auto-checkpoint
    // threshold — leaving committed rows only in the -wal file. WAL-blind
    // readers (the sql.js fallback search path; the statusline's read-only
    // `sqlite3` vector count) then see a stale/empty main DB file and report
    // "0 vectors" / empty search. A PASSIVE checkpoint flushes committed pages
    // into the main file without blocking writers. Best-effort, never fatal.
    let persistWarning: string | undefined;
    try {
      if (typeof ctx.db.pragma === 'function') {
        ctx.db.pragma('wal_checkpoint(PASSIVE)');
      }
    } catch (checkpointErr) {
      // #2968: on the sql.js fallback driver (engaged when better-sqlite3's
      // native binding never got built — e.g. a skipped optionalDependency
      // postinstall), this PRAGMA isn't implemented and throws "Invalid
      // PRAGMA command". sql.js has no WAL journal to checkpoint at all, so
      // this specific failure is the strongest signal available here that
      // the insert above may exist only in this process's in-memory image
      // and never reach disk — not the ordinary "non-WAL, busy, or
      // unsupported" case the old blanket catch assumed. Surface it rather
      // than swallow it silently; other pragma failures stay non-fatal.
      const msg = checkpointErr instanceof Error ? checkpointErr.message : String(checkpointErr);
      if (/Invalid PRAGMA/i.test(msg)) {
        persistWarning = `sql.js fallback driver in use — this write may not be durably persisted to disk (${msg}). Install better-sqlite3's native binding to restore durable writes (see issue #2968: npm rebuild better-sqlite3, or reinstall with install scripts enabled).`;
      }
    }

    // Phase 2: Invalidate cache so the next read fetches the fresh row.
    //
    // #3051 — this used to be a write-through with a partial payload
    // (`{ id, key, namespace, content, embedding }` — missing `tags`,
    // access_count, timestamps, metadata, provenance_type). Any read that
    // hit the cache then returned `tags: cached.tags || []` = `[]` for the
    // very entry that had just been written with real tags, so
    // `memory_store({ tags })` → `memory_retrieve()` looked like it silently
    // dropped tags. Invalidating instead of partial-cache-set forces the
    // next `bridgeGetEntry` to load the authoritative row (which correctly
    // parses tags/metadata from the JSON columns) and repopulate the cache
    // from that full shape.
    const cacheKey = entryCacheKey(namespace, key);
    await cacheInvalidate(registry, cacheKey);

    // Phase 4: AttestationLog write audit
    await logAttestation(registry, 'store', id, { key, namespace, hasEmbedding: !!embeddingJson });

    return {
      success: true,
      id,
      embedding: embeddingJson ? { dimensions, model } : undefined,
      rawEmbedding: embeddingArr ?? undefined,
      guarded: true,
      cached: true,
      attested: true,
      ...(persistWarning ? { persistWarning } : {}),
      ...(embeddingError ? { embeddingError } : {}),
    };
  } catch (err) {
    // #2775: distinguish a data-level UNIQUE constraint violation (key
    // already exists — expected outcome of a strict insert) from a real
    // bridge failure (registry gone, DB locked, disk full, etc.). The
    // ON CONFLICT clause on the strict-insert SQL above should normally
    // convert UNIQUE hits into a `changes === 0` result, so reaching here
    // with a UNIQUE error means the schema pre-dates the (namespace, key)
    // unique index or the conflict target didn't match — treat it as a
    // clean "already exists" so the caller never demotes to sql.js and
    // never triggers the #2735 whole-image guard with a misleading
    // "active native WAL connection" error.
    const msg = err instanceof Error ? err.message : String(err);
    if (/UNIQUE constraint failed/i.test(msg)) {
      return {
        success: false,
        id: '',
        error: `key "${options.key}" already exists in namespace "${options.namespace ?? 'default'}" — pass upsert=true (--upsert on the CLI) to update it`,
      };
    }
    // Returning null below demotes the caller to the sql.js whole-image path,
    // whose WAL-sidecar guard then reports a cause that has nothing to do with
    // what actually went wrong here. Record the real error so it can be
    // surfaced alongside that guard's message.
    bridgeFailureReasons.set(canonicalDbPath(options.dbPath), msg);
    return null;
  }
}

/**
 * Search entries via AgentDB v3.
 * Phase 2: BM25 hybrid scoring replaces naive String.includes() keyword fallback.
 * Combines cosine similarity (semantic) with BM25 (lexical) via reciprocal rank fusion.
 */
/**
 * #4397: how many of the newest rows the pre-rank SELECT hands to scoring.
 * #2982 added ORDER BY updated_at DESC but kept LIMIT 1000, so rows outside
 * the newest 1000 became unfindable (the sql.js path and 3.38.3 used 10000).
 * Override with CLAUDE_FLOW_SEARCH_WINDOW (clamped to 100..100000).
 */
export const DEFAULT_BRIDGE_SEARCH_WINDOW = 10000;
export function resolveBridgeSearchWindow(env: NodeJS.ProcessEnv = process.env): number {
  const n = Number.parseInt(env.CLAUDE_FLOW_SEARCH_WINDOW ?? "", 10);
  if (!Number.isFinite(n)) return DEFAULT_BRIDGE_SEARCH_WINDOW;
  return Math.min(100000, Math.max(100, n));
}

export async function bridgeSearchEntries(options: {
  query: string;
  namespace?: string;
  limit?: number;
  threshold?: number;
  dbPath?: string;
  /** ADR-323: restrict results to these provenance types. */
  provenanceFilter?: string[];
}): Promise<{
  success: boolean;
  results: {
    id: string;
    key: string;
    content: string;
    score: number;
    namespace: string;
    provenance?: string;
    /** ADR-323 — NOT the same as `provenance` above (that's the
     *  ExplainableRecall score breakdown). This is the entry's
     *  user_claim/agent_output/... provenance type. */
    provenanceType?: string;
  }[];
  searchTime: number;
  searchMethod?: string;
  error?: string;
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeSearchEntries(options));
  if (options.provenanceFilter?.length) {
    const invalid = options.provenanceFilter.filter(p => !isValidProvenanceType(p));
    if (invalid.length > 0) return null; // caller (searchEntries) demotes to sql.js, which returns a typed error
  }

  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;

  const ctx = getDb(registry);
  if (!ctx) return null;

  try {
    const { query: queryStr, namespace, limit = 10, threshold = DEFAULT_SEARCH_THRESHOLD, provenanceFilter } = options;
    const effectiveNamespace = namespace || 'all';
    const startTime = Date.now();

    // Generate query embedding — same agentdb-then-local chain as the write
    // path (#3325), so rows embedded by the local fallback are searchable.
    // No vector → keyword (BM25) search only.
    const queryEmbedding: number[] | null = (await embedForBridge(ctx.agentdb, queryStr)).vector;

    // better-sqlite3: .prepare().all() returns array of objects
    // ADR-323: compose namespace + provenance filters into one WHERE clause.
    const filters: string[] = [];
    const filterParams: string[] = [];
    if (effectiveNamespace !== 'all') {
      filters.push('namespace = ?');
      filterParams.push(effectiveNamespace);
    }
    if (provenanceFilter?.length) {
      filters.push(`provenance_type IN (${provenanceFilter.map(() => '?').join(',')})`);
      filterParams.push(...provenanceFilter);
    }
    const whereExtra = filters.length > 0 ? `AND ${filters.join(' AND ')}` : '';

    let rows: any[];
    try {
      // #2982/#2976: this pre-rank SELECT truncates the corpus to 1000 rows
      // before BM25/embedding scoring runs. Without ORDER BY, SQLite returns
      // rows in arbitrary storage order (effectively oldest-inserted-first at
      // scale), so on any corpus over 1000 entries the newest — and often
      // most relevant — rows never reach scoring at all. bridgeListEntries()
      // already orders by updated_at DESC for the same reason; mirror it here.
      const stmt = ctx.db.prepare(`
        SELECT id, key, namespace, content, embedding, provenance_type
        FROM memory_entries
        WHERE ${liveMemoryRowSql()} ${whereExtra}
        ORDER BY updated_at DESC
        LIMIT ${resolveBridgeSearchWindow()}
      `);
      rows = filterParams.length > 0 ? stmt.all(...filterParams) : stmt.all();
    } catch {
      return null;
    }

    // Phase 2: Compute BM25 term stats for the corpus. Tokenize the corpus a
    // single time and reuse the per-doc `{contentLower, words}` for term-freq,
    // BM25 scoring, and the coverage floor below.
    const queryTerms = queryStr.toLowerCase().split(/\s+/).filter(t => t.length > 1);
    const docs = tokenizeCorpus(rows);
    const { termDocFreqs, avgDocLength } = computeTermDocFreqs(queryTerms, docs);
    const docCount = rows.length;

    const results: { id: string; key: string; content: string; score: number; namespace: string; provenance?: string; provenanceType?: string }[] = [];

    for (let i = 0; i < rows.length; i++) {
      const row = rows[i];
      const doc = docs[i];
      let semanticScore = 0;
      let bm25ScoreVal = 0;

      // Semantic scoring via cosine similarity
      if (queryEmbedding && row.embedding) {
        try {
          const embedding = JSON.parse(row.embedding) as number[];
          semanticScore = cosineSim(queryEmbedding, embedding);
        } catch {
          // Invalid embedding
        }
      }

      // Phase 2: BM25 keyword scoring (replaces String.includes fallback)
      if (queryTerms.length > 0 && row.content) {
        bm25ScoreVal = bm25Score(queryTerms, doc.words, doc.words.length, avgDocLength, docCount, termDocFreqs);
        // Normalize BM25 to 0-1 range (cap at 10 for normalization)
        bm25ScoreVal = Math.min(bm25ScoreVal / 10, 1.0);
      }

      // #2558: keyword-coverage floor for the lexical signal.
      // BM25's IDF collapses toward zero when a term appears in most/all
      // documents (routine on small memory corpora), and the /10 normalization
      // crushed exact-keyword hits well below the default 0.3 threshold — so
      // `memory search` recalled NOTHING even when the content literally
      // contained the query term (issue #2558: "keyword recall random"). The
      // pre-BM25 fallback guaranteed keyword recall via matchCount/words*0.5;
      // this restores that guarantee. `coverage` is the fraction of query
      // terms present in the document — a full-coverage hit must always be
      // recallable regardless of IDF.
      const contentLower = doc.contentLower;
      const matchedTerms = queryTerms.filter(t => contentLower.includes(t)).length;
      const coverage = queryTerms.length > 0 ? matchedTerms / queryTerms.length : 0;
      const lexicalScore = Math.max(bm25ScoreVal, coverage);

      // Recall-friendly fusion: a strong semantic OR lexical signal alone must
      // clear the threshold. `blended` (0.6 semantic + 0.4 lexical) drives
      // ranking; taking max() with the raw semantic score means (a) a genuinely
      // similar entry is never dropped just because it lacks the query's exact
      // words, and (b) a full-coverage keyword hit (lexical=1 → blended≥0.4) is
      // never dropped just because its embedding cosine is low or negative.
      const blended = 0.6 * Math.max(0, semanticScore) + 0.4 * lexicalScore;
      const score = Math.max(blended, semanticScore);

      if (score >= threshold) {
        // Phase 4: ExplainableRecall provenance
        const provenance = queryEmbedding
          ? `semantic:${semanticScore.toFixed(3)}+lexical:${lexicalScore.toFixed(3)}`
          : `lexical:${lexicalScore.toFixed(3)}`;

        results.push({
          id: String(row.id).substring(0, 12),
          key: row.key || String(row.id).substring(0, 15),
          content: (row.content || '').substring(0, 60) + ((row.content || '').length > 60 ? '...' : ''),
          score,
          namespace: row.namespace || 'default',
          provenance,
          provenanceType: row.provenance_type || 'unknown',
        });
      }
    }

    results.sort((a, b) => b.score - a.score);

    return {
      success: true,
      results: results.slice(0, limit),
      searchTime: Date.now() - startTime,
      searchMethod: queryEmbedding ? 'hybrid-bm25-semantic' : 'bm25-only',
    };
  } catch {
    return null;
  }
}

/**
 * List entries via AgentDB v3.
 */
export async function bridgeListEntries(options: {
  namespace?: string;
  limit?: number;
  offset?: number;
  dbPath?: string;
  /** #2073: When true, include the entry's full `content` string in each result. */
  includeContent?: boolean;
  /** ADR-323: restrict rows to these provenance types. */
  provenanceFilter?: string[];
  /** ADR-472: include each entry's embedding as int8+scale (`embeddingQ8`); at most MAX_LIST_EMBEDDINGS rows. */
  includeEmbedding?: boolean;
  /** #4056: also return rows whose TTL has passed (with `expiresAt`). For cleanup only. */
  includeExpired?: boolean;
  /** Require entries to include all of these tags (AND). */
  tags?: string[];
}): Promise<{
  success: boolean;
  entries: {
    id: string;
    key: string;
    namespace: string;
    size: number;
    accessCount: number;
    createdAt: string;
    updatedAt: string;
    /** #4056: epoch ms the row expires at; null when it never does. */
    expiresAt?: number | null;
    hasEmbedding: boolean;
    /** #2073: Present when `includeContent: true` was requested. */
    content?: string;
    provenanceType?: string;
    embeddingQ8?: { dims: number; scale: number; b64: string };
    /** Tag set stored with the entry (empty array when none). */
    tags?: string[];
  }[];
  total: number;
  error?: string;
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeListEntries(options));
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;

  const ctx = getDb(registry);
  if (!ctx) return null;

  try {
    const { namespace, limit = 20, offset = 0, provenanceFilter, tags: requiredTags } = options;
    if (provenanceFilter?.some(p => !isValidProvenanceType(p))) return null;

    const filters: string[] = [];
    const filterParams: string[] = [];
    if (namespace) {
      filters.push('namespace = ?');
      filterParams.push(namespace);
    }
    if (provenanceFilter?.length) {
      filters.push(`provenance_type IN (${provenanceFilter.map(() => '?').join(',')})`);
      filterParams.push(...provenanceFilter);
    }
    // Tags are stored as JSON-array TEXT (e.g. `["a","b"]`). Match each
    // required tag as an exact element via SQLite's json_each so the filter
    // runs in SQL instead of pulling the whole table into memory to filter
    // there. A LIKE-based substring match is ASCII case-insensitive (so
    // `prod` would match `PROD`) and matches raw JSON bytes rather than
    // parsed array elements (so a tag literally containing `"prod` could
    // false-match) — json_each compares real, decoded array values.
    const tagFilter = Array.isArray(requiredTags)
      ? requiredTags.filter((t): t is string => typeof t === 'string' && t.length > 0)
      : [];
    for (const tag of tagFilter) {
      filters.push(`EXISTS (SELECT 1 FROM json_each(tags) WHERE value = ?)`);
      filterParams.push(tag);
    }
    const extraFilter = filters.length > 0 ? `AND ${filters.join(' AND ')}` : '';

    // #2120 — `status IS NULL` accepted alongside `'active'`. Old
    // databases imported by the auto-memory bridge (before the status
    // column existed) end up with NULL status after schema migration if
    // the migration ran on an existing DB without a backfill. Reporter
    // @alexandrelealbess on WSL2 had 251 entries with NULL status, so
    // the `status = 'active'` filter matched zero. Treat NULL as
    // "legacy-active" — the safe default for any entry that predates the
    // status column.
    const statusFilter = liveMemoryRowSql({ includeExpired: options.includeExpired });

    // `|| 20` would treat an explicit `limit: 0` as falsy and silently
    // substitute the default (returning 20 rows instead of the requested
    // zero) — only fall back to the default when parsing genuinely failed.
    const parsedLimit = parseInt(String(limit), 10);
    const safeLimit = Number.isNaN(parsedLimit) ? 20 : parsedLimit;
    const parsedOffset = parseInt(String(offset), 10);
    const safeOffset = Number.isNaN(parsedOffset) ? 0 : parsedOffset;

    // Count
    let total = 0;
    try {
      const countStmt = ctx.db.prepare(
        `SELECT COUNT(*) as cnt FROM memory_entries WHERE ${statusFilter} ${extraFilter}`
      );
      const countRow = countStmt.get(...filterParams);
      total = countRow?.cnt ?? 0;
    } catch {
      return null;
    }

    // List
    const entries: any[] = [];
    try {
      // Include tags so export/list can round-trip them.
      const stmt = ctx.db.prepare(`
        SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, provenance_type, expires_at, tags
        FROM memory_entries
        WHERE ${statusFilter} ${extraFilter}
        ORDER BY updated_at DESC
        LIMIT ? OFFSET ?
      `);
      const rows = stmt.all(...filterParams, options.includeEmbedding ? Math.min(safeLimit, MAX_LIST_EMBEDDINGS) : safeLimit, safeOffset);
      for (const row of rows) {
        let tags: string[] = [];
        if (row.tags) {
          try {
            const parsed = typeof row.tags === 'string' ? JSON.parse(row.tags) : row.tags;
            if (Array.isArray(parsed)) {
              tags = parsed.filter((t: unknown): t is string => typeof t === 'string');
            }
          } catch { /* invalid tags JSON */ }
        }
        const entry: Record<string, unknown> = {
          // #2073: don't truncate id when content is requested — callers
          // (notably memory_export) need the full id to round-trip via import.
          id: options.includeContent ? String(row.id) : String(row.id).substring(0, 20),
          key: row.key || String(row.id).substring(0, 15),
          namespace: row.namespace || 'default',
          size: (row.content || '').length,
          accessCount: row.access_count ?? 0,
          createdAt: row.created_at || new Date().toISOString(),
          updatedAt: row.updated_at || new Date().toISOString(),
          expiresAt: row.expires_at ?? null,
          hasEmbedding: !!(row.embedding && String(row.embedding).length > 10),
          provenanceType: row.provenance_type || 'unknown',
          tags,
        };
        if (options.includeContent) {
          entry.content = row.content || '';
        }
        if (options.includeEmbedding) {
          const q8 = encodeEmbeddingQ8(row.embedding);
          if (q8) entry.embeddingQ8 = q8;
        }
        entries.push(entry);
      }
    } catch {
      return null;
    }

    return { success: true, entries, total };
  } catch {
    return null;
  }
}

/**
 * Get a specific entry via AgentDB v3.
 * Phase 2: TieredCache consulted before DB hit.
 */
export async function bridgeGetEntry(options: {
  key: string;
  namespace?: string;
  dbPath?: string;
}): Promise<{
  success: boolean;
  found: boolean;
  entry?: {
    id: string;
    key: string;
    namespace: string;
    content: string;
    accessCount: number;
    createdAt: string;
    updatedAt: string;
    hasEmbedding: boolean;
    tags: string[];
  };
  cacheHit?: boolean;
  error?: string;
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeGetEntry(options));
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;

  const ctx = getDb(registry);
  if (!ctx) return null;

  try {
    const { key, namespace = 'default' } = options;

    // Phase 2: Check TieredCache first
    const cacheKey = entryCacheKey(namespace, key);
    dropCacheIfDbChangedElsewhere(registry, ctx);
    const cached = await cacheGet(registry, cacheKey);
    if (cached && cached.content && (cached.expiresAt == null || cached.expiresAt > Date.now())) {
      return {
        success: true,
        found: true,
        cacheHit: true,
        entry: {
          id: String(cached.id || ''),
          key: cached.key || key,
          namespace: cached.namespace || namespace,
          content: cached.content || '',
          accessCount: cached.accessCount ?? 0,
          createdAt: cached.createdAt || new Date().toISOString(),
          updatedAt: cached.updatedAt || new Date().toISOString(),
          // #3325: the cache holds the `entry` object built below, which has
          // `hasEmbedding` but no `embedding` field — so `!!cached.embedding`
          // reported false on every cache hit, even for embedded rows.
          hasEmbedding: typeof cached.hasEmbedding === 'boolean' ? cached.hasEmbedding : !!cached.embedding,
          tags: cached.tags || [],
        },
      };
    }

    let row: any;
    try {
      const stmt = ctx.db.prepare(`
        SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, tags, expires_at
        FROM memory_entries
        WHERE ${liveMemoryRowSql()} AND key = ? AND namespace = ?
        LIMIT 1
      `);
      row = stmt.get(key, namespace);
    } catch {
      return null;
    }

    if (!row) {
      return { success: true, found: false };
    }

    // Update access count
    try {
      ctx.db.prepare(
        `UPDATE memory_entries SET access_count = access_count + 1, last_accessed_at = ? WHERE id = ?`
      ).run(Date.now(), row.id);
    } catch {
      // Non-fatal
    }

    let tags: string[] = [];
    if (row.tags) {
      try { tags = JSON.parse(row.tags); } catch { /* invalid */ }
    }

    const entry = {
      id: String(row.id),
      key: row.key || String(row.id),
      namespace: row.namespace || 'default',
      content: row.content || '',
      accessCount: (row.access_count ?? 0) + 1,
      createdAt: row.created_at || new Date().toISOString(),
      updatedAt: row.updated_at || new Date().toISOString(),
      hasEmbedding: !!(row.embedding && String(row.embedding).length > 10),
      tags,
    };

    // Phase 2: Populate cache for next read
    await cacheSet(registry, cacheKey, { ...entry, expiresAt: row.expires_at });

    return { success: true, found: true, cacheHit: false, entry };
  } catch {
    return null;
  }
}

/**
 * Delete an entry via AgentDB v3.
 * Phase 5: MutationGuard validation, cache invalidation, attestation logging.
 */
export async function bridgeDeleteEntry(options: {
  key: string;
  namespace?: string;
  dbPath?: string;
}): Promise<{
  success: boolean;
  deleted: boolean;
  key: string;
  namespace: string;
  remainingEntries: number;
  guarded?: boolean;
  error?: string;
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeDeleteEntry(options));
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;

  const ctx = getDb(registry);
  if (!ctx) return null;

  try {
    const { key, namespace = 'default' } = options;

    // Phase 5: MutationGuard validation before delete
    const guardResult = await guardValidate(registry, 'delete', { key, namespace });
    if (!guardResult.allowed) {
      return { success: false, deleted: false, key, namespace, remainingEntries: 0, error: `MutationGuard rejected: ${guardResult.reason}` };
    }

    // #3785: secure_delete zeroes the old cells while the payload columns are
    // scrubbed; otherwise SQLite can leave the deleted text in free pages.
    try {
      ctx.db.pragma('secure_delete = ON');
    } catch { /* non-fatal: the logical scrub below still hides the row */ }

    // Soft delete using parameterized query. The tombstone must keep only
    // what later upserts/audits need: the payload columns are scrubbed here,
    // not merely hidden by the status filter. `content` is NOT NULL in the
    // schema, so "scrubbed" is the empty string rather than SQL NULL; that
    // still removes the deleted value from disk and from any raw SQLite read.
    let changes = 0;
    try {
      const result = ctx.db.prepare(`
        UPDATE memory_entries
        SET status = 'deleted',
            content = '',
            embedding = NULL,
            embedding_model = NULL,
            embedding_dimensions = NULL,
            tags = NULL,
            metadata = NULL,
            updated_at = ?
        WHERE key = ? AND namespace = ? AND ${ACTIVE_MEMORY_ROW_SQL}
      `).run(Date.now(), key, namespace);
      changes = result?.changes ?? 0;
    } catch {
      return null;
    }

    // #2775: mirror the #2558 PASSIVE checkpoint after the delete. Without
    // this, the tombstone stays WAL-only until some unrelated store
    // eventually checkpoints — meaning WAL-blind readers (sql.js fallback,
    // statusline's read-only sqlite3 counter) keep serving the deleted row.
    // If the process exits before another checkpoint, on live multi-worktree
    // installations we've observed rows `active` in the main image but
    // `deleted` in the -wal, or rows existing only in an orphaned -wal
    // invisible to every image reader. PASSIVE flushes committed pages
    // without blocking writers. Best-effort, never fatal.
    try {
      if (typeof ctx.db.pragma === 'function') {
        ctx.db.pragma('wal_checkpoint(PASSIVE)');
      }
    } catch { /* non-WAL, busy, or unsupported — non-fatal */ }

    // Phase 2: Invalidate cache
    await cacheInvalidate(registry, entryCacheKey(namespace, key));

    // Phase 4: AttestationLog delete audit
    if (changes > 0) {
      await logAttestation(registry, 'delete', key, { namespace });
    }

    let remaining = 0;
    try {
      const row = ctx.db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE ${ACTIVE_MEMORY_ROW_SQL}`).get();
      remaining = row?.cnt ?? 0;
    } catch {
      // Non-fatal
    }

    return {
      success: true,
      deleted: changes > 0,
      key,
      namespace,
      remainingEntries: remaining,
      guarded: true,
    };
  } catch {
    return null;
  }
}

// #2666 — Hard, namespace-scoped purge. bridgeDeleteEntry above only ever
// soft-deletes a single (namespace, key); this is a real
// `DELETE FROM memory_entries WHERE namespace = ?` against the live
// better-sqlite3-style handle, for callers (e.g. a plugin's index-reconcile
// step) that need a namespace to be genuinely empty rather than tombstoned.
// Irreversible — callers must gate this behind an explicit confirmation.
export async function bridgePurgeNamespace(options: {
  namespace: string;
  dbPath?: string;
}): Promise<{
  success: boolean;
  deletedCount: number;
  remainingEntries: number;
  guarded?: boolean;
  error?: string;
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgePurgeNamespace(options));
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;

  const ctx = getDb(registry);
  if (!ctx) return null;

  try {
    const { namespace } = options;

    const guardResult = await guardValidate(registry, 'purge', { namespace });
    if (!guardResult.allowed) {
      return { success: false, deletedCount: 0, remainingEntries: 0, error: `MutationGuard rejected: ${guardResult.reason}` };
    }

    let deletedCount = 0;
    try {
      // #3785: a hard DELETE without secure_delete leaves the purged payload
      // in free pages; purge claims to be irreversible.
      try {
        ctx.db.pragma('secure_delete = ON');
      } catch { /* non-fatal: the rows are still removed below */ }
      const result = ctx.db.prepare(`DELETE FROM memory_entries WHERE namespace = ?`).run(namespace);
      deletedCount = result?.changes ?? 0;
    } catch (e) {
      return { success: false, deletedCount: 0, remainingEntries: 0, error: e instanceof Error ? e.message : String(e) };
    }

    // Entries are cached individually, not under a namespace sentinel.
    // SQLite data_version does not change for writes on this connection, so
    // the cross-process freshness check cannot invalidate this purge for us.
    try {
      const cache = registry.get('tieredCache');
      if (cache && typeof cache.clear === 'function') await cache.clear();
    } catch { /* cache cleanup is best-effort */ }

    if (deletedCount > 0) {
      await logAttestation(registry, 'purge', namespace, { namespace, deletedCount });
    }

    let remaining = 0;
    try {
      const row = ctx.db.prepare(`SELECT COUNT(*) as cnt FROM memory_entries WHERE status = 'active'`).get();
      remaining = row?.cnt ?? 0;
    } catch {
      // Non-fatal
    }

    return {
      success: true,
      deletedCount,
      remainingEntries: remaining,
      guarded: true,
    };
  } catch {
    return null;
  }
}

// ===== Phase 2: Embedding bridge =====

/**
 * Generate embedding via AgentDB v3's embedder.
 * Returns null if bridge unavailable — caller falls back to own ONNX/hash.
 */
export async function bridgeGenerateEmbedding(
  text: string,
  dbPath?: string,
): Promise<{ embedding: number[]; dimensions: number; model: string; backend?: 'onnx' | 'mock' } | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeGenerateEmbedding(text, dbPath));
  const registry = await getRegistry(dbPath);
  if (!registry) return null;

  try {
    const agentdb = registry.getAgentDB();
    const embedder = agentdb?.embedder;
    if (!embedder || isMockAgentdbEmbedder(embedder)) return null;

    const emb = await embedder.embed(text);
    if (!emb) return null;

    // AUDIT #3: surface backend truthfully. AgentDB's embedder is a real ONNX
    // model when present; if it ever exposes a mock/stub signal, honor it.
    const isMock = (embedder as { isMock?: boolean; backend?: string }).isMock === true
      || (embedder as { backend?: string }).backend === 'mock';

    // #2395 — AgentDB's vectorBackend controller may initialize as
    // `enabled: false` (e.g., ruvector isn't wired into its neural substrate
    // yet) and silently fall back to a 128-dim hash stub. The embedder doesn't
    // expose isMock=true in that path, so the wrapper above was reporting
    // backend='onnx' on what's actually 128-dim hash garbage. The model name
    // we hardcode ('Xenova/all-MiniLM-L6-v2') always produces 384-dim, so a
    // dimensions mismatch is a definitive stub signal: return null and let
    // the caller fall through to generateLocalEmbedding which routes to
    // transformers.js / ruvector ONNX directly.
    if (emb.length !== 384) {
      return null;
    }

    return {
      embedding: Array.from(emb),
      dimensions: emb.length,
      model: 'Xenova/all-MiniLM-L6-v2',
      backend: isMock ? 'mock' : 'onnx',
    };
  } catch {
    return null;
  }
}

/**
 * Load embedding model via AgentDB v3 (it loads on init).
 * Returns null if unavailable.
 */
export async function bridgeLoadEmbeddingModel(
  dbPath?: string,
): Promise<{
  success: boolean;
  dimensions: number;
  modelName: string;
  loadTime?: number;
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeLoadEmbeddingModel(dbPath));
  const startTime = Date.now();
  const registry = await getRegistry(dbPath);
  if (!registry) return null;

  try {
    const agentdb = registry.getAgentDB();
    const embedder = agentdb?.embedder;
    if (!embedder || isMockAgentdbEmbedder(embedder)) return null;

    // Verify embedder works by generating a test embedding
    const test = await embedder.embed('test');
    if (!test) return null;

    return {
      success: true,
      dimensions: test.length,
      modelName: 'Xenova/all-MiniLM-L6-v2',
      loadTime: Date.now() - startTime,
    };
  } catch {
    return null;
  }
}

// ===== Phase 3: HNSW bridge =====

/**
 * Get vector search status from AgentDB v3's SQLite-backed store.
 * Returns null if unavailable.
 *
 * #2922: previously named `bridgeGetHNSWStatus` and unconditionally returned
 * `available: true` whenever a DB connection succeeded — but the search this
 * status describes (`bridgeSearchBruteForceCosine`, below) is a full-table
 * SELECT + brute-force cosine scan, not an HNSW index lookup. Renamed and
 * given an explicit `algorithm` field so callers can't mistake "vector
 * search works" for "vector search is HNSW-accelerated".
 */
export async function bridgeGetVectorSearchStatus(
  dbPath?: string,
): Promise<{
  available: boolean;
  initialized: boolean;
  entryCount: number;
  dimensions: number;
  algorithm: 'brute-force-cosine';
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeGetVectorSearchStatus(dbPath));
  const registry = await getRegistry(dbPath);
  if (!registry) return null;

  try {
    const ctx = getDb(registry);
    if (!ctx) return null;

    // Count entries with embeddings
    let entryCount = 0;
    try {
      const row = ctx.db.prepare(
        `SELECT COUNT(*) as cnt FROM memory_entries WHERE status = 'active' AND embedding IS NOT NULL`,
      ).get();
      entryCount = row?.cnt ?? 0;
    } catch {
      // Table might not exist
    }

    return {
      available: true,
      initialized: true,
      entryCount,
      dimensions: 384,
      algorithm: 'brute-force-cosine',
    };
  } catch {
    return null;
  }
}

/**
 * #4203: RaBitQ pre-filter for the bridge's vector search.
 *
 * The index yields candidate ids from a 32×-compressed Hamming scan; each is
 * reranked here with the same exact cosine similarity the exhaustive scan uses,
 * so scores keep their meaning and only the scanned set shrinks (the candidate
 * window `k * 2` is then widened 3× by `searchRabitq` itself).
 *
 * Returns null whenever the index cannot answer this query — WASM missing, too
 * few vectors, or an index built for another store/dimension — so the caller
 * runs its unchanged brute-force scan. Keyword/BM25 recall is unaffected: this
 * only ever replaces the cosine scan.
 */
async function rabitqSearchAndRerank(
  db: any,
  queryEmbedding: number[],
  options: { k: number; threshold: number; namespace?: string; dbPath?: string },
): Promise<Array<{ id: string; key: string; content: string; score: number; namespace: string }> | null> {
  try {
    const { ensureRabitqIndex, searchRabitq } = await import('./rabitq-index.js');

    const ready = await ensureRabitqIndex({ dbPath: options.dbPath, dimensions: queryEmbedding.length });
    if (!ready) return null;

    const candidates = await searchRabitq(queryEmbedding, {
      k: options.k * 2,
      namespace: options.namespace,
    });
    if (!candidates || candidates.length === 0) return null;

    // Fetch exactly the candidates (id is the primary key) instead of the
    // 10k-row full scan; chunked to stay well inside SQLite's parameter limit.
    const rowsById = new Map<string, { key: string; namespace: string; content: string; score: number }>();
    const ids = candidates.map(c => c.id);
    for (let i = 0; i < ids.length; i += 500) {
      const chunk = ids.slice(i, i + 500);
      const placeholders = chunk.map(() => '?').join(',');
      const rows: any[] = db.prepare(`
        SELECT id, key, namespace, content, embedding
        FROM memory_entries
        WHERE id IN (${placeholders}) AND ${liveMemoryRowSql()} AND embedding IS NOT NULL
      `).all(...chunk);

      for (const row of rows) {
        let embedding: number[];
        try {
          embedding = JSON.parse(row.embedding) as number[];
        } catch {
          continue;
        }
        if (!Array.isArray(embedding) || embedding.length !== queryEmbedding.length) continue;
        rowsById.set(String(row.id), {
          key: row.key || String(row.id),
          namespace: row.namespace || 'default',
          content: row.content || '',
          score: cosineSim(queryEmbedding, embedding),
        });
      }
    }

    const results: Array<{ id: string; key: string; content: string; score: number; namespace: string }> = [];
    for (const candidate of candidates) {
      const row = rowsById.get(candidate.id);
      if (!row || row.score < options.threshold) continue;
      results.push({
        id: candidate.id.substring(0, 12),
        key: row.key || candidate.id.substring(0, 15),
        content: row.content.substring(0, 60) + (row.content.length > 60 ? '...' : ''),
        score: row.score,
        namespace: row.namespace,
      });
    }

    if (results.length === 0) return null;
    results.sort((a, b) => b.score - a.score);
    return results.slice(0, options.k);
  } catch {
    return null;
  }
}

/**
 * Search AgentDB v3's embedder + SQLite entries via a full-table scan and
 * brute-force cosine similarity. NOT HNSW-accelerated — see #2922. Returns
 * null if unavailable.
 *
 * #4203: when a RaBitQ index is available the Hamming-scan candidate set is
 * reranked exactly instead of scanning the whole table; the exhaustive loop
 * below stays the fallback, so results and scores keep their meaning.
 */
export async function bridgeSearchBruteForceCosine(
  queryEmbedding: number[],
  options?: { k?: number; namespace?: string; threshold?: number },
  dbPath?: string,
): Promise<Array<{
  id: string;
  key: string;
  content: string;
  score: number;
  namespace: string;
}> | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeSearchBruteForceCosine(queryEmbedding, options, dbPath));
  const registry = await getRegistry(dbPath);
  if (!registry) return null;

  const ctx = getDb(registry);
  if (!ctx) return null;

  try {
    const k = options?.k ?? 10;
    const threshold = options?.threshold ?? DEFAULT_SEARCH_THRESHOLD;
    const nsFilter = options?.namespace && options.namespace !== 'all'
      ? `AND namespace = ?`
      : '';

    // #4203: try the RaBitQ pre-filter before the exhaustive scan below. A null
    // result (no index / unavailable / nothing above threshold) falls through
    // to the unchanged brute-force path.
    const accelerated = await rabitqSearchAndRerank(ctx.db, queryEmbedding, {
      k,
      threshold,
      namespace: options?.namespace,
      dbPath,
    });
    if (accelerated) return accelerated;

    let rows: any[];
    try {
      // #2982/#2976: same unordered pre-rank truncation as bridgeSearchEntries
      // above — without ORDER BY, a corpus over 10000 rows silently drops
      // its newest entries before cosine scoring ever runs.
      const stmt = ctx.db.prepare(`
        SELECT id, key, namespace, content, embedding
        FROM memory_entries
        WHERE ${liveMemoryRowSql()} AND embedding IS NOT NULL ${nsFilter}
        ORDER BY updated_at DESC
        LIMIT 10000
      `);
      rows = nsFilter
        ? stmt.all(options!.namespace)
        : stmt.all();
    } catch {
      return null;
    }

    const results: Array<{
      id: string; key: string; content: string; score: number; namespace: string;
    }> = [];

    for (const row of rows) {
      if (!row.embedding) continue;
      try {
        const emb = JSON.parse(row.embedding) as number[];
        const score = cosineSim(queryEmbedding, emb);
        if (score >= threshold) {
          results.push({
            id: String(row.id).substring(0, 12),
            key: row.key || String(row.id).substring(0, 15),
            content: (row.content || '').substring(0, 60) +
              ((row.content || '').length > 60 ? '...' : ''),
            score,
            namespace: row.namespace || 'default',
          });
        }
      } catch {
        // Skip invalid embeddings
      }
    }

    results.sort((a, b) => b.score - a.score);
    return results.slice(0, k);
  } catch {
    return null;
  }
}

/**
 * Add entry to the bridge's database with embedding. No HNSW index is built
 * or updated here — see #2922; the embedding is only stored for a later
 * brute-force scan. Returns null if unavailable.
 */
export async function bridgeAddEmbedding(
  id: string,
  embedding: number[],
  entry: { id: string; key: string; namespace: string; content: string },
  dbPath?: string,
): Promise<boolean | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeAddEmbedding(id, embedding, entry, dbPath));
  const registry = await getRegistry(dbPath);
  if (!registry) return null;

  const ctx = getDb(registry);
  if (!ctx) return null;

  try {
    const now = Date.now();
    const embeddingJson = JSON.stringify(embedding);
    // Do not use INSERT OR REPLACE here. storeEntry() has already written the
    // authoritative row, including provenance/tags/metadata; REPLACE deleted
    // that row and recreated it without provenance_type, silently resetting
    // every typed CLI/MCP write to "unknown".
    ctx.db.prepare(`
      INSERT INTO memory_entries (
        id, key, namespace, content, type,
        embedding, embedding_dimensions, embedding_model,
        created_at, updated_at, status
      ) VALUES (?, ?, ?, ?, 'semantic', ?, ?, 'Xenova/all-MiniLM-L6-v2', ?, ?, 'active')
      ON CONFLICT(namespace, key) DO UPDATE SET
        id                   = excluded.id,
        content              = excluded.content,
        type                 = excluded.type,
        embedding            = excluded.embedding,
        embedding_dimensions = excluded.embedding_dimensions,
        embedding_model      = excluded.embedding_model,
        updated_at           = excluded.updated_at,
        status               = 'active'
    `).run(
      id, entry.key, entry.namespace, entry.content,
      embeddingJson, embedding.length,
      now, now,
    );
    return true;
  } catch {
    return null;
  }
}

// ===== Phase 4: Controller access =====

/**
 * Get a named controller from AgentDB v3 via ControllerRegistry.
 * This borrowed handle must not be retained across shutdownBridge().
 * Returns null if unavailable.
 */
export async function bridgeGetController(
  name: string,
  dbPath?: string,
): Promise<any | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeGetController(name, dbPath));
  const registry = await getRegistry(dbPath);
  if (!registry) return null;

  try {
    return registry.get(name) ?? null;
  } catch {
    return null;
  }
}

/**
 * Check if a controller is available.
 */
export async function bridgeHasController(
  name: string,
  dbPath?: string,
): Promise<boolean> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeHasController(name, dbPath));
  const registry = await getRegistry(dbPath);
  if (!registry) return false;

  try {
    const controller = registry.get(name);
    return controller !== null && controller !== undefined;
  } catch {
    return false;
  }
}

/**
 * List all controllers and their status.
 */
export async function bridgeListControllers(
  dbPath?: string,
): Promise<Array<{ name: string; enabled: boolean; level: number }> | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeListControllers(dbPath));
  const registry = await getRegistry(dbPath);
  if (!registry) return null;

  try {
    return registry.listControllers();
  } catch {
    return null;
  }
}

/**
 * Check if the AgentDB v3 bridge is available.
 */
export async function isBridgeAvailable(dbPath?: string): Promise<boolean> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => isBridgeAvailable(dbPath));
  const registry = await getRegistry(dbPath);
  return registry !== null;
}

/**
 * Get the ControllerRegistry instance (for advanced consumers).
 * This is a borrowed handle, valid only until shutdownBridge(). Callers must
 * finish using it before requesting shutdown; bridge operations own their own
 * leases. Prefer bridgeListControllers() for status inspection.
 */
export async function getControllerRegistry(dbPath?: string): Promise<any | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => getControllerRegistry(dbPath));
  return getRegistry(dbPath);
}

/**
 * Why the bridge last declined a write, or null when it has not.
 *
 * A bridge that initialised fine can still fail every write — a schema mismatch throws
 * per-operation while the registry stays healthy — and that case is exactly
 * the one worth reporting, since the caller then demotes to a fallback whose
 * error message describes something else entirely.
 *
 * Callers that surface a degraded-path error should include this so the
 * operator learns the cause instead of only the symptom.
 */
export function getBridgeFailureReason(dbPath?: string): string | null {
  if (shouldDisableNativeBridge()) {
    return process.platform === 'win32'
      ? 'AgentDB native bridge disabled on Windows after #3024; set CLAUDE_FLOW_ENABLE_NATIVE_BRIDGE_ON_WINDOWS=1 to opt in'
      : 'AgentDB native bridge disabled by CLAUDE_FLOW_DISABLE_BRIDGE=1';
  }
  return bridgeFailureReasons.get(canonicalDbPath(dbPath)) ?? null;
}

/**
 * Install a pre-initialized registry for deterministic bridge tests.
 *
 * The CLI test runner intentionally externalizes the optional
 * `@claude-flow/memory` package so an unbuilt workspace can still exercise
 * fallback paths. That also makes module-level mocking of ControllerRegistry
 * environment-dependent. This narrow seam keeps native SQL regression tests
 * independent of package build order without changing production startup.
 */
export function __setMemoryBridgeRegistryForTests(registry: any | null): void {
  registryPromises.clear();
  registryInstances.clear();
  testRegistryOverride = registry;
  testRegistryFactory = null;
  bridgeFailureReasons.clear();
}

/**
 * Shutdown the bridge and release resources.
 *
 * The cached state is cleared unconditionally. Previously the reset lived
 * inside `if (registryInstance)`, so it could not clear a FAILED init. This
 * also clears per-path failed promises, allowing a later retry.
 */
export function shutdownBridge(): Promise<void> {
  if (shutdownPromise) return shutdownPromise;
  // Publish the barrier before any await: no later operation can join the
  // retiring lifecycle. Concurrent callers share the same retirement promise.
  shutdownPromise = (async () => {
    if (activeOperations > 0) await new Promise<void>(resolve => { drained = resolve; });
    await Promise.allSettled([...registryPromises.values()]);
    // A failed PERSIST (AGENTDB_LOCK_UNRECOVERABLE: live lock or concurrent
    // writer on a sql.js database) means pending changes were not saved. That
    // is surfaced after cleanup completes; other close errors stay best-effort.
    let persistFailure: unknown;
    for (const registry of new Set(registryInstances.values())) {
      try { await registry.shutdown(); } catch (err) {
        if ((err as { code?: unknown } | null)?.code === 'AGENTDB_LOCK_UNRECOVERABLE') persistFailure ??= err;
      }
    }
    registryInstances.clear();
    registryPromises.clear();
    testRegistryOverride = null;
    bridgeFailureReasons.clear();
    if (persistFailure) throw persistFailure;
  })().finally(() => { shutdownPromise = null; });
  return shutdownPromise;
}

// ===== Phase 3: ReasoningBank pattern operations =====

/**
 * Store a pattern via ReasoningBank controller.
 * Falls back to raw SQL if ReasoningBank unavailable.
 */
export async function bridgeStorePattern(options: {
  pattern: string;
  type: string;
  confidence: number;
  metadata?: Record<string, unknown>;
  dbPath?: string;
}): Promise<{ success: boolean; patternId: string; controller: string; hasEmbedding?: boolean; embeddingError?: string; error?: string } | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeStorePattern(options));
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;

  try {
    const reasoningBank = registry.get('reasoningBank');
    const patternId = generateId('pattern');

    // #3327 Finding A — the real method is `storePattern`, and it takes a
    // ReasoningPattern, NOT the {id, content, type, confidence} shape used
    // here before. `reasoningBank.store` has never existed on agentdb's
    // ReasoningBank, so `typeof ... === 'function'` was always false and this
    // branch was dead code — every write fell through to bridge-fallback while
    // `agentdb_controllers` cheerfully reported `reasoningBank: enabled=true`.
    //
    // Contract (agentdb ReasoningBank.d.ts):
    //   storePattern({ taskType, approach, successRate, uses?, avgReward?,
    //                  tags?, metadata? }) => Promise<number>   // sqlite rowid
    // The embedded text is `${taskType}: ${approach}`, so the caller's pattern
    // text must land in `approach` for search to match on it.
    if (reasoningBank && typeof reasoningBank.storePattern === 'function') {
      const rowId = await reasoningBank.storePattern({
        taskType: options.type,
        approach: options.pattern,
        successRate: options.confidence,
        tags: [options.type, 'reasoning-pattern'],
        metadata: options.metadata,
      });
      // storePattern returns a numeric rowid; surface it as the caller-facing
      // id so a later getPattern/deletePattern by this id resolves.
      return {
        success: true,
        patternId: rowId != null ? String(rowId) : patternId,
        controller: 'reasoningBank',
      };
    }

    // The intelligence module's LocalReasoningBank (registered when agentdb's
    // own ReasoningBank is unavailable) has store()/findSimilar() but no
    // storePattern(). bridgeSearchPatterns reads it through findSimilar(), so
    // the write must land there too, with an embedding from the same
    // generateEmbedding() the search uses. Otherwise store and search split
    // across two backends and a stored pattern is never found.
    if (reasoningBank && typeof reasoningBank.store === 'function' && typeof reasoningBank.findSimilar === 'function') {
      let embedding: number[] = [];
      try {
        const { generateEmbedding } = await import('./memory-initializer.js');
        const emb = await generateEmbedding(options.pattern);
        if (emb && Array.isArray(emb.embedding)) embedding = emb.embedding;
      } catch { /* no embedder — findSimilar misses it, the getAll() substring scan still finds it */ }
      // store() returns false when it merges into an existing pattern with the
      // same content; that is still a successful write.
      reasoningBank.store({
        id: patternId,
        type: options.type,
        content: options.pattern,
        confidence: options.confidence,
        embedding,
        metadata: options.metadata,
      });
      // Saves are debounced; a short-lived CLI process can exit first.
      if (typeof reasoningBank.flushToDisk === 'function') reasoningBank.flushToDisk();
      return {
        success: true,
        patternId,
        controller: 'reasoningBank',
        hasEmbedding: embedding.length > 0,
      };
    }

    // Fallback: store via bridge SQL
    const patternValue = JSON.stringify({ pattern: options.pattern, type: options.type, confidence: options.confidence, metadata: options.metadata });
    const result = await bridgeStoreEntry({
      key: patternId,
      value: patternValue,
      namespace: 'pattern',
      generateEmbeddingFlag: true,
      tags: [options.type, 'reasoning-pattern'],
      dbPath: options.dbPath,
    });

    if (!result) return null;

    // #3691: bridgeStoreEntry reports data-level failures (MutationGuard
    // rejection, nothing written) as a truthy {success:false}. Do not turn
    // that into a success receipt — refuse at this boundary.
    if (!result.success) {
      return {
        success: false,
        patternId: '',
        controller: 'bridge-fallback',
        error: result.error ?? 'pattern write was not persisted',
      };
    }

    // Add to HNSW index for fast semantic search (bridgeStoreEntry stores SQL only)
    if (result.rawEmbedding) {
      try {
        const { addToHNSWIndex } = await import('./memory-initializer.js');
        await addToHNSWIndex(result.id, result.rawEmbedding, {
          id: result.id,
          key: patternId,
          namespace: 'pattern',
          content: patternValue,
        });
      } catch { /* HNSW is best-effort */ }
    }

    // #3324: bridgeStoreEntry's `result.id` is its OWN internally generated
    // row id (generateId('entry')), a different value from the `key` the row
    // was actually stored under. getEntry/memory_retrieve look up by `key`,
    // so returning result.id here handed the caller a handle that can never
    // be read back — return `patternId` (the real key) instead.
    // #3325: say whether the row got a vector. Without one, Tier-1 (semantic)
    // pattern search cannot find it — report that here, at write time.
    return {
      success: true,
      patternId,
      controller: 'bridge-fallback',
      hasEmbedding: !!result.embedding,
      ...(result.embeddingError ? { embeddingError: result.embeddingError } : {}),
    };
  } catch (err) {
    // #3327 Finding A — this catch is what hid the defect for months. When
    // ReasoningBank threw `embedPassage is not a function`, the error was
    // discarded and the caller saw an ordinary fallback, indistinguishable
    // from "no controller registered". Record it so `agentdb_health` and the
    // degraded `reason` can name the real cause instead of guessing.
    bridgeFailureReasons.set(canonicalDbPath(options.dbPath), err instanceof Error ? err.message : String(err));
    return null;
  }
}

/**
 * Search patterns via ReasoningBank controller.
 */
export async function bridgeSearchPatterns(options: {
  query: string;
  topK?: number;
  minConfidence?: number;
  dbPath?: string;
}): Promise<{ results: Array<{ id: string; content: string; score: number }>; controller: string } | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeSearchPatterns(options));
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;

  try {
    const reasoningBank = registry.get('reasoningBank');

    // ReasoningBank may expose .searchPatterns() (agentdb) or .search() (legacy) (#1492 Bug 2)
    if (reasoningBank && typeof (reasoningBank.searchPatterns ?? reasoningBank.search) === 'function') {
      let results: any;
      if (typeof reasoningBank.searchPatterns === 'function') {
        results = await reasoningBank.searchPatterns({ task: options.query, k: options.topK || 5, threshold: options.minConfidence || 0.3 });
      } else {
        results = await reasoningBank.search(options.query, { topK: options.topK || 5, minScore: options.minConfidence || 0.3 });
      }
      // #3327 Finding A — agentdb returns ReasoningPattern[]: the text lives in
      // `approach` and the cosine score in `similarity`. Neither `content`/
      // `pattern` nor `score`/`confidence` exists on that shape, so the old
      // mapping produced `content: ''` and `score: 0` for every hit even when
      // the search itself succeeded. Read the real fields first, keeping the
      // legacy names as fallbacks for the pre-agentdb shape.
      return {
        results: Array.isArray(results) ? results.map((r: any) => ({
          id: String(r.id ?? r.patternId ?? ''),
          content: r.approach ?? r.content ?? r.pattern ?? '',
          score: r.similarity ?? r.score ?? r.successRate ?? r.confidence ?? 0,
        })) : [],
        controller: 'reasoningBank',
      };
    }

    // #2226 — the wired-in LocalReasoningBank implements store() + findSimilar()/getAll()
    // but NOT searchPatterns()/search(). bridgeStorePattern commits patterns to its
    // store(), so search MUST read the SAME backend or stored patterns are never found
    // (previously search fell through to the disjoint sql.js 'pattern' namespace, which
    // the store never wrote to → always-empty results). Adapt findSimilar (semantic) with
    // a getAll() substring fallback so freshly-stored patterns are visible. This mirrors
    // what hooks_intelligence_pattern-search already does against the same backend.
    if (reasoningBank && typeof reasoningBank.findSimilar === 'function') {
      const k = options.topK || 5;
      const threshold = options.minConfidence ?? 0.3;
      let mapped: Array<{ id: string; content: string; score: number }> = [];
      try {
        const { generateEmbedding } = await import('./memory-initializer.js');
        const qEmb = await generateEmbedding(options.query);
        if (qEmb && Array.isArray(qEmb.embedding) && qEmb.embedding.length > 0) {
          const hits = reasoningBank.findSimilar(qEmb.embedding, { k, threshold });
          // findSimilar() no longer overwrites confidence with the query-match
          // score — prefer similarity (the actual match strength) for search ranking,
          // falling back to confidence/score only for older/foreign result shapes.
          mapped = (Array.isArray(hits) ? hits : []).map((r: any) => ({
            id: r.id ?? '',
            content: r.content ?? '',
            score: r.similarity ?? r.confidence ?? r.score ?? 0,
          }));
        }
      } catch { /* embedding unavailable — fall through to substring scan */ }

      // Deterministic substring fallback over the same in-memory store.
      if (mapped.length === 0 && typeof reasoningBank.getAll === 'function') {
        const q = options.query.toLowerCase();
        mapped = (reasoningBank.getAll() as any[])
          .filter((p: any) => typeof p.content === 'string' && p.content.toLowerCase().includes(q))
          .slice(0, k)
          .map((p: any) => ({ id: p.id ?? '', content: p.content ?? '', score: p.confidence ?? 0 }));
      }

      // Nothing in the bank: patterns written by the SQL fallback path (before
      // the bank was registered, or by a process without it) live in the
      // `pattern` namespace, so search that instead of returning empty.
      if (mapped.length > 0) return { results: mapped, controller: 'reasoningBank' };
    }

    // Fallback: search via bridge
    const result = await bridgeSearchEntries({
      query: options.query,
      namespace: 'pattern',
      limit: options.topK || 5,
      threshold: options.minConfidence || 0.3,
      dbPath: options.dbPath,
    });

    return result ? {
      results: result.results.map(r => ({ id: r.id, content: r.content, score: r.score })),
      controller: 'bridge-fallback',
    } : null;
  } catch (err) {
    // #3327 Finding A — see bridgeStorePattern's catch. `embedQuery is not a
    // function` died here silently, which is why search reported
    // `reasoningBank-unavailable:registry-null` (a null return) even though
    // the registry was present and the controller was reported enabled.
    bridgeFailureReasons.set(canonicalDbPath(options.dbPath), err instanceof Error ? err.message : String(err));
    return null;
  }
}

// ===== Phase 3: Feedback recording =====

/**
 * Record task feedback for learning via ReasoningBank or LearningSystem.
 * Wired into hooks_post-task handler.
 */
export async function bridgeRecordFeedback(options: {
  taskId: string;
  /** Human-readable task text used as the semantic learning signal. */
  task?: string;
  success: boolean;
  quality: number;
  agent?: string;
  duration?: number;
  patterns?: string[];
  dbPath?: string;
  // ADR-147 P2: nested-subagent spawn tree capture.
  // parentAgentId is sourced from Claude Code's `parent_agent_id` OTel span tag
  // (header `x-claude-code-parent-agent-id`). depth is the chain length from the
  // root lead session (0 = lead, 1+ = subagent). Both undefined for top-level work.
  parentAgentId?: string;
  depth?: number;
}): Promise<{ success: boolean; controller: string; updated: number } | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeRecordFeedback(options));
  const patterns = validateFeedbackPatterns(options.patterns);
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;

  try {
    let controller = 'none';
    let updated = 0;

    // Real intelligence-pipeline write (#2786 fix-3, 2026-07-26 sweep follow-up).
    // The prior code called `learningSystem.recordFeedback/.record` and
    // `reasoningBank.recordOutcome/.record` — none of those methods exist on
    // the LocalSonaCoordinator / LocalReasoningBank instances the bridge
    // actually wires into the registry (see initializeIntelligence in
    // memory/intelligence.ts). The silent catch made it look successful.
    //
    // The REAL public API is `intelligence.recordTrajectory(steps, verdict)`
    // — same call `hooks_post-command` already uses (hooks-tools.ts).
    // It initializes lazily, embeds the step, and drives both the SONA
    // coordinator and pattern distillation.
    try {
      const intelligence = await import('./intelligence.js');
      const verdict = options.success ? 'success' : 'failure';
      const taskContext = options.task?.trim();
      const recorded = await intelligence.recordTrajectory(
        [{
          type: 'action',
          // Put the task description first so the embedding represents the
          // work, not just the bookkeeping suffix (#2812).
          content: `${taskContext ? `${taskContext} — ` : ''}Task ${options.taskId} completed by ${options.agent || 'unknown'} — success=${options.success}, quality=${options.quality.toFixed(3)}`,
          metadata: {
            taskId: options.taskId,
            task: taskContext,
            agent: options.agent,
            quality: options.quality,
            duration: options.duration,
            // ADR-147 P2: forward spawn-tree lineage if present
            parentAgentId: options.parentAgentId,
            depth: options.depth,
          },
          timestamp: Date.now(),
        }],
        verdict,
      );
      if (recorded) {
        controller = 'intelligence';
        updated++;
      }
    } catch {
      // Intelligence init failed (missing embeddings backend etc.). Fall
      // through to the memory-store write below — that always succeeds via
      // sql.js fallback so feedback is never fully lost.
    }

    // Optional pattern store: if the caller supplied learned patterns,
    // add them to LocalReasoningBank via its real `.store()` method (the
    // one method that DOES exist on the class).
    const reasoningBank = registry.get('reasoningBank');
    if (reasoningBank && Array.isArray(patterns) && patterns.length) {
      for (const pattern of patterns) {
        try {
          if (typeof reasoningBank.store === 'function') {
            reasoningBank.store({
              id: `feedback-pattern-${options.taskId}-${updated}`,
              content: pattern,
              category: options.agent || 'general',
              confidence: options.quality,
              source: 'bridge-feedback',
            });
            updated++;
          }
        } catch { /* pattern rejected — non-critical */ }
      }
      if (updated > 0 && controller === 'intelligence') controller = 'intelligence+reasoningBank';
      else if (updated > 0 && controller === 'none') controller = 'reasoningBank';
    }

    // SkillLibrary's public API is createSkill(Skill), not promote().
    if (options.success && options.quality >= 0.9 && patterns?.length) {
      const skills = registry.get('skills');
      let created = 0;
      if (skills && typeof skills.createSkill === 'function') {
        for (const [index, pattern] of patterns.entries()) {
          try {
            await skills.createSkill({
              name: `feedback-${options.taskId}-${index}`,
              description: pattern,
              successRate: 1,
              uses: 1,
              avgReward: options.quality,
              avgLatencyMs: options.duration,
              metadata: { taskId: options.taskId, task: options.task, agent: options.agent, source: 'bridge-feedback' },
            });
            updated++;
            created++;
          } catch { /* failed promotion must not count as an update */ }
        }
        if (created > 0) controller = controller === 'none' ? 'skills' : `${controller}+skills`;
      }
    }

    // Always store feedback as a memory entry for retrieval (ensures it persists)
    const storeResult = await bridgeStoreEntry({
      key: `feedback-${options.taskId}`,
      value: JSON.stringify(options),
      namespace: 'feedback',
      tags: [options.success ? 'success' : 'failure', options.agent || 'unknown'],
      dbPath: options.dbPath,
    });
    if (storeResult?.success) {
      controller = controller === 'none' ? 'bridge-store' : `${controller}+bridge-store`;
      updated++;
    }

    return { success: true, controller, updated };
  } catch {
    return null;
  }
}

// ===== Phase 3: CausalMemoryGraph =====

/**
 * Record a causal edge between two entries (e.g., task → result).
 */
export async function bridgeRecordCausalEdge(options: {
  sourceId: string;
  targetId: string;
  relation: string;
  weight?: number;
  dbPath?: string;
}): Promise<{ success: boolean; controller: string } | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeRecordCausalEdge(options));
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;

  try {
    const causalGraph = registry.get('causalGraph');
    if (causalGraph && typeof causalGraph.addEdge === 'function') {
      causalGraph.addEdge(options.sourceId, options.targetId, {
        relation: options.relation,
        weight: options.weight ?? 1.0,
        timestamp: Date.now(),
      });
      return { success: true, controller: 'causalGraph' };
    }

    // Fallback: store edge as metadata
    const ctx = getDb(registry);
    if (ctx) {
      try {
        ctx.db.prepare(`
          INSERT OR REPLACE INTO memory_entries (id, key, namespace, content, type, created_at, updated_at, status)
          VALUES (?, ?, 'causal-edges', ?, 'procedural', ?, ?, 'active')
        `).run(
          generateId('edge'),
          `${options.sourceId}→${options.targetId}`,
          JSON.stringify(options),
          Date.now(), Date.now(),
        );
        return { success: true, controller: 'bridge-fallback' };
      } catch { /* skip */ }
    }

    return null;
  } catch {
    return null;
  }
}

// ===== #1784: Delete tools for hierarchical + causal-graph =====

/**
 * Delete a hierarchical-memory entry by key (#1784).
 *
 * Reality check: agentdb's HierarchicalMemory class doesn't expose a public
 * delete API today, so the real-backend path falls back to direct SQL on
 * the underlying SQLite tables (status flip to 'deleted' + AttestationLog
 * audit). The bridge-fallback path that bridgeHierarchicalStore uses when
 * HierarchicalMemory isn't loaded writes plain memory_entries rows that
 * `bridgeDeleteEntry` already handles.
 *
 * Returns { controller: 'native-unsupported' } when the real HM is loaded
 * and the SQL fallback can't reach its private tables — surfacing the
 * limitation honestly instead of silently returning success.
 */
export async function bridgeDeleteHierarchical(options: {
  key: string;
  tier?: string;
  dbPath?: string;
}): Promise<{
  success: boolean;
  deleted: boolean;
  key: string;
  tier?: string;
  controller: string;
  guarded?: boolean;
  error?: string;
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeDeleteHierarchical(options));
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;
  try {
    const { key, tier } = options;

    // MutationGuard validation
    const guardResult = await guardValidate(registry, 'delete', { key, namespace: 'hierarchical' });
    if (!guardResult.allowed) {
      return { success: false, deleted: false, key, tier, controller: 'guard', error: `MutationGuard rejected: ${guardResult.reason}` };
    }

    const hm = registry.get('hierarchicalMemory');

    // 1. [email protected]+: ReflexionMemory.deleteEpisode propagates through
    //    graph adapter / generic graph backend / vector backend AND purges SQL
    //    episodes + episode_embeddings rows. Single call, durably consistent.
    //    See agentic-flow#150/#151 (closes ruvnet/RuVector#427 the cli-visible way).
    const reflexion = registry.get('reflexionMemory');
    if (reflexion && typeof reflexion.deleteEpisode === 'function') {
      try {
        const removed = await reflexion.deleteEpisode(key);
        if (removed) {
          await logAttestation(registry, 'delete', key, { namespace: 'hierarchical', tier });
          return { success: true, deleted: true, key, tier, controller: 'reflexionMemory', guarded: true };
        }
      } catch { /* fall through */ }
    }

    // 2. Try HierarchicalMemory's own delete API if it ever ships one.
    if (hm && typeof hm.delete === 'function') {
      try {
        await hm.delete(key);
        await logAttestation(registry, 'delete', key, { namespace: 'hierarchical', tier });
        return { success: true, deleted: true, key, tier, controller: 'hierarchicalMemory', guarded: true };
      } catch (err) {
        // Fall through to SQL fallback
      }
    }

    // 3. Stub HierarchicalMemory may expose `remove` or `forget`
    if (hm && typeof hm.remove === 'function') {
      try {
        await hm.remove(key);
        await logAttestation(registry, 'delete', key, { namespace: 'hierarchical', tier });
        return { success: true, deleted: true, key, tier, controller: 'hierarchicalMemory-stub', guarded: true };
      } catch { /* fall through */ }
    }

    // 3. Bridge-fallback: HM stored to memory_entries with namespace prefix
    //    (used when the real controller isn't loaded). Soft-delete via SQL.
    const ctx = getDb(registry);
    if (ctx) {
      try {
        const result = ctx.db.prepare(`
          UPDATE memory_entries
          SET status = 'deleted', updated_at = ?
          WHERE key = ? AND namespace LIKE 'hierarchical%' AND status = 'active'
        `).run(Date.now(), key);
        const changes = result?.changes ?? 0;
        if (changes > 0) {
          await logAttestation(registry, 'delete', key, { namespace: 'hierarchical', tier });
          return { success: true, deleted: true, key, tier, controller: 'bridge-fallback', guarded: true };
        }
        // Nothing to delete in SQL fallback — and no real-HM delete API.
        // Surface the situation honestly.
        return {
          success: false, deleted: false, key, tier,
          controller: hm ? 'native-unsupported' : 'not-found',
          error: hm
            ? 'HierarchicalMemory has no public delete API; entry remains in native storage'
            : 'No hierarchical entry found with this key',
        };
      } catch (err) {
        return { success: false, deleted: false, key, tier, controller: 'sql-error', error: (err as Error).message };
      }
    }
    return null;
  } catch {
    return null;
  }
}

/**
 * Delete a causal edge between two memory entries (#1784).
 *
 * The bridge stores fallback edges in namespace='causal-edges' with key
 * '{sourceId}→{targetId}'. Those CAN be soft-deleted. The native graph-node
 * backend has no delete API (createNode/createEdge/createHyperedge only),
 * so an edge that landed in graph-node native storage stays there. We
 * surface that explicitly via controller: 'native-unsupported'.
 */
export async function bridgeDeleteCausalEdge(options: {
  sourceId: string;
  targetId: string;
  relation?: string;
  dbPath?: string;
}): Promise<{
  success: boolean;
  deleted: boolean;
  sourceId: string;
  targetId: string;
  controller: string;
  guarded?: boolean;
  error?: string;
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeDeleteCausalEdge(options));
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;
  try {
    const { sourceId, targetId, relation } = options;
    const edgeKey = `${sourceId}→${targetId}`;

    const guardResult = await guardValidate(registry, 'delete', { key: edgeKey, namespace: 'causal-edges' });
    if (!guardResult.allowed) {
      return { success: false, deleted: false, sourceId, targetId, controller: 'guard', error: `MutationGuard rejected: ${guardResult.reason}` };
    }

    const causalGraph = registry.get('causalGraph');

    // 1. [email protected]+: GraphDatabaseAdapter.deleteEdgesByEndpoints
    //    handles the (sourceId, targetId, relation?) tuple case directly via
    //    Cypher MATCH … DETACH DELETE. Cypher-injection-safe (label validated
    //    against /^[A-Za-z_][A-Za-z0-9_]*$/ upstream).
    if (causalGraph && typeof causalGraph.deleteEdgesByEndpoints === 'function') {
      try {
        const r = await causalGraph.deleteEdgesByEndpoints(sourceId, targetId, relation);
        const deletedCount = typeof r === 'object' && r ? (r.deleted ?? 0) : (r ? 1 : 0);
        if (deletedCount > 0) {
          await logAttestation(registry, 'delete', edgeKey, { namespace: 'causal-edges', relation, count: deletedCount });
          return { success: true, deleted: true, sourceId, targetId, controller: 'causalGraph-cypher', guarded: true };
        }
      } catch { /* fall through */ }
    }

    // 2. Pre-alpha.13 / different controller: try removeEdge() if exposed.
    if (causalGraph && typeof causalGraph.removeEdge === 'function') {
      try {
        await causalGraph.removeEdge(sourceId, targetId, relation);
        await logAttestation(registry, 'delete', edgeKey, { namespace: 'causal-edges', relation });
        return { success: true, deleted: true, sourceId, targetId, controller: 'causalGraph', guarded: true };
      } catch { /* fall through */ }
    }

    // 2. Bridge-fallback: soft-delete the memory_entries row.
    const ctx = getDb(registry);
    if (ctx) {
      try {
        const result = ctx.db.prepare(`
          UPDATE memory_entries
          SET status = 'deleted', updated_at = ?
          WHERE key = ? AND namespace = 'causal-edges' AND status = 'active'
        `).run(Date.now(), edgeKey);
        const changes = result?.changes ?? 0;
        if (changes > 0) {
          await logAttestation(registry, 'delete', edgeKey, { namespace: 'causal-edges', relation });
          return { success: true, deleted: true, sourceId, targetId, controller: 'bridge-fallback', guarded: true };
        }
        return {
          success: false, deleted: false, sourceId, targetId,
          controller: 'native-unsupported',
          error: 'graph-node native backend has no delete API; edge cannot be removed from native storage. SQL fallback found no matching row.',
        };
      } catch (err) {
        return { success: false, deleted: false, sourceId, targetId, controller: 'sql-error', error: (err as Error).message };
      }
    }
    return null;
  } catch {
    return null;
  }
}

/**
 * Cascade-delete a causal node and all its incident edges (#1784).
 *
 * Same constraint as bridgeDeleteCausalEdge — native graph-node lacks a
 * delete API. SQL fallback path soft-deletes the node (if stored as a
 * memory_entries row) and every edge whose key contains the nodeId.
 */
export async function bridgeDeleteCausalNode(options: {
  nodeId: string;
  dbPath?: string;
}): Promise<{
  success: boolean;
  deletedNode: boolean;
  deletedEdges: number;
  nodeId: string;
  controller: string;
  guarded?: boolean;
  error?: string;
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeDeleteCausalNode(options));
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;
  try {
    const { nodeId } = options;

    const guardResult = await guardValidate(registry, 'delete', { key: nodeId, namespace: 'causal-nodes' });
    if (!guardResult.allowed) {
      return { success: false, deletedNode: false, deletedEdges: 0, nodeId, controller: 'guard', error: `MutationGuard rejected: ${guardResult.reason}` };
    }

    // 1. [email protected]+: GraphDatabaseAdapter.deleteNode(id, {cascade})
    //    counts incident edges before delete so we get accurate audit numbers
    //    regardless of binding stats. Cypher MATCH (n {id}) DETACH DELETE n.
    const causalGraph = registry.get('causalGraph');
    if (causalGraph && typeof causalGraph.deleteNode === 'function') {
      try {
        const r = await causalGraph.deleteNode(nodeId, { cascade: true });
        if (r && typeof r === 'object') {
          const deletedNodeNative = !!r.deletedNode;
          const deletedEdgesNative = typeof r.deletedEdges === 'number' ? r.deletedEdges : 0;
          await logAttestation(registry, 'delete', nodeId, { namespace: 'causal-nodes', deletedEdges: deletedEdgesNative });
          return {
            success: true,
            deletedNode: deletedNodeNative,
            deletedEdges: deletedEdgesNative,
            nodeId,
            controller: 'causalGraph-cypher',
            guarded: true,
          };
        }
      } catch { /* fall through to SQL */ }
    }

    // 2. SQL fallback: soft-delete the node row + every causal-edges row whose
    //    key contains nodeId on either side. Used when agentdb pre-alpha.13 OR
    //    when the entry was stored via the bridge's SQL fallback path.
    const ctx = getDb(registry);
    if (!ctx) return null;

    let deletedEdges = 0;
    let deletedNode = false;
    try {
      const edgeResult = ctx.db.prepare(`
        UPDATE memory_entries
        SET status = 'deleted', updated_at = ?
        WHERE namespace = 'causal-edges'
          AND status = 'active'
          AND (key LIKE ? OR key LIKE ?)
      `).run(Date.now(), `${nodeId}→%`, `%→${nodeId}`);
      deletedEdges = edgeResult?.changes ?? 0;

      const nodeResult = ctx.db.prepare(`
        UPDATE memory_entries
        SET status = 'deleted', updated_at = ?
        WHERE key = ? AND status = 'active'
      `).run(Date.now(), nodeId);
      deletedNode = (nodeResult?.changes ?? 0) > 0;

      await logAttestation(registry, 'delete', nodeId, { namespace: 'causal-nodes', deletedEdges });
    } catch (err) {
      return { success: false, deletedNode: false, deletedEdges: 0, nodeId, controller: 'sql-error', error: (err as Error).message };
    }

    return {
      success: true,
      deletedNode,
      deletedEdges,
      nodeId,
      controller: 'bridge-fallback',
      guarded: true,
    };
  } catch {
    return null;
  }
}

// ===== Phase 5: ReflexionMemory session lifecycle =====

/**
 * Start a session with ReflexionMemory episodic replay.
 * Loads relevant past session patterns for the new session.
 */
export async function bridgeSessionStart(options: {
  sessionId: string;
  context?: string;
  dbPath?: string;
}): Promise<{
  success: boolean;
  controller: string;
  restoredPatterns: number;
  sessionId: string;
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeSessionStart(options));
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;

  try {
    let restoredPatterns = 0;
    let controller = 'none';

    // Try ReflexionMemory for episodic session replay
    const reflexion = registry.get('reflexion');
    if (reflexion && typeof reflexion.startEpisode === 'function') {
      await reflexion.startEpisode(options.sessionId, { context: options.context });
      controller = 'reflexion';
    }

    // Load recent patterns from past sessions
    const searchResult = await bridgeSearchEntries({
      query: options.context || 'session patterns',
      namespace: 'session',
      limit: 10,
      threshold: 0.2,
      dbPath: options.dbPath,
    });

    if (searchResult?.results) {
      restoredPatterns = searchResult.results.length;
    }

    return {
      success: true,
      controller: controller === 'none' ? 'bridge-search' : controller,
      restoredPatterns,
      sessionId: options.sessionId,
    };
  } catch {
    return null;
  }
}

/**
 * End a session and persist episodic summary to ReflexionMemory.
 */
export async function bridgeSessionEnd(options: {
  sessionId: string;
  summary?: string;
  tasksCompleted?: number;
  patternsLearned?: number;
  dbPath?: string;
}): Promise<{
  success: boolean;
  controller: string;
  persisted: boolean;
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeSessionEnd(options));
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;

  try {
    let controller = 'none';
    let persisted = false;

    // End episode in ReflexionMemory
    const reflexion = registry.get('reflexion');
    if (reflexion && typeof reflexion.endEpisode === 'function') {
      await reflexion.endEpisode(options.sessionId, {
        summary: options.summary,
        tasksCompleted: options.tasksCompleted,
        patternsLearned: options.patternsLearned,
      });
      controller = 'reflexion';
      persisted = true;
    }

    // Persist session summary as memory entry
    await bridgeStoreEntry({
      key: `session-${options.sessionId}`,
      value: JSON.stringify({
        sessionId: options.sessionId,
        summary: options.summary || 'Session ended',
        tasksCompleted: options.tasksCompleted ?? 0,
        patternsLearned: options.patternsLearned ?? 0,
        endedAt: new Date().toISOString(),
      }),
      namespace: 'session',
      tags: ['session-end'],
      upsert: true,
      dbPath: options.dbPath,
    });

    if (controller === 'none') controller = 'bridge-store';
    persisted = true;

    // Phase 3: Trigger NightlyLearner consolidation if available
    const nightlyLearner = registry.get('nightlyLearner');
    if (nightlyLearner && typeof nightlyLearner.consolidate === 'function') {
      try {
        await nightlyLearner.consolidate({ sessionId: options.sessionId });
        controller += '+nightlyLearner';
      } catch { /* non-fatal */ }
    }

    return { success: true, controller, persisted };
  } catch {
    return null;
  }
}

// ===== Phase 5: SemanticRouter bridge =====

/**
 * Route a task via AgentDB's SemanticRouter.
 * Returns null to fall back to local ruvector router.
 */
export async function bridgeRouteTask(options: {
  task: string;
  context?: string;
  dbPath?: string;
}): Promise<{
  route: string;
  confidence: number;
  agents: string[];
  controller: string;
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeRouteTask(options));
  const registry = await getRegistry(options.dbPath);
  if (!registry) return null;

  try {
    // Try AgentDB's SemanticRouter
    const semanticRouter = registry.get('semanticRouter');
    if (semanticRouter && typeof semanticRouter.route === 'function') {
      const result = await semanticRouter.route(options.task, { context: options.context });
      if (result) {
        return {
          route: result.route || result.category || 'general',
          confidence: result.confidence ?? result.score ?? 0.5,
          agents: result.agents || result.suggestedAgents || [],
          controller: 'semanticRouter',
        };
      }
    }

    // Try LearningSystem recommendAlgorithm (Phase 4)
    const learningSystem = registry.get('learningSystem');
    if (learningSystem && typeof learningSystem.recommendAlgorithm === 'function') {
      const rec = await learningSystem.recommendAlgorithm(options.task);
      if (rec) {
        return {
          route: rec.algorithm || rec.route || 'general',
          confidence: rec.confidence ?? 0.5,
          agents: rec.agents || [],
          controller: 'learningSystem',
        };
      }
    }

    return null; // Fall back to local router
  } catch {
    return null;
  }
}

// ===== Phase 4: Health check with attestation =====

/**
 * Get comprehensive bridge health including all controller statuses.
 */
export async function bridgeHealthCheck(
  dbPath?: string,
): Promise<{
  available: boolean;
  controllers: Array<{ name: string; enabled: boolean; level: number }>;
  attestationCount?: number;
  cacheStats?: { size: number; hits: number; misses: number };
  hierarchicalMemory?: {
    controller: string;
    durable: boolean;
    persistence: string;
    /** Real row count in the backing table — null when nothing is on disk. */
    persistedRows: number | null;
    fallbackFrom?: string;
  };
} | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeHealthCheck(dbPath));
  const registry = await getRegistry(dbPath);
  if (!registry) return null;

  try {
    const controllers = registry.listControllers();

    // Phase 4: AttestationLog stats
    let attestationCount = 0;
    const attestation = registry.get('attestationLog');
    if (attestation && typeof attestation.count === 'function') {
      attestationCount = attestation.count();
    }

    // Phase 2: TieredCache stats
    let cacheStats = { size: 0, hits: 0, misses: 0 };
    const cache = registry.get('tieredCache');
    if (cache && typeof cache.stats === 'function') {
      const s = cache.stats();
      cacheStats = { size: s.size ?? 0, hits: s.hits ?? 0, misses: s.misses ?? 0 };
    }

    // #2887: cacheStats alone let a "successful" hierarchical-store coexist
    // with an empty store. Report the backing table's real row count so the
    // inconsistency is visible instead of inferred.
    let hierarchicalMemory;
    const hm = registry.get('hierarchicalMemory');
    if (hm) {
      hierarchicalMemory = {
        ...describeHierarchicalStore(hm, getHierarchicalFallback(registry)),
        persistedRows: typeof hm.countPersisted === 'function' ? hm.countPersisted() : null,
      };
    }

    return { available: true, controllers, attestationCount, cacheStats, hierarchicalMemory };
  } catch {
    return null;
  }
}

// ===== Phase 7: Hierarchical memory, consolidation, batch, context, semantic route =====

/**
 * Store to hierarchical memory with tier.
 * Valid tiers: working, episodic, semantic
 *
 * Real HierarchicalMemory API (agentdb alpha.10+):
 *   store(content, importance?, tier?, options?) → Promise<string>
 * Fallback API (@claude-flow/memory TieredMemoryStore):
 *   store(key, value, tier, temporalOptions?) — synchronous, returns
 *   { id, key, tier, superseded? }
 *
 * Temporal validity (Zep/Graphiti-style, impl/memory-sota):
 * - validFrom / validUntil (ISO) travel with the entry.
 * - supersedes=<entryId|key> INVALIDATES the old entry (validUntil=now +
 *   supersededBy=newId) instead of deleting it. Natively supported by the
 *   TieredMemoryStore fallback; on the real agentdb HierarchicalMemory the
 *   temporal fields are stored in metadata, and supersede is reported as
 *   unsupported (no public update API) rather than silently dropped.
 */
/**
 * Describe which store `agentdb_hierarchical-*` actually landed on and
 * whether its writes survive the process (#2887).
 *
 * agentdb removed its `HierarchicalMemory` export at 3.0.0-alpha.17, so the
 * @claude-flow/memory TieredMemoryStore fallback is the live path. It is only
 * durable when it was handed a SQLite connection — callers must not report a
 * volatile write as a success.
 */
export function describeHierarchicalStore(
  hm: any,
  fallback: { reason: string } | null,
): { controller: string; fallbackFrom?: string; durable: boolean; persistence: string } {
  // Only the tiered fallback exposes isDurable(); the native controller
  // (should agentdb reintroduce it) writes to agentdb's own tables.
  if (typeof hm?.isDurable !== 'function') {
    return { controller: 'hierarchicalMemory', durable: true, persistence: 'agentdb' };
  }
  return {
    controller: 'tieredMemoryStore',
    fallbackFrom: fallback?.reason ?? 'hierarchicalMemory',
    durable: hm.isDurable() === true,
    persistence: typeof hm.getPersistence === 'function' ? hm.getPersistence() : 'unknown',
  };
}

/** Read `getHierarchicalFallback()` off a registry that may predate it. */
function getHierarchicalFallback(registry: any): { reason: string } | null {
  return typeof registry?.getHierarchicalFallback === 'function'
    ? registry.getHierarchicalFallback()
    : null;
}

export async function bridgeHierarchicalStore(params: {
  key: string; value: string; tier?: string; importance?: number;
  validFrom?: string; validUntil?: string; supersedes?: string;
}): Promise<any> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeHierarchicalStore(params));
  const registry = await getRegistry();
  if (!registry) return null;
  try {
    const hm = registry.get('hierarchicalMemory');
    if (!hm) return { success: false, error: 'HierarchicalMemory not available' };
    const tier = params.tier || 'working';

    // Detect real HierarchicalMemory (has async store returning id) vs stub
    if (typeof hm.getStats === 'function' && typeof hm.promote === 'function') {
      // Real agentdb HierarchicalMemory — temporal fields ride in metadata
      // so bridgeHierarchicalRecall can filter on them.
      const metadata: Record<string, unknown> = { key: params.key };
      if (params.validFrom) metadata.validFrom = params.validFrom;
      if (params.validUntil) metadata.validUntil = params.validUntil;
      const id = await hm.store(params.value, params.importance || 0.5, tier, {
        metadata,
        tags: [params.key],
      });
      const result: any = {
        success: true, id, key: params.key, tier,
        controller: 'hierarchicalMemory', durable: true, persistence: 'agentdb',
      };
      if (params.supersedes) {
        // No public update/invalidate API on agentdb HierarchicalMemory —
        // surface the limitation honestly instead of silently dropping it.
        result.superseded = null;
        result.warning = 'supersedes is not supported by the native agentdb HierarchicalMemory backend (no update API); the referenced entry was left untouched';
      }
      return result;
    }
    // TieredMemoryStore fallback (temporal-aware) / legacy stub.
    // agentdb dropped its HierarchicalMemory export at 3.0.0-alpha.17, so
    // this is the live path — and it is only trustworthy when the store is
    // backed by SQLite. A volatile write must NOT report success (#2887).
    const storeResult = hm.store(params.key, params.value, tier, {
      validFrom: params.validFrom,
      validUntil: params.validUntil,
      supersedes: params.supersedes,
    });
    const info = describeHierarchicalStore(hm, getHierarchicalFallback(registry));
    const base = {
      ...info,
      ...(storeResult && typeof storeResult === 'object' ? storeResult : { key: params.key, tier }),
    };
    if (!info.durable) {
      return {
        ...base,
        success: false,
        error: `hierarchical-store is running on the ${info.persistence} tiered fallback (${info.fallbackFrom}); the entry is NOT persisted to disk and will be lost when this process exits. Use memory_store for durable key-value persistence.`,
      };
    }
    return { success: true, ...base };
  } catch (e: any) { return { success: false, error: e.message }; }
}

/**
 * Recall from hierarchical memory.
 *
 * Real HierarchicalMemory API (agentdb alpha.10+):
 *   recall(query: MemoryQuery) → Promise<MemoryItem[]>
 *   where MemoryQuery = { query, tier?, k?, threshold?, context?, includeDecayed? }
 * Stub API (fallback):
 *   recall(query: string, topK: number) → synchronous array
 */
export async function bridgeHierarchicalRecall(params: { query: string; tier?: string; topK?: number; includeExpired?: boolean }): Promise<any> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeHierarchicalRecall(params));
  const registry = await getRegistry();
  if (!registry) return null;
  try {
    const hm = registry.get('hierarchicalMemory');
    if (!hm) return { results: [], error: 'HierarchicalMemory not available' };

    // Detect real HierarchicalMemory vs stub
    if (typeof hm.getStats === 'function' && typeof hm.promote === 'function') {
      // Real agentdb HierarchicalMemory — recall takes MemoryQuery object
      const memoryQuery: any = {
        query: params.query,
        k: params.topK || 5,
      };
      if (params.tier) {
        memoryQuery.tier = params.tier;
      }
      const results = await hm.recall(memoryQuery);
      // Temporal filter over metadata (validFrom/validUntil stamped by
      // bridgeHierarchicalStore). Entries without the fields are always
      // valid — legacy behavior unchanged.
      const filtered = params.includeExpired
        ? (results || [])
        : (results || []).filter((r: any) => {
            const meta = r?.metadata || {};
            const now = Date.now();
            if (meta.validFrom) {
              const from = Date.parse(String(meta.validFrom));
              if (!Number.isNaN(from) && from > now) return false;
            }
            if (meta.validUntil) {
              const until = Date.parse(String(meta.validUntil));
              if (!Number.isNaN(until) && until <= now) return false;
            }
            return true;
          });
      return { results: filtered, controller: 'hierarchicalMemory' };
    }

    // TieredMemoryStore fallback — recall(string, number, options?).
    // Temporal filtering happens inside the store; the legacy stub simply
    // ignores the extra argument.
    const results = hm.recall(params.query, params.topK || 5, {
      includeExpired: params.includeExpired === true,
    });
    const filtered = params.tier
      ? results.filter((r: any) => r.tier === params.tier)
      : results;
    return { results: filtered, ...describeHierarchicalStore(hm, getHierarchicalFallback(registry)) };
  } catch (e: any) { return { results: [], error: e.message }; }
}

/** Run consolidation when a real controller is available. */
export async function bridgeConsolidate(params: { minAge?: number; maxEntries?: number }): Promise<any> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeConsolidate(params));
  // No installed consolidation API accepts these historical options. Reject
  // them explicitly rather than silently claiming their limits were applied.
  if (params.minAge !== undefined || params.maxEntries !== undefined) {
    return { success: false, status: 'unsupported', error: 'minAge and maxEntries are not supported by the consolidation controller' };
  }
  const registry = await getRegistry();
  if (!registry) return null;
  try {
    const mc = registry.get('memoryConsolidation');
    if (!mc) return { success: false, error: 'MemoryConsolidation not available' };
    const result = await mc.consolidate();
    if (result?.source === 'stub') {
      return { success: false, status: 'unsupported', error: 'Memory consolidation is unavailable; no consolidation ran', consolidated: result };
    }
    return { success: true, consolidated: result };
  } catch (e: any) { return { success: false, error: e.message }; }
}

/**
 * Batch operations (insert, update, delete).
 * - insert: calls insertEpisodes(entries) where entries are {content, metadata?}
 * - delete: calls bulkDelete(table, conditions) on episodes table
 * - update: calls bulkUpdate(table, updates, conditions) on episodes table
 */
export async function bridgeBatchOperation(params: { operation: string; entries: any[] }): Promise<any> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeBatchOperation(params));
  const registry = await getRegistry();
  if (!registry) return null;
  try {
    const batch = registry.get('batchOperations');
    if (!batch) return { success: false, error: 'BatchOperations not available' };
    let result;
    switch (params.operation) {
      case 'insert': {
        if (typeof batch.insertEpisodes !== 'function') {
          return { success: false, error: 'BatchOperations.insertEpisodes not available — embedder may not be initialized. Use memory_store instead.' };
        }
        const episodes = params.entries.map((e: any) => ({
          content: e.value || e.content || JSON.stringify(e),
          metadata: e.metadata || { key: e.key },
        }));
        try {
          result = await batch.insertEpisodes(episodes);
        } catch (insertErr: any) {
          if (insertErr?.message?.includes('null') || insertErr?.message?.includes('embedBatch')) {
            return { success: false, error: 'Embedder not initialized for batch insert. Use memory_store for individual entries or run embeddings_init first.' };
          }
          throw insertErr;
        }
        break;
      }
      case 'delete': {
        // bulkDelete(table, conditions) — conditions is a WHERE clause object
        const keys = params.entries.map((e: any) => e.key).filter(Boolean);
        for (const key of keys) {
          await batch.bulkDelete('episodes', { key });
        }
        result = { deleted: keys.length };
        break;
      }
      case 'update': {
        // bulkUpdate(table, updates, conditions)
        for (const entry of params.entries) {
          await batch.bulkUpdate('episodes', { content: entry.value || entry.content }, { key: entry.key });
        }
        result = { updated: params.entries.length };
        break;
      }
      default: return { success: false, error: `Unknown operation: ${params.operation}` };
    }
    return { success: true, operation: params.operation, count: params.entries.length, result };
  } catch (e: any) { return { success: false, error: e.message }; }
}

/**
 * Synthesize context from memories.
 * ContextSynthesizer.synthesize is a static method that takes MemoryPattern[] (not a string).
 */
type ContextEpisode = {
  task: string;
  reward: number;
  success: boolean;
  critique?: string;
  input?: string;
  output?: string;
};

function contextEpisodeFrom(value: unknown): ContextEpisode | null {
  if (typeof value === 'string') {
    try { value = JSON.parse(value); }
    catch { return null; }
  }
  if (!value || typeof value !== 'object' || Array.isArray(value)) return null;

  const record = value as Record<string, unknown>;
  const owns = (key: string) => Object.prototype.hasOwnProperty.call(record, key);
  if (!owns('task') || !owns('reward') || !owns('success')
      || typeof record.task !== 'string' || !record.task.trim()
      || typeof record.reward !== 'number' || !Number.isFinite(record.reward)
      || typeof record.success !== 'boolean') return null;

  const episode: ContextEpisode = {
    task: record.task.trim(),
    reward: record.reward,
    success: record.success,
  };
  for (const field of ['critique', 'input', 'output'] as const) {
    if (owns(field)) {
      if (typeof record[field] !== 'string') return null;
      episode[field] = record[field];
    }
  }
  return episode;
}

function contextEpisodeFromRecall(row: unknown): ContextEpisode | null {
  if (!row || typeof row !== 'object' || Array.isArray(row)) return null;
  const record = row as Record<string, unknown>;
  for (const field of [null, 'metadata', 'value', 'content'] as const) {
    const candidate = field === null ? record
      : Object.prototype.hasOwnProperty.call(record, field) ? record[field] : undefined;
    const episode = contextEpisodeFrom(candidate);
    if (episode) return episode;
  }
  return null;
}

export async function bridgeContextSynthesize(params: { query: string; maxEntries?: number }): Promise<any> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeContextSynthesize(params));
  const registry = await getRegistry();
  if (!registry) return null;
  try {
    const CS = registry.get('contextSynthesizer');
    if (!CS || typeof CS.synthesize !== 'function') {
      return { success: false, reason: 'synthesizer-unavailable', error: 'ContextSynthesizer not available' };
    }
    const hm = registry.get('hierarchicalMemory');
    if (!hm || typeof hm.recall !== 'function') {
      return { success: false, reason: 'memory-unavailable', error: 'HierarchicalMemory not available' };
    }
    let recalled: unknown;
    try {
      // Native HierarchicalMemory accepts a query object; the tiered fallback
      // accepts positional arguments. Either implementation may be async.
      recalled = typeof hm.promote === 'function'
        ? await hm.recall({ query: params.query, k: params.maxEntries || 10 })
        : await hm.recall(params.query, params.maxEntries || 10);
    } catch (e: any) {
      return { success: false, reason: 'recall-failed', error: e.message };
    }
    if (!Array.isArray(recalled)) {
      return { success: false, reason: 'invalid-recall-result', error: 'HierarchicalMemory recall did not return an array' };
    }
    const recalledCount = recalled.length;
    if (recalledCount === 0) {
      return { success: false, reason: 'no-memories', error: 'No memories matched the query', recalled: 0, eligible: 0, skipped: 0 };
    }
    const memories = recalled.map(contextEpisodeFromRecall).filter((episode): episode is ContextEpisode => episode !== null);
    const counts = { recalled: recalledCount, eligible: memories.length, skipped: recalledCount - memories.length };
    if (memories.length === 0) {
      return { success: false, reason: 'no-eligible-episodes', error: 'Recalled memories have no validated task outcomes', ...counts };
    }
    try {
      const result = await CS.synthesize(memories, { includeRecommendations: true });
      if (!result || typeof result !== 'object') {
        return { success: false, reason: 'invalid-synthesis', error: 'ContextSynthesizer returned no result', ...counts };
      }
      return { success: true, synthesis: result, ...counts };
    } catch (e: any) {
      return { success: false, reason: 'synthesizer-failed', error: e.message, ...counts };
    }
  } catch (e: any) { return { success: false, reason: 'bridge-error', error: e.message }; }
}

/**
 * Route via SemanticRouter.
 * Available since agentdb 3.0.0-alpha.10 — uses @ruvector/router for
 * semantic matching with keyword fallback.
 */
export async function bridgeSemanticRoute(params: { input: string }): Promise<any> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeSemanticRoute(params));
  const registry = await getRegistry();
  if (!registry) return null;
  try {
    const router = registry.get('semanticRouter');
    if (!router) {
      // ADR-093 F9: surface an actionable error pointing callers at the
      // alternative routing surfaces that DO work, instead of just
      // saying "not available".
      return {
        route: null,
        error: 'SemanticRouter not available in current agentdb build',
        recommendation: 'Use bridgeRouteTask (registers as `agentdb_route` MCP tool) for keyword+pattern routing, or hooks_model-route for ADR-026 model selection.',
        controller: 'none',
      };
    }
    const result = await router.route(params.input);
    return { route: result, controller: 'semanticRouter' };
  } catch (e: any) { return { route: null, error: e.message, controller: 'error' }; }
}

// ===== RaBitQ data export =====

/**
 * Export all embeddings from the bridge's better-sqlite3 connection.
 * Used by RaBitQ to build its index from the same data that memory_store writes.
 * Returns null if bridge is unavailable (caller falls back to sql.js).
 */
export async function bridgeGetAllEmbeddings(options?: {
  dimensions?: number;
  limit?: number;
  dbPath?: string;
}): Promise<Array<{
  id: string;
  key: string;
  namespace: string;
  embedding: number[];
}> | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeGetAllEmbeddings(options));
  const registry = await getRegistry(options?.dbPath);
  if (!registry) return null;

  const ctx = getDb(registry);
  if (!ctx) return null;

  try {
    const dims = options?.dimensions ?? 384;
    const maxRows = options?.limit ?? 50000;

    const rows: any[] = ctx.db.prepare(`
      SELECT id, key, namespace, embedding
      FROM memory_entries
      WHERE ${liveMemoryRowSql()} AND embedding IS NOT NULL
      LIMIT ?
    `).all(maxRows);

    const results: Array<{ id: string; key: string; namespace: string; embedding: number[] }> = [];

    for (const row of rows) {
      if (!row.embedding) continue;
      try {
        const emb = JSON.parse(row.embedding) as number[];
        if (emb.length !== dims) continue;
        results.push({
          id: String(row.id),
          key: row.key || String(row.id),
          namespace: row.namespace || 'default',
          embedding: emb,
        });
      } catch { /* skip invalid */ }
    }

    return results;
  } catch {
    return null;
  }
}

/**
 * Count the embeddings `bridgeGetAllEmbeddings()` would export (#4203).
 * RaBitQ's auto-build uses this as its cheap "has the corpus drifted?" probe —
 * a COUNT instead of re-reading every embedding blob. With `dimensions` it
 * counts only rows build() would keep, so the drift ratio compares like with
 * like. Returns null if the bridge is unavailable.
 */
export async function bridgeCountEmbeddings(options?: {
  dimensions?: number;
  dbPath?: string;
}): Promise<number | null> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => bridgeCountEmbeddings(options));
  const registry = await getRegistry(options?.dbPath);
  if (!registry) return null;

  const ctx = getDb(registry);
  if (!ctx) return null;

  const dims = options?.dimensions;
  try {
    if (dims != null) {
      try {
        const row = ctx.db.prepare(
          `SELECT COUNT(*) as cnt FROM memory_entries WHERE ${liveMemoryRowSql()} AND embedding IS NOT NULL AND json_array_length(embedding) = ?`,
        ).get(dims);
        return row?.cnt ?? 0;
      } catch {
        // JSON1 unavailable in this SQLite build — fall through to the
        // unfiltered count rather than losing the probe entirely.
      }
    }

    const row = ctx.db.prepare(
      `SELECT COUNT(*) as cnt FROM memory_entries WHERE ${liveMemoryRowSql()} AND embedding IS NOT NULL`,
    ).get();
    return row?.cnt ?? 0;
  } catch {
    return null;
  }
}

// ===== Utility =====

function cosineSim(a: number[], b: number[]): number {
  if (!a || !b || a.length === 0 || b.length === 0) return 0;
  const len = Math.min(a.length, b.length);
  let dot = 0, normA = 0, normB = 0;
  for (let i = 0; i < len; i++) {
    const ai = a[i], bi = b[i];
    dot += ai * bi;
    normA += ai * ai;
    normB += bi * bi;
  }
  const mag = Math.sqrt(normA * normB);
  return mag === 0 ? 0 : dot / mag;
}

/**
 * Public helper for the unified learning-stats aggregator: counts of entries
 * per namespace + the top-level total. Best-effort — if the bridge isn't
 * available it returns zeros so the aggregator can still report the other
 * stores honestly. (#2245 follow-up.)
 */
export async function getMemoryBridgeStats(options: {
  namespaces?: string[];
  dbPath?: string;
} = {}): Promise<{
  totalEntries: number;
  perNamespace: Record<string, number>;
  source: string;
  reachable: boolean;
}> {
  if (!operationContext.getStore()?.active) return withBridgeOperation(() => getMemoryBridgeStats(options));
  const namespaces = options.namespaces ?? [
    'default', 'patterns', 'claude-memories', 'auto-memory',
    'tasks', 'feedback', 'pretrain', 'trajectories',
  ];
  try {
    const all = await bridgeListEntries({ dbPath: options.dbPath, limit: 1 });
    if (!all) {
      return { totalEntries: 0, perNamespace: {}, source: 'memory-bridge (unreachable)', reachable: false };
    }
    const perNamespace: Record<string, number> = {};
    for (const ns of namespaces) {
      try {
        const r = await bridgeListEntries({ namespace: ns, dbPath: options.dbPath, limit: 1 });
        const n = r?.total ?? 0;
        if (n > 0) perNamespace[ns] = n;
      } catch { /* skip per-namespace failure */ }
    }
    return {
      totalEntries: all.total,
      perNamespace,
      source: 'memory-bridge AgentDB (bridgeListEntries)',
      reachable: true,
    };
  } catch {
    return { totalEntries: 0, perNamespace: {}, source: 'memory-bridge (error)', reachable: false };
  }
}