fix(doctor): wire real memory-DB integrity checks into the default doctor run

[ruvnet]

Summary

Fixes #2737.

@claude-flow/cli's doctor command has real memory-database integrity checks (checkMemoryIntegrity, checkMemoryContent, checkMemoryEmbeddingCoverage — added for #2677), but they were registered only 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 wiring gap

• allChecks (default run): only checkMemoryDatabase (existence/size only).
• componentMap['memory'] (--component memory only): the full doctor: --component memory asserts existence, not function — passes a store that is 99.97% empty (and one SQLite calls malformed) #2677 trio.

Three-part fix

1. New default-run check — checkMemoryStructuralIntegrity, added to allChecks. Uses native better-sqlite3 (WAL-aware — SQLite resolves the sibling -wal file itself; the existing sql.js checks are WAL-blind because they only readFileSync() the main db image) and runs PRAGMA quick_check (bounded — per sqlite.org it skips UNIQUE/index-vs-table cross-checks that integrity_check does, cheap enough to run unconditionally). Explicitly labeled "structural-only" in both the row name and every message so it's never confused with the deeper --component memory probe. checkMemoryDatabase's reported row is relabeled "Memory Database Presence" to be honest about its existence-only scope — behavior unchanged, it stays in allChecks too.

2. Strengthened checkMemoryIntegrity (deep path, --component memory only — the full doctor: --component memory asserts existence, not function — passes a store that is 99.97% empty (and one SQLite calls malformed) #2677 trio stays there, unchanged in registration). Now prefers native better-sqlite3 PRAGMA integrity_check (adds the index↔table + UNIQUE verification quick_check skips, and is WAL-aware) when better-sqlite3 is installed, falling back to the original sql.js probe — now explicitly labeled "main-image-only" (WAL-blind) — when it's not.

3. Definitive corruption now fails, not warns — in both checks, a "file is not a database" / "malformed" result now maps to fail, WITH an encryption-at-rest carve-out: before concluding "malformed," both checks sniff the file for the product's RFE1 magic bytes (reusing isEncryptedBlob() from encryption/vault.ts — the exact same detector checkEncryptionAtRest uses), so a legitimately encrypted-at-rest DB is never misclassified as corrupt.

better-sqlite3 is added to @claude-flow/cli's optionalDependencies (matching the existing pattern in @claude-flow/memory and @claude-flow/hooks), with an ambient module declaration in optional-modules.d.ts. Every code path that touches it degrades gracefully (sql.js fallback, or a warn) on MODULE_NOT_FOUND — never a silent pass.

What I deliberately did not touch

• agentdb_health / memory_stats — out of scope per the issue, tracked separately.
• doctor --fix's behavior beyond inheriting the new default check (it already runs allChecks).
• The ruflo-doctor skill/plugin docs.
• checkMemoryContent / checkMemoryEmbeddingCoverage — kept exactly as-is; checkMemoryIntegrity failing hard is enough to prevent a false "all healthy" (checks are ordered so the earliest chain-break is the first red the user sees).

Test plan

• New __tests__/doctor-2737-memory-structural.test.ts (7 cases), driven through doctorCommand.action() (the real entry point, not the check functions in isolation):
  • Healthy DB (built with real better-sqlite3) → default doctor run passes, including the new check.
  • Malformed DB (garbage bytes) → new check reports fail; overall run reports failed > 0, success: false, exitCode: 1 — never the "all healthy" false negative.
  • A real RFE1-encrypted blob (built with the product's own encryptBuffer) is not misclassified as corrupt.
  • --component memory still runs the full, unchanged 4-check trio; the new default-run check is deliberately absent from it.
  • checkMemoryIntegrity directly: fails on malformed+unencrypted, does not hard-fail on legitimately-encrypted.
• Full existing doctor-*.test.ts suite (19 tests total) still passes — no regressions.
• Manual repro: node bin/cli.js doctor against a scratch dir with a garbage .swarm/memory.db:

  ✓ Memory Database Presence: ...\.swarm\memory.db (0.00 MB) — existence/size only, not a health check (see Memory Structural Integrity)
  ✗ Memory Structural Integrity (quick_check): ...\.swarm\memory.db — quick_check probe threw: file is not a database (unencrypted) [structural-only]
  Summary: 13 passed, 11 warnings, 1 failed
  Some checks failed. Please address the issues above.
  

  Process exit code: 1 (previously: silent pass via checkMemoryDatabase, exit 0, "All checks passed! System is healthy.").
  Re-verified against a valid DB (exit 0, quick_check: ok) and via --component memory (full trio, native integrity_check path confirmed with [native, WAL-aware] in the message).

Note: while manually verifying --component memory end-to-end via the compiled CLI binary, I hit a libuv assertion crash (Assertion failed: !(handle->flags & UV_HANDLE_CLOSING), src\win\async.c) on process exit in this sandbox. I confirmed it reproduces identically on unmodified main (stashed my diff, rebuilt, same crash) — it's a pre-existing Windows/Node-24/native-module environment issue in this sandbox, not something this change introduces, and unrelated to the actual check logic (which completes and prints correct results before the crash occurs during teardown).

🤖 Generated with RuFlo