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): wire real memory-DB integrity checks into the default doctor run (#2748)

rUvc47462ebc281
diff --git a/v3/@claude-flow/cli/__tests__/doctor-2737-memory-structural.test.ts b/v3/@claude-flow/cli/__tests__/doctor-2737-memory-structural.test.ts
new file mode 100644
index 0000000000..109b8b3565
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/doctor-2737-memory-structural.test.ts
@@ -0,0 +1,206 @@
+/**
+ * Regression guard for #2737:
+ *
+ * `doctor`'s real memory-database integrity check (`checkMemoryIntegrity`,
+ * plus `checkMemoryContent` / `checkMemoryEmbeddingCoverage`) was only
+ * registered under `componentMap['memory']` (`--component memory`), never
+ * in the `allChecks` array a bare `doctor` or `doctor --fix` actually runs.
+ * The default run's only memory probe was `checkMemoryDatabase` β€” plain
+ * `existsSync` + `statSync` β€” which reports `pass` for ANY file that
+ * exists and can be stat'd, corrupt or not. A genuinely corrupt
+ * `.swarm/memory.db` could sail through a bare `doctor` run reporting
+ * "All checks passed! System is healthy."
+ *
+ * The fix (three parts):
+ * 1. A new, bounded, native `checkMemoryStructuralIntegrity` check (native
+ * better-sqlite3 `PRAGMA quick_check`, WAL-aware) is now IN `allChecks`,
+ * so a bare `doctor` run actually opens the file. `checkMemoryDatabase`
+ * is relabeled "Memory Database Presence" to be honest about its scope.
+ * 2. `checkMemoryIntegrity` (deep, `--component memory` only) now prefers
+ * native better-sqlite3 `PRAGMA integrity_check` over the sql.js
+ * fallback, and the full #2677 trio stays registered there unchanged.
+ * 3. A definitively malformed (and unencrypted) DB maps to `fail`, not
+ * `warn`, in both checks β€” WITH a carve-out for legitimately
+ * RFE1-encrypted-at-rest files (ADR-096), which are NOT malformed.
+ *
+ * This suite drives the checks through `doctorCommand.action()` β€” the same
+ * entry point a real `doctor` / `doctor --component memory` invocation uses
+ * β€” and inspects the returned `HealthCheck[]` plus the top-level
+ * success/exitCode so the wiring gap itself (not just the check functions
+ * in isolation) is what's under test.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+import { doctorCommand } from '../src/commands/doctor.js';
+import { encryptBuffer } from '../src/encryption/vault.js';
+import { _resetMemoryRootCache } from '../src/memory/memory-initializer.js';
+
+type HealthCheck = { name: string; status: 'pass' | 'warn' | 'fail'; message: string; fix?: string };
+type DoctorData = { passed: number; warnings: number; failed: number; results: HealthCheck[] };
+
+const ORIGINAL_CWD = process.cwd();
+let workdir: string;
+
+async function runDoctor(component?: string) {
+ const ctx = {
+ flags: component ? { component } : {},
+ args: [],
+ config: {} as Record<string, unknown>,
+ } as unknown as Parameters<NonNullable<typeof doctorCommand.action>>[0];
+ return doctorCommand.action!(ctx);
+}
+
+function findCheck(results: HealthCheck[], namePart: string): HealthCheck | undefined {
+ return results.find((r) => r.name.includes(namePart));
+}
+
+describe('doctor #2737 β€” bare `doctor` actually opens memory.db', () => {
+ beforeEach(() => {
+ workdir = mkdtempSync(join(tmpdir(), 'doctor-2737-'));
+ process.chdir(workdir);
+ _resetMemoryRootCache();
+ });
+
+ afterEach(() => {
+ process.chdir(ORIGINAL_CWD);
+ _resetMemoryRootCache();
+ try {
+ rmSync(workdir, { recursive: true, force: true });
+ } catch {
+ /* ignore */
+ }
+ });
+
+ function plantDb(bytes: Buffer | string) {
+ mkdirSync(join(workdir, '.swarm'), { recursive: true });
+ writeFileSync(join(workdir, '.swarm', 'memory.db'), bytes);
+ }
+
+ it('default `doctor` run reports the renamed presence check and the new structural check', async () => {
+ // No DB planted β€” both checks should degrade to warn (not-yet-initialized
+ // project), never a silent pass/absence.
+ const result = await runDoctor();
+ const data = result.data as DoctorData;
+ const presence = findCheck(data.results, 'Memory Database Presence');
+ const structural = findCheck(data.results, 'Memory Structural Integrity');
+ expect(presence).toBeDefined();
+ expect(structural).toBeDefined();
+ // The old, misleading "Memory Database" (unqualified) name must be gone.
+ expect(data.results.some((r) => r.name === 'Memory Database')).toBe(false);
+ }, 20000);
+
+ it('healthy DB β†’ default `doctor` run passes, including the new structural check', async () => {
+ // Build a real, valid SQLite file via better-sqlite3 (same native module
+ // the check under test uses) so this is an authentic positive case.
+ const Database = (await import('better-sqlite3')).default as any;
+ mkdirSync(join(workdir, '.swarm'), { recursive: true });
+ const db = new Database(join(workdir, '.swarm', 'memory.db'));
+ db.exec('CREATE TABLE memory_entries (id INTEGER PRIMARY KEY, content TEXT)');
+ db.exec("INSERT INTO memory_entries (content) VALUES ('hello world')");
+ db.close();
+
+ const result = await runDoctor();
+ const data = result.data as DoctorData;
+ const structural = findCheck(data.results, 'Memory Structural Integrity');
+ expect(structural?.status).toBe('pass');
+ expect(structural?.message).toMatch(/quick_check: ok/);
+ expect(structural?.message).toMatch(/structural-only/);
+
+ const presence = findCheck(data.results, 'Memory Database Presence');
+ expect(presence?.status).toBe('pass');
+ }, 20000);
+
+ it('malformed/corrupt DB β†’ default `doctor` run FAILS the new structural check and does not report all-healthy', async () => {
+ // Garbage bytes at the memory.db path β€” not a SQLite file, not RFE1-encrypted.
+ plantDb(Buffer.from('this is definitely not a sqlite database, just garbage padding bytes to be safe'.repeat(3)));
+
+ const result = await runDoctor();
+ const data = result.data as DoctorData;
+ const structural = findCheck(data.results, 'Memory Structural Integrity');
+
+ // Core regression assertion: the old bug reported "pass" here (or the
+ // check was entirely absent from the default run). It must now be a
+ // hard `fail`, never `pass`, and never silently missing.
+ expect(structural).toBeDefined();
+ expect(structural?.status).toBe('fail');
+ expect(structural?.status).not.toBe('pass');
+
+ // And the wiring-gap regression: the overall doctor run must NOT report
+ // success/no-failures when a memory check has failed β€” this is exactly
+ // the "All checks passed! System is healthy." false-negative from #2737.
+ expect(data.failed).toBeGreaterThan(0);
+ expect(result.success).toBe(false);
+ expect(result.exitCode).toBe(1);
+
+ // The old, presence-only check must still just report the file exists β€”
+ // it is not being asked to change behavior, only to be honestly labeled.
+ const presence = findCheck(data.results, 'Memory Database Presence');
+ expect(presence?.status).toBe('pass');
+ }, 20000);
+
+ it('legitimately RFE1-encrypted-at-rest DB is NOT misclassified as corrupt', async () => {
+ // Build a real encrypted blob with the product's own vault primitives β€”
+ // this is exactly what an at-rest-encrypted memory.db looks like on disk.
+ const key = randomBytes(32);
+ const plaintext = Buffer.from('SQLite format 3\0'.padEnd(200, '\0'), 'binary');
+ const blob = encryptBuffer(plaintext, key);
+ plantDb(blob);
+
+ const result = await runDoctor();
+ const data = result.data as DoctorData;
+ const structural = findCheck(data.results, 'Memory Structural Integrity');
+
+ expect(structural).toBeDefined();
+ // Must NOT be a hard fail β€” encryption is expected, not corruption.
+ expect(structural?.status).not.toBe('fail');
+ expect(structural?.status).toBe('warn');
+ expect(structural?.message.toLowerCase()).toMatch(/encrypt/);
+ }, 20000);
+
+ it('`doctor --component memory` still runs the full #2677 trio unchanged', async () => {
+ const Database = (await import('better-sqlite3')).default as any;
+ mkdirSync(join(workdir, '.swarm'), { recursive: true });
+ const db = new Database(join(workdir, '.swarm', 'memory.db'));
+ db.exec('CREATE TABLE memory_entries (id INTEGER PRIMARY KEY, content TEXT)');
+ db.exec("INSERT INTO memory_entries (content) VALUES ('hello world')");
+ db.close();
+
+ const result = await runDoctor('memory');
+ const data = result.data as DoctorData;
+ const names = data.results.map((r) => r.name);
+
+ expect(names).toContain('Memory Database Presence');
+ expect(names).toContain('Memory Integrity');
+ expect(names).toContain('Memory Content');
+ expect(names).toContain('Memory Embedding Coverage');
+ // The new default-run-only check is deliberately NOT part of the deep
+ // --component memory suite (it's the cheap default-run probe, not a
+ // replacement for the trio).
+ expect(names.some((n) => n.includes('Memory Structural Integrity'))).toBe(false);
+ });
+
+ it('`doctor --component memory`: checkMemoryIntegrity fails (not warns) on a definitively malformed, unencrypted DB', async () => {
+ plantDb(Buffer.from('garbage not a database'.repeat(5)));
+ const result = await runDoctor('memory');
+ const data = result.data as DoctorData;
+ const integrity = findCheck(data.results, 'Memory Integrity');
+ expect(integrity?.status).toBe('fail');
+ });
+
+ it('`doctor --component memory`: checkMemoryIntegrity does not hard-fail a legitimately encrypted DB', async () => {
+ const key = randomBytes(32);
+ const plaintext = Buffer.from('SQLite format 3\0'.padEnd(200, '\0'), 'binary');
+ const blob = encryptBuffer(plaintext, key);
+ plantDb(blob);
+
+ const result = await runDoctor('memory');
+ const data = result.data as DoctorData;
+ const integrity = findCheck(data.results, 'Memory Integrity');
+ expect(integrity?.status).not.toBe('fail');
+ });
+});
diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.json
index d545038bfa..0aa2505bd2 100644
--- a/v3/@claude-flow/cli/package.json
+++ b/v3/@claude-flow/cli/package.json
@@ -115,6 +115,7 @@
"@claude-flow/security": "^3.0.0-alpha.12",
"agentdb": "^3.0.0-alpha.17",
"agentic-flow": "^3.0.0-alpha.1",
+ "better-sqlite3": "^12.9.0",
"ruvector": "^0.2.27"
},
"publishConfig": {
diff --git a/v3/@claude-flow/cli/src/commands/doctor.ts b/v3/@claude-flow/cli/src/commands/doctor.ts
index c1b4117037..d9036f0932 100644
--- a/v3/@claude-flow/cli/src/commands/doctor.ts
+++ b/v3/@claude-flow/cli/src/commands/doctor.ts
@@ -7,7 +7,7 @@
import type { Command, CommandContext, CommandResult } from '../types.js';
import { output } from '../output.js';
-import { existsSync, readFileSync, statSync } from 'fs';
+import { existsSync, readFileSync, statSync, openSync, readSync, closeSync } from 'fs';
import { join, dirname } from 'path';
import { fileURLToPath } from 'url';
import { createHash } from 'crypto';
@@ -238,6 +238,16 @@ async function checkDaemonStatus(): Promise<HealthCheck> {
}
// Check memory database
+//
+// #2737: renamed the reported row from "Memory Database" to "Memory Database
+// Presence" β€” this check is existsSync()+statSync() ONLY, it never opens the
+// file or queries it, so it PASSES for any file that exists and can be
+// stat'd, corrupt or not. It was the ONLY memory probe in the default
+// `allChecks` run (the real integrity checks were --component memory only),
+// so a corrupt .swarm/memory.db could sail through a bare `doctor` run as
+// "healthy". The name change makes the check's actual scope honest; the
+// behavior below is unchanged. See checkMemoryStructuralIntegrity below for
+// the new default-run check that actually opens the file.
async function checkMemoryDatabase(): Promise<HealthCheck> {
// Authoritative path comes from `getMemoryRoot()` (honors
// `CLAUDE_FLOW_MEMORY_PATH`, claude-flow.config.json's `memory.persistPath`,
@@ -264,14 +274,14 @@ async function checkMemoryDatabase(): Promise<HealthCheck> {
try {
const stats = statSync(dbPath);
const sizeMB = (stats.size / 1024 / 1024).toFixed(2);
- return { name: 'Memory Database', status: 'pass', message: `${dbPath} (${sizeMB} MB)` };
+ return { name: 'Memory Database Presence', status: 'pass', message: `${dbPath} (${sizeMB} MB) β€” existence/size only, not a health check (see Memory Structural Integrity)` };
} catch {
- return { name: 'Memory Database', status: 'warn', message: `${dbPath} (unable to stat)` };
+ return { name: 'Memory Database Presence', status: 'warn', message: `${dbPath} (unable to stat)` };
}
}
}
- return { name: 'Memory Database', status: 'warn', message: 'Not initialized', fix: 'claude-flow memory configure --backend hybrid' };
+ return { name: 'Memory Database Presence', status: 'warn', message: 'Not initialized', fix: 'claude-flow memory configure --backend hybrid' };
}
// ═══════════════════════════════════════════════════════════════════════════
@@ -329,44 +339,277 @@ async function tryOpenSqlJs(dbPath: string): Promise<any | null> {
} catch { return null; }
}
-// Check 1 β€” sql.js can open it AND PRAGMA integrity_check returns 'ok'.
-// Two fail modes handled distinctly per "UNKNOWN is never PASS":
-// - Open fails: warn ("cannot open; encrypted DB or corrupt β€” doctor
-// can't distinguish from this side")
-// - Open succeeds but pragma != 'ok': fail (definite corruption)
+// ── #2737 shared helpers: encryption-at-rest carve-out ─────────────────────
+//
+// "file is not a database" / "malformed" from sql.js or better-sqlite3 is
+// EXACTLY the signal a legitimately RFE1-encrypted-at-rest memory.db also
+// produces when opened without decrypting (ADR-096). Before either the new
+// default-run check or the strengthened checkMemoryIntegrity below concludes
+// "malformed = fail", they sniff for the RFE1 magic using the SAME detector
+// checkEncryptionAtRest uses (isEncryptedBlob), so the two checks can never
+// disagree about what counts as "encrypted".
+
+/** Read just the first `len` bytes of a file without loading the whole file
+ * into memory β€” a multi-GB memory.db shouldn't get fully buffered just to
+ * check a 4-byte magic. Returns fewer bytes (or empty) when the file is
+ * shorter than `len`; isEncryptedBlob() correctly treats a too-short blob
+ * as "not encrypted", so callers don't need to special-case that. */
+function readHeaderBytes(path: string, len: number): Buffer {
+ const fd = openSync(path, 'r');
+ try {
+ const buf = Buffer.alloc(len);
+ const bytesRead = readSync(fd, buf, 0, len, 0);
+ return buf.subarray(0, bytesRead);
+ } finally {
+ closeSync(fd);
+ }
+}
+
+// RFE1 wire format is magic(4) + iv(12) + ciphertext(N) + tag(16); the
+// shortest possible blob is 32 bytes. 64 gives headroom without importing
+// vault.ts's private MIN_BLOB_LEN constant.
+const ENCRYPTION_SNIFF_LEN = 64;
+
+/** True iff `dbPath` is a legitimately RFE1-encrypted-at-rest file. A read
+ * failure (permissions, races) is treated as "not encrypted" β€” callers
+ * still hit their own open/query error handling right after, so nothing
+ * gets silently swallowed. */
+function isMemoryDbEncryptedAtRest(dbPath: string): boolean {
+ try {
+ return isEncryptedBlob(readHeaderBytes(dbPath, ENCRYPTION_SNIFF_LEN));
+ } catch {
+ return false;
+ }
+}
+
+// #2737 part 1 β€” bare `doctor` (no --component flag) never actually opened
+// memory.db: checkMemoryDatabase above is existsSync()+statSync() only, so
+// it PASSES on any file that exists and can be stat'd, corrupt or not, and
+// it was the ONLY memory probe `allChecks` ran. The real integrity checks
+// (checkMemoryIntegrity/Content/EmbeddingCoverage below) were, and remain,
+// --component memory only.
+//
+// This is a NEW, cheaper, native check added to the default `allChecks` run
+// (not a replacement for the deep trio):
+// - better-sqlite3 (native) instead of sql.js: it's WAL-aware because
+// SQLite itself resolves any sibling -wal file next to the main image;
+// sql.js is WAL-blind β€” tryOpenSqlJs() above only readFileSync()s the
+// main file and hands the raw bytes to the WASM build, so any
+// committed-but-not-checkpointed rows sitting in a -wal file are
+// invisible to it.
+// - PRAGMA quick_check, not integrity_check: per sqlite.org, quick_check
+// "is like integrity_check except that it does not verify UNIQUE
+// constraints and does not verify that index content matches table
+// content" β€” bounded enough to run unconditionally on every bare
+// `doctor` call. The full integrity_check (with those extra
+// cross-checks) is what the strengthened checkMemoryIntegrity below
+// runs when better-sqlite3 is available.
+// Explicitly labeled "structural-only" in both the row name and every
+// message so nobody mistakes this cheap default-run probe for the deeper
+// --component memory one.
+async function checkMemoryStructuralIntegrity(): Promise<HealthCheck> {
+ const NAME = 'Memory Structural Integrity (quick_check)';
+ const dbPath = await resolveMemoryDbPath();
+ if (!dbPath) {
+ // Not-yet-initialized project β€” Memory Database Presence above already
+ // surfaces this; "UNKNOWN is never PASS" still applies, so this stays a
+ // warn rather than a silent skip, but doesn't pile on a second red for
+ // the same root cause.
+ return {
+ name: NAME,
+ status: 'warn',
+ message: 'no memory.db found (see Memory Database Presence above) β€” structural-only check skipped',
+ };
+ }
+
+ // Encryption-at-rest carve-out (#2737 part 3) β€” see helpers above.
+ if (isMemoryDbEncryptedAtRest(dbPath)) {
+ return {
+ name: NAME,
+ status: 'warn',
+ message: `${dbPath} β€” RFE1-encrypted at rest; structural-only check can't run without decrypting (expected, not corruption β€” see Encryption at Rest)`,
+ };
+ }
+
+ let Database: any;
+ try {
+ Database = ((await import('better-sqlite3')) as any).default;
+ } catch {
+ return {
+ name: NAME,
+ status: 'warn',
+ message: `${dbPath} β€” better-sqlite3 not installed; structural-only check skipped (optional native module)`,
+ fix: 'npm install better-sqlite3 (enables WAL-aware structural checks on every `doctor` run)',
+ };
+ }
+
+ let db: any;
+ try {
+ db = new Database(dbPath, { readonly: true, fileMustExist: true });
+ } catch (e) {
+ const msg = (e as Error).message || String(e);
+ // Encryption already ruled out above β€” an unencrypted file
+ // better-sqlite3 can't even open is definitive corruption.
+ // #2737 part 3: fail, not warn.
+ return {
+ name: NAME,
+ status: 'fail',
+ message: `${dbPath} β€” better-sqlite3 failed to open: ${msg} (unencrypted; definitively malformed) [structural-only]`,
+ fix: 'back up .swarm/memory.db then `claude-flow memory init --force`',
+ };
+ }
+
+ try {
+ const rows = db.pragma('quick_check') as Array<Record<string, unknown>>;
+ const values = rows.map((r) => String(Object.values(r)[0]));
+ if (values.length === 1 && values[0] === 'ok') {
+ return {
+ name: NAME,
+ status: 'pass',
+ message: `${dbPath} β€” PRAGMA quick_check: ok [structural-only, native + WAL-aware]`,
+ };
+ }
+ return {
+ name: NAME,
+ status: 'fail',
+ message: `${dbPath} β€” PRAGMA quick_check: ${values.slice(0, 3).join('; ')}${values.length > 3 ? ` (+${values.length - 3} more)` : ''} [structural-only]`,
+ fix: 'back up .swarm/memory.db then `claude-flow memory init --force`',
+ };
+ } catch (e) {
+ const msg = (e as Error).message || String(e);
+ // Encryption ruled out above; DB opened but the pragma itself threw β€”
+ // still definitive, unencrypted breakage. Fail, not warn.
+ return {
+ name: NAME,
+ status: 'fail',
+ message: `${dbPath} β€” quick_check probe threw: ${msg} (unencrypted) [structural-only]`,
+ fix: 'back up .swarm/memory.db then `claude-flow memory init --force`',
+ };
+ } finally {
+ try { db.close(); } catch { /* best-effort */ }
+ }
+}
+
+// Check 1 (--component memory, deep path) β€” #2737 part 2 strengthens this:
+// prefer native better-sqlite3 PRAGMA integrity_check (adds index↔table
+// cross-checking + UNIQUE verification that quick_check above deliberately
+// skips, and is WAL-aware β€” see checkMemoryStructuralIntegrity's comment)
+// when better-sqlite3 is available, falling back to the original sql.js
+// probe when it's not. The sql.js fallback is main-image-only (WAL-blind);
+// its message says so explicitly so operators know its limits.
+//
+// #2737 part 3: with the encryption carve-out applied up front on BOTH
+// paths, a "file is not a database" / "malformed" result is now definitive,
+// unencrypted corruption in every branch below β€” fail, not warn (the
+// previous version treated this as an ambiguous warn because it couldn't
+// tell corruption from encryption; that ambiguity is what the carve-out
+// resolves).
async function checkMemoryIntegrity(): Promise<HealthCheck> {
const dbPath = await resolveMemoryDbPath();
- if (!dbPath) return { name: 'Memory Integrity', status: 'warn', message: 'no memory.db found (see Memory Database check above)' };
+ if (!dbPath) return { name: 'Memory Integrity', status: 'warn', message: 'no memory.db found (see Memory Database Presence check above)' };
+
+ if (isMemoryDbEncryptedAtRest(dbPath)) {
+ return {
+ name: 'Memory Integrity',
+ status: 'warn',
+ message: `${dbPath} β€” RFE1-encrypted at rest; integrity check can't run without decrypting (expected, not corruption β€” see Encryption at Rest)`,
+ };
+ }
+
+ // Prefer native better-sqlite3 (WAL-aware, full integrity_check). Module
+ // load is isolated in its own try/catch so ONLY "not installed" falls
+ // through to the sql.js fallback below β€” once the module loaded, any
+ // open/query failure is resolved (fail) right here, not silently
+ // reclassified as "sql.js fallback, main-image-only" by an outer catch.
+ let Database: any;
+ try {
+ Database = ((await import('better-sqlite3')) as any).default;
+ } catch {
+ Database = null; // not installed β€” fall through to the sql.js fallback below.
+ }
+
+ if (Database) {
+ let db: any;
+ try {
+ db = new Database(dbPath, { readonly: true, fileMustExist: true });
+ } catch (e) {
+ const msg = (e as Error).message || String(e);
+ return {
+ name: 'Memory Integrity',
+ status: 'fail',
+ message: `${dbPath} β€” better-sqlite3 failed to open: ${msg} (unencrypted; definitively malformed) [native, WAL-aware]`,
+ fix: 'back up .swarm/memory.db then `claude-flow memory init --force`',
+ };
+ }
+ try {
+ const rows = db.pragma('integrity_check') as Array<Record<string, unknown>>;
+ const values = rows.map((r) => String(Object.values(r)[0]));
+ if (values.length === 1 && values[0] === 'ok') {
+ return { name: 'Memory Integrity', status: 'pass', message: `${dbPath} β€” PRAGMA integrity_check: ok [native, WAL-aware]` };
+ }
+ return {
+ name: 'Memory Integrity',
+ status: 'fail',
+ message: `${dbPath} β€” PRAGMA integrity_check: ${values.slice(0, 3).join('; ')}${values.length > 3 ? ` (+${values.length - 3} more)` : ''} [native, WAL-aware]`,
+ fix: 'back up .swarm/memory.db then `claude-flow memory init --force`',
+ };
+ } catch (e) {
+ // DB opened but the pragma itself threw β€” still definitive,
+ // unencrypted breakage (encryption ruled out above). Fail, not warn,
+ // and NOT a fall-through to the sql.js fallback: better-sqlite3 IS
+ // installed and just gave us the answer.
+ const msg = (e as Error).message || String(e);
+ return {
+ name: 'Memory Integrity',
+ status: 'fail',
+ message: `${dbPath} β€” integrity_check probe threw: ${msg} (unencrypted; definitively malformed) [native, WAL-aware]`,
+ fix: 'back up .swarm/memory.db then `claude-flow memory init --force`',
+ };
+ } finally {
+ try { db.close(); } catch { /* best-effort */ }
+ }
+ }
+
+ // Fallback: sql.js β€” main-image-only (WAL-blind). tryOpenSqlJs()
+ // readFileSync()s the base file directly, so any committed-but-not-
+ // checkpointed rows sitting in a sibling -wal file are invisible here.
+ // Install better-sqlite3 for the WAL-aware path above.
const db = await tryOpenSqlJs(dbPath);
if (!db) {
+ // Encryption already ruled out above β€” an unencrypted file sql.js can't
+ // even open is definitive corruption too.
return {
name: 'Memory Integrity',
- status: 'warn',
- message: `${dbPath} β€” sql.js can't open (encrypted DB or corrupt; doctor can't tell which from outside)`,
- fix: 'if encrypted: expected. if not: back up + `claude-flow memory init --force` to rebuild',
+ status: 'fail',
+ message: `${dbPath} β€” sql.js can't open (unencrypted; definitively malformed) [main-image-only fallback β€” install better-sqlite3 for WAL-aware checking]`,
+ fix: 'back up .swarm/memory.db then `claude-flow memory init --force`',
};
}
try {
const res = db.exec('PRAGMA integrity_check');
const rows: string[] = res[0]?.values?.map((v: any[]) => String(v[0])) ?? [];
if (rows.length === 1 && rows[0] === 'ok') {
- return { name: 'Memory Integrity', status: 'pass', message: `${dbPath} β€” PRAGMA integrity_check: ok` };
+ return { name: 'Memory Integrity', status: 'pass', message: `${dbPath} β€” PRAGMA integrity_check: ok [main-image-only fallback β€” sql.js can't see WAL-only data; install better-sqlite3 for full coverage]` };
}
return {
name: 'Memory Integrity',
status: 'fail',
- message: `${dbPath} β€” PRAGMA integrity_check: ${rows.slice(0, 3).join('; ')}${rows.length > 3 ? ` (+${rows.length - 3} more)` : ''}`,
+ message: `${dbPath} β€” PRAGMA integrity_check: ${rows.slice(0, 3).join('; ')}${rows.length > 3 ? ` (+${rows.length - 3} more)` : ''} [main-image-only fallback]`,
fix: 'back up .swarm/memory.db then `claude-flow memory init --force`',
};
} catch (e) {
const msg = (e as Error).message || String(e);
- const encryptedOrCorrupt = msg.includes('file is not a database') || msg.includes('malformed');
+ const definitivelyMalformed = msg.includes('file is not a database') || msg.includes('malformed');
+ // Encryption already ruled out above, so β€” matched pattern or not β€”
+ // this is a query refusal on a file we KNOW isn't RFE1-encrypted.
+ // #2737 part 3: fail, not warn.
return {
name: 'Memory Integrity',
- status: 'warn',
- message: encryptedOrCorrupt
- ? `${dbPath} β€” DB refused query: ${msg} (encrypted DB or corruption; see Memory Integrity above)`
- : `${dbPath} β€” probe threw: ${msg}`,
+ status: 'fail',
+ message: definitivelyMalformed
+ ? `${dbPath} β€” DB refused query: ${msg} (unencrypted; definitively malformed) [main-image-only fallback]`
+ : `${dbPath} β€” probe threw: ${msg} (unencrypted β€” encryption ruled out above) [main-image-only fallback]`,
+ fix: 'back up .swarm/memory.db then `claude-flow memory init --force`',
};
} finally { try { db.close(); } catch { /* best-effort */ } }
}
@@ -1770,6 +2013,7 @@ export const doctorCommand: Command = {
checkStaleSettingsNpx, // #2448 β€” runaway `npx @latest` in statusLine/hooks
checkDaemonStatus,
checkMemoryDatabase,
+ checkMemoryStructuralIntegrity, // #2737 β€” bounded, native quick_check on every default run
checkLearningBridge, // #2545 β€” can the auto-memory hook actually load @claude-flow/memory?
checkApiKeys,
checkMcpServers,
diff --git a/v3/@claude-flow/cli/src/types/optional-modules.d.ts b/v3/@claude-flow/cli/src/types/optional-modules.d.ts
index c607c1e072..706d9db9d1 100644
--- a/v3/@claude-flow/cli/src/types/optional-modules.d.ts
+++ b/v3/@claude-flow/cli/src/types/optional-modules.d.ts
@@ -19,6 +19,26 @@ declare module 'sql.js' {
export default initSqlJs;
}
+// #2737 β€” native, WAL-aware SQLite bindings. Optional: doctor's default-run
+// structural check and the strengthened `--component memory` integrity
+// check both prefer this over sql.js when it's installed, falling back to
+// sql.js (main-image-only / WAL-blind) when it's not.
+declare module 'better-sqlite3' {
+ interface DatabaseOptions {
+ readonly?: boolean;
+ fileMustExist?: boolean;
+ timeout?: number;
+ verbose?: (message?: unknown, ...additionalArgs: unknown[]) => void;
+ }
+ class Database {
+ constructor(filename: string, options?: DatabaseOptions);
+ pragma(source: string, options?: { simple?: boolean }): any;
+ close(): void;
+ readonly open: boolean;
+ }
+ export default Database;
+}
+
declare module 'agentic-flow' {
export const reasoningbank: any;
}
diff --git a/v3/pnpm-lock.yaml b/v3/pnpm-lock.yaml
index 9b5bd7be7f..0e2771e35b 100644
--- a/v3/pnpm-lock.yaml
+++ b/v3/pnpm-lock.yaml
@@ -153,6 +153,9 @@ importers:
agentic-flow:
specifier: ^3.0.0-alpha.1
version: 3.0.0-alpha.2
+ better-sqlite3:
+ specifier: ^12.9.0
+ version: 12.9.0
ruvector:
specifier: ^0.2.27
version: 0.2.27([email protected])