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

fix(doctor): stop inferring memory driver history from table count (#3331)

Sean Yu6ccf25b3e081
diff --git a/v3/@claude-flow/cli/__tests__/doctor-memory-driver-3321.test.ts b/v3/@claude-flow/cli/__tests__/doctor-memory-driver-3321.test.ts
new file mode 100644
index 0000000000..ca6c293249
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/doctor-memory-driver-3321.test.ts
@@ -0,0 +1,253 @@
+/** #3321: schema size cannot identify a database's driver or write history. */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { existsSync, mkdtempSync, readFileSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import Database from 'better-sqlite3';
+import { initializeMemoryDatabase, _resetMemoryRootCache } from '../src/memory/memory-initializer.js';
+import { encryptBuffer } from '../src/encryption/vault.js';
+
+type Check = { name: string; status: string; message: string; fix?: string };
+const originalCwd = process.cwd();
+let workdir: string;
+let dbPath: string;
+
+async function runDoctor() {
+ const { doctorCommand } = await import('../src/commands/doctor.js');
+ const result = await doctorCommand.action!({
+ flags: { component: 'memory' }, args: [], config: {},
+ } as Parameters<NonNullable<typeof doctorCommand.action>>[0]);
+ const checks = (result.data as { results: Check[] }).results;
+ const driver = checks.find((check) => check.name === 'Memory Persistence Driver');
+ expect(driver).toBeDefined();
+ return { result, checks, driver: driver! };
+}
+
+async function runDriver() {
+ // Probe directly for fault injection: concurrent imports in doctor's other
+ // checks bypass Vitest's manual mock while its first import is in flight.
+ const { checkMemoryPersistenceDriver } = await import('../src/commands/doctor.js');
+ return checkMemoryPersistenceDriver();
+}
+
+function expectNoDriverInference(check: Check) {
+ expect(check.message).not.toMatch(/active driver:|likely created|writes made before|native schema ~|fallback schema shape/i);
+ expect(check.fix ?? '').not.toMatch(/init --force/);
+}
+
+// Wrap real native handles; only the driver check's count query is replaced.
+function mockCountQuery(getCount: () => unknown) {
+ const query = vi.fn(getCount);
+ const handles: Array<{ db: InstanceType<typeof Database>; close: ReturnType<typeof vi.fn> }> = [];
+ const construct = vi.fn(function (filename: string, options: object) {
+ const db = new Database(filename, options);
+ const close = vi.fn(() => db.close());
+ handles.push({ db, close });
+ return {
+ prepare(sql: string) {
+ if (sql === "SELECT count(*) AS c FROM sqlite_master WHERE type='table'") {
+ return { get: query };
+ }
+ return db.prepare(sql);
+ },
+ pragma: (sql: string) => db.pragma(sql),
+ close,
+ };
+ });
+ vi.doMock('better-sqlite3', () => ({ default: construct }));
+ return { handles, construct, query };
+}
+
+beforeEach(async () => {
+ workdir = mkdtempSync(join(tmpdir(), 'doctor-3321-'));
+ process.chdir(workdir);
+ dbPath = join(workdir, '.swarm', 'memory.db');
+ vi.stubEnv('CLAUDE_FLOW_MEMORY_PATH', join(workdir, '.swarm'));
+ vi.stubEnv('CLAUDE_FLOW_DISABLE_BRIDGE', '1');
+ vi.stubEnv('CLAUDE_FLOW_ENCRYPT_AT_REST', '');
+ vi.stubEnv('CLAUDE_FLOW_ENCRYPTION_KEY', '');
+ _resetMemoryRootCache();
+ // Real current initializer and sql.js schema/storage. The existing bridge
+ // opt-out avoids unrelated AgentDB controllers and model downloads.
+ const initialized = await initializeMemoryDatabase({
+ dbPath, backend: 'hybrid', force: true, migrate: false,
+ });
+ expect(initialized.success).toBe(true);
+});
+
+afterEach(() => {
+ vi.doUnmock('better-sqlite3');
+ vi.doUnmock('sql.js');
+ vi.resetModules();
+ vi.unstubAllEnvs();
+ process.chdir(originalCwd);
+ _resetMemoryRootCache();
+ rmSync(workdir, { recursive: true, force: true });
+});
+
+describe('doctor Memory Persistence Driver (#3321)', () => {
+ it('does not recommend rebuilding a freshly initialized, readable schema', async () => {
+ const db = new Database(dbPath, { readonly: true, fileMustExist: true });
+ const tables = db.prepare("SELECT name FROM sqlite_master WHERE type='table'").all() as { name: string }[];
+ expect(tables.map((row) => row.name)).toEqual(expect.arrayContaining([
+ 'memory_entries', 'patterns', 'metadata', 'vector_indexes', 'graph_edges',
+ ]));
+ // Establish that this real fixture exercises the former <20 branch.
+ expect(tables.length).toBeLessThan(20);
+ expect(db.pragma('integrity_check')).toEqual([{ integrity_check: 'ok' }]);
+ db.close();
+ const before = readFileSync(dbPath);
+ const { driver } = await runDoctor();
+ expectNoDriverInference(driver);
+ expect(driver.message).toContain(`${tables.length} tables`);
+ expect(driver.message).toMatch(/read-only/i);
+ expect(driver.message).toMatch(/not verified/i);
+ expect(readFileSync(dbPath)).toEqual(before);
+ });
+
+ it('reports a larger schema with the same limits on what was verified', async () => {
+ const db = new Database(dbPath);
+ for (let i = 0; i < 40; i++) db.exec(`CREATE TABLE extra_${i} (id INTEGER)`);
+ const count = (db.prepare("SELECT count(*) AS c FROM sqlite_master WHERE type='table'").get() as { c: number }).c;
+ db.close();
+ const { driver } = await runDoctor();
+ expect(driver.status).toBe('pass');
+ expect(driver.message).toContain(`${count} tables`);
+ expect(driver.message).toMatch(/not verified/i);
+ expectNoDriverInference(driver);
+ });
+
+ it('warns when the native package cannot be imported even if sql.js reads the schema', async () => {
+ vi.doMock('better-sqlite3', () => { throw new Error('Cannot find package better-sqlite3'); });
+ const driver = await runDriver();
+ expect(driver.status).toBe('warn');
+ expect(driver.message).toMatch(/unavailable|not installed/i);
+ expect(driver.fix).toMatch(/better-sqlite3/);
+ expectNoDriverInference(driver);
+ });
+
+ it('warns when the wrapper loads but its native binding cannot be constructed', async () => {
+ vi.doMock('better-sqlite3', () => ({ default: class {
+ constructor() { throw new Error('Could not locate the bindings file. Tried:\n better_sqlite3.node'); }
+ } }));
+ const driver = await runDriver();
+ const { checks } = await runDoctor();
+ expect(driver.status).toBe('warn');
+ expect(driver.message).toMatch(/binding unavailable/i);
+ expect(driver.message).not.toMatch(/better_sqlite3.node/);
+ expectNoDriverInference(driver);
+ expect(checks.find((c) => c.name === 'Memory Integrity')?.status).toBe('warn');
+ });
+
+ it('does not let a large sql.js table count mask a native open failure', async () => {
+ const db = new Database(dbPath);
+ for (let i = 0; i < 40; i++) db.exec(`CREATE TABLE extra_${i} (id INTEGER)`);
+ db.close();
+ vi.doMock('better-sqlite3', () => ({ default: class {
+ constructor() { throw new Error('SQLITE_CANTOPEN: unable to open database file'); }
+ } }));
+ const driver = await runDriver();
+ const { checks, result } = await runDoctor();
+ expect(driver.status).toBe('warn');
+ expect(driver.message).toMatch(/could not open.*SQLITE_CANTOPEN/i);
+ expectNoDriverInference(driver);
+ expect(checks.find((c) => c.name === 'Memory Integrity')?.status).toBe('fail');
+ expect(result.success).toBe(false);
+ });
+
+ it('warns on a count query exception and closes every owned native handle', async () => {
+ const db = new Database(dbPath);
+ for (let i = 0; i < 40; i++) db.exec(`CREATE TABLE extra_${i} (id INTEGER)`);
+ db.close();
+ const { handles, construct } = mockCountQuery(() => { throw new Error('count probe failed'); });
+ const driver = await runDriver();
+ expect(driver.status).toBe('warn');
+ expect(driver.message).toMatch(/table count.*(unavailable|failed)/i);
+ expect(driver.message).toContain('count probe failed');
+ expect(handles.length).toBeGreaterThan(0);
+ for (const handle of handles) {
+ expect(handle.close).toHaveBeenCalledTimes(1);
+ expect(handle.db.open).toBe(false);
+ }
+ for (const [filename, options] of construct.mock.calls) {
+ expect(filename).toBe(dbPath);
+ expect(options).toEqual({ readonly: true, fileMustExist: true });
+ }
+ });
+
+ it.each([undefined, {}, { c: null }, { c: NaN }, { c: -1 }, { c: 1.5 }, { c: Infinity }])(
+ 'warns when the count query provides no reliable result: %j', async (row) => {
+ const { handles, query } = mockCountQuery(() => row);
+ const driver = await runDriver();
+ expect(driver.status).toBe('warn');
+ expect(driver.message).toMatch(/table count.*(unavailable|failed)/i);
+ expectNoDriverInference(driver);
+ expect(query).toHaveBeenCalledTimes(1);
+ expect(handles).toHaveLength(1);
+ for (const handle of handles) expect(handle.db.open).toBe(false);
+ },
+ );
+
+ it('closes successful native probes without changing logical data', async () => {
+ const before = readFileSync(dbPath);
+ const { handles, query } = mockCountQuery(() => ({ c: 11 }));
+ const driver = await runDriver();
+ expect(driver.message).toMatch(/read-only/i);
+ expect(readFileSync(dbPath)).toEqual(before);
+ expect(query).toHaveBeenCalledTimes(1);
+ expect(handles).toHaveLength(1);
+ for (const handle of handles) {
+ expect(handle.close).toHaveBeenCalledTimes(1);
+ expect(handle.db.open).toBe(false);
+ }
+ });
+
+ it.each(['throw', 'missing', 'invalid'])('keeps an unavailable fallback count unknown: %s', async (mode) => {
+ vi.doMock('better-sqlite3', () => { throw new Error('Cannot find package better-sqlite3'); });
+ const close = vi.fn();
+ const exec = vi.fn(() => {
+ if (mode === 'throw') throw new Error('fallback query failed');
+ return mode === 'missing' ? [] : [{ values: [[NaN]] }];
+ });
+ vi.doMock('sql.js', () => ({ default: async () => ({
+ Database: class { exec = exec; close = close; },
+ }) }));
+ const before = readFileSync(dbPath);
+ const driver = await runDriver();
+ expect(driver.status).toBe('warn');
+ expect(driver.message).toContain('table count unavailable');
+ expectNoDriverInference(driver);
+ expect(exec).toHaveBeenCalledTimes(1);
+ expect(close).toHaveBeenCalledTimes(1);
+ expect(readFileSync(dbPath)).toEqual(before);
+ });
+
+ it('keeps encrypted databases unprobed and unchanged', async () => {
+ writeFileSync(dbPath, encryptBuffer(readFileSync(dbPath), Buffer.alloc(32, 7)));
+ const before = readFileSync(dbPath);
+ const { construct } = mockCountQuery(() => ({ c: 11 }));
+ const driver = await runDriver();
+ expect(driver.status).toBe('warn');
+ expect(driver.message).toMatch(/RFE1-encrypted/);
+ expect(construct).not.toHaveBeenCalled();
+ expect(readFileSync(dbPath)).toEqual(before);
+ });
+
+ it('retains real corruption failures in the integrity check', async () => {
+ writeFileSync(dbPath, 'not a SQLite database');
+ const { driver, checks, result } = await runDoctor();
+ expect(driver.status).toBe('warn');
+ expect(checks.find((c) => c.name === 'Memory Integrity')?.status).toBe('fail');
+ expect(result.success).toBe(false);
+ });
+
+ it('warns without creating a missing database', async () => {
+ unlinkSync(dbPath);
+ const { construct } = mockCountQuery(() => ({ c: 11 }));
+ const driver = await runDriver();
+ expect(driver.status).toBe('warn');
+ expect(driver.message).toMatch(/no memory.db found/);
+ expect(construct).not.toHaveBeenCalled();
+ expect(existsSync(dbPath)).toBe(false);
+ });
+});
diff --git a/v3/@claude-flow/cli/src/commands/doctor.ts b/v3/@claude-flow/cli/src/commands/doctor.ts
index f9347aa954..c35e815928 100644
--- a/v3/@claude-flow/cli/src/commands/doctor.ts
+++ b/v3/@claude-flow/cli/src/commands/doctor.ts
@@ -537,24 +537,14 @@ async function checkMemoryStructuralIntegrity(): Promise<HealthCheck> {
}
}
-// #2968 option 1 β€” read-only doctor check for the active SQLite driver.
-//
-// Native better-sqlite3 (durable, WAL-capable) can silently degrade to the
-// sql.js WASM fallback (non-durable β€” `wal_checkpoint` calls are rejected
-// and the write is lost) when a postinstall script is skipped. `memory
-// store` still printed "Data stored successfully" before the persistWarning
-// fix in #2983/3.38.1 (see memory-store-persist-warning-2968.test.ts); this
-// check gives a standing, read-only signal so the driver split is visible
-// any time doctor runs, independent of any single store call.
-//
-// Table count in the on-disk memory.db is the cheap, reliable signal from
-// the issue report: the native driver's schema produces 47 tables, the
-// sql.js fallback's produces only 10. Deliberately does NOT change install
-// behavior (that's option 2 from #2968, explicitly out of scope here) β€”
-// this only reports, it never repairs.
-const MEMORY_DRIVER_NATIVE_TABLE_FLOOR = 20; // roughly midpoint of sql.js's ~10 and native's ~47
-
-async function checkMemoryPersistenceDriver(): Promise<HealthCheck> {
+// #2968/#3321 β€” read-only native SQLite capability probe. A skipped
+// postinstall can leave the wrapper importable but its binding unavailable.
+// Schema size cannot identify the runtime driver or the database's history:
+// memory init creates its schema with sql.js even when native is available.
+// This probe does not verify schema compatibility or cross-process writes;
+// integrity checks and memory store's persistWarning retain their own roles.
+
+export async function checkMemoryPersistenceDriver(): Promise<HealthCheck> {
const NAME = 'Memory Persistence Driver';
const dbPath = await resolveMemoryDbPath();
if (!dbPath) {
@@ -583,6 +573,7 @@ async function checkMemoryPersistenceDriver(): Promise<HealthCheck> {
let tableCount: number | null = null;
let nativeUnavailableReason: string | null = null;
let nativeOpenOtherError: string | null = null;
+ let nativeQueryError: string | null = null;
if (Database) {
let db: any;
@@ -598,10 +589,14 @@ async function checkMemoryPersistenceDriver(): Promise<HealthCheck> {
}
if (db) {
try {
- const row = db.prepare("SELECT count(*) AS c FROM sqlite_master WHERE type='table'").get() as { c: number };
- tableCount = Number(row?.c ?? 0);
- } catch {
- // leave null β€” Memory Integrity above already reports open/query failures
+ const row = db.prepare("SELECT count(*) AS c FROM sqlite_master WHERE type='table'").get() as { c?: unknown } | undefined;
+ if (typeof row?.c === 'number' && Number.isSafeInteger(row.c) && row.c >= 0) {
+ tableCount = row.c;
+ } else {
+ nativeQueryError = 'query returned no reliable table count';
+ }
+ } catch (e) {
+ nativeQueryError = (e as Error).message || String(e);
} finally {
try { db.close(); } catch { /* best-effort */ }
}
@@ -617,7 +612,10 @@ async function checkMemoryPersistenceDriver(): Promise<HealthCheck> {
if (sdb) {
try {
const res = sdb.exec("SELECT count(*) FROM sqlite_master WHERE type='table'");
- tableCount = Number(res[0]?.values?.[0]?.[0] ?? 0);
+ const count = res[0]?.values?.[0]?.[0];
+ if (typeof count === 'number' && Number.isSafeInteger(count) && count >= 0) {
+ tableCount = count;
+ }
} catch {
// leave null
} finally {
@@ -628,13 +626,13 @@ async function checkMemoryPersistenceDriver(): Promise<HealthCheck> {
const tableSummary = tableCount === null
? 'table count unavailable'
- : `${tableCount} tables (native schema ~47, sql.js-fallback schema ~10 β€” #2968)`;
+ : `${tableCount} tables`;
if (nativeUnavailableReason) {
return {
name: NAME,
status: 'warn',
- message: `${dbPath} β€” active driver: sql.js (WASM fallback, non-durable) β€” native better-sqlite3 binding unavailable: ${nativeUnavailableReason} β€” wal_checkpoint calls silently no-op, writes may not persist across processes (#2968/#2867/#2219) [${tableSummary}]`,
+ message: `${dbPath} β€” native better-sqlite3 binding unavailable: ${nativeUnavailableReason} β€” native read-only probe unavailable; runtime driver and write persistence not verified (#2968) [${tableSummary}; sql.js main-image-only fallback]`,
fix: 'reinstall with npm install scripts enabled, or run `npm rebuild better-sqlite3`; then rerun this check',
};
}
@@ -647,19 +645,18 @@ async function checkMemoryPersistenceDriver(): Promise<HealthCheck> {
};
}
- if (tableCount !== null && tableCount < MEMORY_DRIVER_NATIVE_TABLE_FLOOR) {
+ if (nativeQueryError || tableCount === null) {
return {
name: NAME,
status: 'warn',
- message: `${dbPath} β€” active driver: native better-sqlite3, but this database has only ${tableCount} tables β€” that matches the sql.js-fallback schema shape (~10), not the native schema (~47); it was likely created before the native binding became available, and durable writes made before then may be missing`,
- fix: 'back up .swarm/memory.db then `claude-flow memory init --force` to rebuild under the native driver',
+ message: `${dbPath} β€” native better-sqlite3 opened read-only, but table count unavailable: ${nativeQueryError ?? 'query returned no reliable result'}; runtime driver and write persistence not verified`,
};
}
return {
name: NAME,
status: 'pass',
- message: `${dbPath} β€” active driver: native better-sqlite3 (durable, WAL-capable) [${tableSummary}]`,
+ message: `${dbPath} β€” native better-sqlite3 read-only open and schema query succeeded [${tableSummary}]; runtime driver, schema compatibility, and write persistence not verified`,
};
}
@@ -2420,7 +2417,7 @@ export const doctorCommand: Command = {
checkDaemonStatus,
checkMemoryDatabase,
checkMemoryStructuralIntegrity, // #2737 β€” bounded, native quick_check on every default run
- checkMemoryPersistenceDriver, // #2968 β€” native better-sqlite3 vs sql.js fallback, read-only
+ checkMemoryPersistenceDriver, // #2968/#3321 β€” read-only native capability probe
checkLearningBridge, // #2545 β€” can the auto-memory hook actually load @claude-flow/memory?
checkApiKeys,
checkMcpServers,
@@ -2459,7 +2456,7 @@ export const doctorCommand: Command = {
'memory': [
checkMemoryDatabase, // existing: exists + statable (unchanged)
checkMemoryIntegrity, // #2677 check 1: sql.js open + PRAGMA integrity_check
- checkMemoryPersistenceDriver, // #2968: native better-sqlite3 vs sql.js fallback
+ checkMemoryPersistenceDriver, // #2968/#3321: read-only native capability probe
checkMemoryContent, // #2677 check 2: memory_entries content coverage
checkMemoryEmbeddingCoverage, // #2677 check 3: vector coverage on populated rows
checkMemoryReflexionCoverage, // #2677 check 6: episodes are retrievable