@remnic/core 9.4.0 → 9.4.2

package/src/memory-projection-open-failure.test.ts

@@ -0,0 +1,322 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { initLogger } from "./logger.js";
+import { rebuildMemoryProjection } from "./maintenance/rebuild-memory-projection.js";
+import {
+  __resetProjectionOpenFailureSuppressionForTest,
+  __setProjectionReadonlyOpenerForTest,
+  getMemoryProjectionPath,
+  probeProjectionHealth,
+  readProjectedMemoryBrowse,
+} from "./memory-projection-store.js";
+import { summarizeProjectionHealth } from "./operator-toolkit.js";
+import { openBetterSqlite3 } from "./runtime/better-sqlite.js";
+import { StorageManager } from "./storage.js";
+
+// Serialized: every test mutates the process-global logger backend and the
+// module-level projection opener / rate-limit map. concurrency:false keeps
+// them from racing each other.
+const SERIAL = { concurrency: false } as const;
+
+// The opener seam expects the real opener signature; derive it without
+// importing the (unexported) alias.
+type ProjectionOpener = NonNullable<Parameters<typeof __setProjectionReadonlyOpenerForTest>[0]>;
+
+function abiStyleError(): Error {
+  // Mirrors the real native-binding mismatch better-sqlite3 throws when its
+  // addon was compiled for a different Node.js ABI (issue #1829 root cause).
+  // Classified as a native mismatch by isLikelyBetterSqlite3NativeBindingError.
+  return new Error(
+    "The module was compiled against a different Node.js version using NODE_MODULE_VERSION 127. " +
+      "This version of Node.js requires NODE_MODULE_VERSION 137."
+  );
+}
+
+function captureLogs(): { warns: string[]; errors: string[]; restore: () => void } {
+  const warns: string[] = [];
+  const errors: string[] = [];
+  initLogger({
+    info() {},
+    warn(msg) {
+      warns.push(msg);
+    },
+    error(msg) {
+      errors.push(msg);
+    },
+    debug() {},
+  });
+  return { warns, errors, restore: () => initLogger() };
+}
+
+test("absent projection index → quiet fallback, no error log, probe reports absent", SERIAL, async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-proj-absent-"));
+  const { warns, restore } = captureLogs();
+  try {
+    // No projection file exists — the normal cold-install / never-built case.
+    assert.equal(probeProjectionHealth(dir).state, "absent");
+    assert.equal(readProjectedMemoryBrowse(dir, { limit: 5, offset: 0 }), null);
+    // The distinguishing guarantee from issue #1829: a MISSING file must stay
+    // quiet (no error spam). Only a PRESENT-but-unopenable file logs.
+    assert.equal(warns.length, 0);
+  } finally {
+    restore();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("present index + ABI-style open failure → distinct rate-limited warn + null + doctor signal", SERIAL, async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-proj-abi-"));
+  const { warns, restore } = captureLogs();
+  __resetProjectionOpenFailureSuppressionForTest();
+  try {
+    // Build a real projection so the index file genuinely EXISTS on disk;
+    // then inject an opener that throws the wrong-ABI error on every open.
+    await rebuildMemoryProjection({ memoryDir: dir, dryRun: false });
+    assert.ok(getMemoryProjectionPath(dir));
+    const throwingOpener: ProjectionOpener = () => {
+      throw abiStyleError();
+    };
+    const restoreOpener = __setProjectionReadonlyOpenerForTest(throwingOpener);
+
+    try {
+      // The read path returns null (full-scan fallback trigger preserved),
+      // but now emits the DISTINCT real-error warn that was missing before.
+      const first = readProjectedMemoryBrowse(dir, { limit: 5, offset: 0 });
+      assert.equal(first, null);
+      assert.equal(warns.length, 1);
+      const msg = warns[0];
+      assert.ok(msg, "expected a distinct projection open-failure warn");
+      assert.match(msg, /present but could not be opened/);
+      assert.match(msg, /wrong Node\.js ABI/);
+
+      // Doctor lens classifies the same failure.
+      const probe = probeProjectionHealth(dir);
+      assert.equal(probe.state, "unopenable");
+      assert.equal(probe.nativeBindingMismatch, true);
+
+      // Rate limit: a second open within the window is suppressed.
+      const second = readProjectedMemoryBrowse(dir, { limit: 5, offset: 0 });
+      assert.equal(second, null);
+      assert.equal(warns.length, 1, "rate limit must suppress the repeat warn");
+
+      // After resetting suppression, the warn fires again.
+      __resetProjectionOpenFailureSuppressionForTest();
+      readProjectedMemoryBrowse(dir, { limit: 5, offset: 0 });
+      assert.equal(warns.length, 2, "warn fires again after suppression reset");
+    } finally {
+      restoreOpener();
+    }
+  } finally {
+    restore();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("present index + WRAPPED ABI open failure (cause = native-binding error) → still reports the native-binding hint", SERIAL, async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-proj-wrapped-abi-"));
+  const { warns, restore } = captureLogs();
+  __resetProjectionOpenFailureSuppressionForTest();
+  try {
+    await rebuildMemoryProjection({ memoryDir: dir, dryRun: false });
+    // Mirrors the production path: loadBetterSqlite3() catches the ABI error
+    // and re-throws a sanitized unavailableError WRAPPER whose message drops
+    // the ABI markers. The original error survives only on .cause. Before
+    // #1848 the classifier inspected only the wrapper's message and MISSED the
+    // mismatch, so the warn and doctor check wrongly suggested rebuilding the
+    // projection instead of better-sqlite3.
+    const throwingOpener: ProjectionOpener = () => {
+      throw new Error(
+        "better-sqlite3 is unavailable. Remnic attempted to load the native SQLite binding and could not.",
+        { cause: abiStyleError() },
+      );
+    };
+    const restoreOpener = __setProjectionReadonlyOpenerForTest(throwingOpener);
+
+    try {
+      // Browse warn carries the native-binding ABI hint (not the projection-rebuild hint).
+      const first = readProjectedMemoryBrowse(dir, { limit: 5, offset: 0 });
+      assert.equal(first, null);
+      assert.equal(warns.length, 1);
+      assert.match(warns[0], /wrong Node\.js ABI/);
+      assert.doesNotMatch(warns[0], /rebuild-memory-projection/);
+
+      // Doctor lens classifies the SAME wrapped failure as a native-binding mismatch.
+      const probe = probeProjectionHealth(dir);
+      assert.equal(probe.state, "unopenable");
+      assert.equal(probe.nativeBindingMismatch, true);
+    } finally {
+      restoreOpener();
+    }
+  } finally {
+    restore();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("present index + non-ABI open failure → distinct warn without the native-binding hint", SERIAL, async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-proj-cantopen-"));
+  const { warns, restore } = captureLogs();
+  __resetProjectionOpenFailureSuppressionForTest();
+  try {
+    await rebuildMemoryProjection({ memoryDir: dir, dryRun: false });
+    // A corrupt-file / permission style failure: carries a stable SQLite
+    // code but is NOT a native-binding mismatch. Tests the failure CLASS,
+    // not just the reported ABI instance (hardening playbook).
+    const cantOpen = Object.assign(new Error("unable to open database file"), {
+      code: "SQLITE_CANTOPEN",
+    });
+    const restoreOpener = __setProjectionReadonlyOpenerForTest((() => {
+      throw cantOpen;
+    }) as ProjectionOpener);
+    try {
+      assert.equal(readProjectedMemoryBrowse(dir, { limit: 5, offset: 0 }), null);
+      assert.equal(warns.length, 1);
+      const msg = warns[0];
+      assert.ok(msg, "expected a distinct projection open-failure warn");
+      assert.match(msg, /present but could not be opened/);
+      assert.match(msg, /SQLITE_CANTOPEN/);
+      assert.doesNotMatch(msg, /native binding/);
+      const probe = probeProjectionHealth(dir);
+      assert.equal(probe.state, "unopenable");
+      assert.equal(probe.nativeBindingMismatch, false);
+    } finally {
+      restoreOpener();
+    }
+  } finally {
+    restore();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("full-scan fallback still returns results when the projection cannot serve", SERIAL, async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-proj-fullscan-"));
+  const { restore } = captureLogs();
+  try {
+    const storage = new StorageManager(dir);
+    const a = await storage.writeMemory("fact", "alpha synthetic fact", { source: "test" });
+    const b = await storage.writeMemory("fact", "beta synthetic fact", { source: "test" });
+
+    // Absent projection: the browse returns null (the trigger the access
+    // layer keys on to run its full-corpus scan) ...
+    assert.equal(readProjectedMemoryBrowse(dir, { limit: 10, offset: 0 }), null);
+
+    // ... and the full-corpus data source the access layer scans still
+    // holds every memory (issue #1829: the fallback must keep serving).
+    const full = [...(await storage.readAllMemories()), ...(await storage.readArchivedMemories())];
+    const ids = new Set(full.map((m) => m.frontmatter.id));
+    assert.ok(ids.has(a.id));
+    assert.ok(ids.has(b.id));
+    assert.equal(full.length, 2);
+
+    // Regression guard for the exact #1829 failure: build the projection,
+    // then make it unopenable, and confirm the null trigger STILL fires so
+    // the full scan is reached (not a throw, not a stale cached page).
+    await rebuildMemoryProjection({ memoryDir: dir, dryRun: false });
+    const restoreOpener = __setProjectionReadonlyOpenerForTest((() => {
+      throw abiStyleError();
+    }) as ProjectionOpener);
+    try {
+      assert.equal(
+        readProjectedMemoryBrowse(dir, { limit: 10, offset: 0 }),
+        null,
+        "unopenable projection must return null so the full scan runs"
+      );
+    } finally {
+      restoreOpener();
+    }
+  } finally {
+    restore();
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("present + valid projection → probe openable + doctor ok (schema validation passes)", SERIAL, async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-proj-healthy-"));
+  try {
+    await rebuildMemoryProjection({ memoryDir: dir, dryRun: false });
+    const probe = probeProjectionHealth(dir);
+    assert.equal(probe.state, "openable");
+    assert.equal(probe.nativeBindingMismatch, false);
+    // Doctor lens reports OK for a schema-valid projection (issue #1848 round 2).
+    const check = summarizeProjectionHealth({ memoryDir: dir });
+    assert.equal(check.status, "ok");
+    assert.match(check.summary, /opens cleanly/i);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("present projection with MISSING schema tables → probe present-but-invalid (doctor non-ok, rebuild hint)", SERIAL, async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-proj-no-tables-"));
+  try {
+    // Create a sqlite file that OPENS cleanly but has NO projection tables
+    // (mirrors a half-built / stale / externally-created .sqlite that opens
+    // but cannot serve any browse query — issue #1848 round 2 root cause).
+    const dbPath = getMemoryProjectionPath(dir);
+    await mkdir(path.dirname(dbPath), { recursive: true });
+    const empty = openBetterSqlite3(dbPath); // creates a valid empty db
+    empty.close();
+
+    // Before #1848 round 2 this reported "openable" → doctor said ok while
+    // browse silently fell back to full-corpus scans on every memory list.
+    const probe = probeProjectionHealth(dir);
+    assert.equal(probe.state, "present-but-invalid");
+    assert.equal(probe.nativeBindingMismatch, false);
+    assert.ok(probe.detail, "expected a path-free detail for the schema failure");
+
+    // Doctor lens surfaces this as an ERROR with a rebuild hint — NOT ok.
+    const check = summarizeProjectionHealth({ memoryDir: dir });
+    assert.equal(check.status, "error");
+    assert.match(check.summary, /missing or unreadable/i);
+    assert.ok(check.remediation);
+    assert.match(check.remediation, /rebuild-memory-projection/);
+
+    // Browse still returns null (full-scan fallback trigger) — the projection
+    // is unusable, so the access layer must reach the full corpus.
+    assert.equal(readProjectedMemoryBrowse(dir, { limit: 5, offset: 0 }), null);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});
+
+test("present projection with memory_current MISSING required columns → probe present-but-invalid (doctor non-ok, rebuild hint)", SERIAL, async () => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "remnic-proj-no-cols-"));
+  try {
+    // A sqlite file that opens cleanly AND has a `memory_current` table, but
+    // the table is stale/half-built with none of the columns
+    // readProjectedMemoryBrowse SELECTs (issue #1848 round 3 root cause). The
+    // round-2 check only verified the table exists + answers `SELECT 1`, so a
+    // file like `CREATE TABLE memory_current (x INTEGER)` was reported
+    // "openable" → doctor said healthy while browse threw on the missing
+    // memory_id/path_rel/category/... columns and silently fell back.
+    const dbPath = getMemoryProjectionPath(dir);
+    await mkdir(path.dirname(dbPath), { recursive: true });
+    const stale = openBetterSqlite3(dbPath); // creates a valid db
+    stale.exec("CREATE TABLE memory_current (x INTEGER)");
+    stale.close();
+
+    // Before round 3 this reported "openable" → doctor said ok.
+    const probe = probeProjectionHealth(dir);
+    assert.equal(probe.state, "present-but-invalid");
+    assert.equal(probe.nativeBindingMismatch, false);
+    // displayErrorDetail surfaces only the path-free error class (ProjectionSchemaError).
+    assert.ok(probe.detail, "expected a path-free detail for the missing-column schema failure");
+
+    // Doctor lens surfaces this as an ERROR with a rebuild hint — NOT ok.
+    const check = summarizeProjectionHealth({ memoryDir: dir });
+    assert.equal(check.status, "error");
+    assert.match(check.summary, /missing or unreadable/i);
+    assert.ok(check.remediation);
+    assert.match(check.remediation, /rebuild-memory-projection/);
+
+    // Browse still returns null (full-scan fallback trigger) — the projection
+    // cannot serve queries missing the browse columns.
+    assert.equal(readProjectedMemoryBrowse(dir, { limit: 5, offset: 0 }), null);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+});

package/src/memory-projection-store.ts

@@ -12,7 +12,10 @@ import type {
   MemoryProjectionCurrentState,
   MemoryStatus,
 } from "./types.js";
+import { log } from "./logger.js";
 import {
+  displayErrorDetail,
+  isLikelyBetterSqlite3NativeBindingError,
   openBetterSqlite3,
   type BetterSqlite3Database,
 } from "./runtime/better-sqlite.js";
@@ -314,14 +317,188 @@ export function initializeMemoryProjectionDb(db: BetterSqlite3Database): void {
     .run("schemaVersion", String(MEMORY_PROJECTION_SCHEMA_VERSION));
 }
 
+// Test seam (issue #1829): the readonly projection opener is overridable so
+// tests can inject an ABI-style throw against a PRESENT file without faking a
+// corrupt native binding. Default delegates to the shared opener.
+type ProjectionReadonlyOpener = typeof openBetterSqlite3;
+let projectionReadonlyOpener: ProjectionReadonlyOpener = openBetterSqlite3;
+
+/** @internal Test seam: override the readonly projection opener; returns a restore fn. */
+export function __setProjectionReadonlyOpenerForTest(
+  opener: ProjectionReadonlyOpener | null,
+): () => void {
+  const previous = projectionReadonlyOpener;
+  projectionReadonlyOpener = opener ?? openBetterSqlite3;
+  return () => {
+    projectionReadonlyOpener = previous;
+  };
+}
+
+// Rate-limited suppression for open failures — mirrors warnProjectionFallback
+// in storage-guards.ts (5-min dedup per memoryDir). A present-but-unopenable
+// projection is a real failure that must surface, but it repeats on every
+// browse, so the log is throttled to keep output actionable (issue #1829).
+const PROJECTION_OPEN_FAILURE_LOG_INTERVAL_MS = 5 * 60_000;
+const projectionOpenFailureLoggedAt = new Map<string, number>();
+
+/** @internal Test seam: clear the rate-limit dedup map. */
+export function __resetProjectionOpenFailureSuppressionForTest(): void {
+  projectionOpenFailureLoggedAt.clear();
+}
+
+function logProjectionOpenFailure(memoryDir: string, error: unknown): void {
+  const now = Date.now();
+  const warnedAt = projectionOpenFailureLoggedAt.get(memoryDir) ?? 0;
+  if (now - warnedAt < PROJECTION_OPEN_FAILURE_LOG_INTERVAL_MS) return;
+  projectionOpenFailureLoggedAt.set(memoryDir, now);
+  // Path-free detail only (rule 11 / CodeQL js/stack-trace-exposure): the raw
+  // message can embed absolute loader paths; displayErrorDetail returns class +
+  // code. This is the DISTINCT signal that was missing before #1829, when a
+  // wrong-ABI build collapsed into the same silent null as a missing file.
+  const detail = displayErrorDetail(error);
+  const nativeMismatch = isLikelyBetterSqlite3NativeBindingError(error);
+  const detailSuffix = detail ? ` (${detail})` : "";
+  const abiSuffix = nativeMismatch
+    ? " — native binding built for the wrong Node.js ABI; rebuild better-sqlite3 for this process"
+    : "";
+  log.warn(
+    `storage.memory-projection: index present but could not be opened${detailSuffix}${abiSuffix}; falling back to full-corpus scan`,
+  );
+}
+
 function openProjectionReadonly(memoryDir: string): BetterSqlite3Database | null {
   const dbPath = getMemoryProjectionPath(memoryDir);
+  // A MISSING file is a normal fallback (cold install, never built). A file
+  // that EXISTS but cannot open (wrong ABI / corrupt / bad perms) is a real
+  // failure that must surface (issue #1829): previously both collapsed into
+  // the same silent null, hiding native-binding mismatches behind 17-27s
+  // full-corpus scans on every memory list.
+  if (!fs.existsSync(dbPath)) return null;
   try {
-    return openBetterSqlite3(dbPath, { readonly: true, fileMustExist: true });
-  } catch {
+    return projectionReadonlyOpener(dbPath, { readonly: true, fileMustExist: true });
+  } catch (error) {
+    logProjectionOpenFailure(memoryDir, error);
     return null;
   }
 }
+
+export type ProjectionHealthState = "absent" | "openable" | "present-but-invalid" | "unopenable";
+
+export interface ProjectionHealthProbe {
+  state: ProjectionHealthState;
+  /** Path-free detail (class + code) when state !== "absent"/"openable"; "" otherwise. */
+  detail: string;
+  /** true when the open failure is classified as a native-binding ABI mismatch. */
+  nativeBindingMismatch: boolean;
+}
+
+/**
+ * Confirm the projection schema is present and queryable, not just that the
+ * sqlite file opens (issue #1848 round 2). A file that opens but has the
+ * projection tables missing — or is corrupt and only fails on first statement
+ * — previously reported `openable`/ok, so `remnic doctor` said healthy while
+ * browse silently fell back to full-corpus scans. `memory_current` is the
+ * core browse table; if it is absent or unreadable the projection cannot
+ * serve any query. Throws so the probe can report a distinct state.
+ */
+// Named so displayErrorDetail surfaces a clear, path-free identifier in the
+// doctor report rather than a generic "Error".
+class ProjectionSchemaError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ProjectionSchemaError";
+  }
+}
+
+/**
+ * Columns `readProjectedMemoryBrowse` SELECTs from `memory_current` with no
+ * graceful fallback. `tags_json`/`preview_text` fall back via
+ * memoryCurrentSelectExpressions and `path_valid` falls back via the legacy
+ * full-scan branch — none of those make a browse query throw. A projection
+ * whose `memory_current` lacks any of these columns cannot serve browse
+ * queries: the SELECT throws and browse silently falls back to a full-corpus
+ * scan. Enumerated directly from readProjectedMemoryBrowse's SELECT list +
+ * ORDER BY references (issue #1848 round 3).
+ */
+const REQUIRED_MEMORY_CURRENT_COLUMNS = [
+  "memory_id",
+  "path_rel",
+  "category",
+  "status",
+  "created_at",
+  "updated_at",
+  "entity_ref",
+] as const;
+
+function assertProjectionSchemaReadable(db: BetterSqlite3Database): void {
+  const row = db
+    .prepare(
+      "SELECT name FROM sqlite_master WHERE type = 'table' AND name = 'memory_current'",
+    )
+    .get() as { name: string } | undefined;
+  if (!row?.name) {
+    throw new ProjectionSchemaError(
+      "projection schema is missing or was not initialized (memory_current table not found)",
+    );
+  }
+  // Round 3 (issue #1848): verify the columns readProjectedMemoryBrowse
+  // actually SELECT are present, not just that the table exists. A file like
+  // `CREATE TABLE memory_current (x INTEGER)` passed the round-2 table-existence
+  // + SELECT-1 check but cannot serve browse queries, so browse silently fell
+  // back to full-corpus scans while `remnic doctor` reported healthy. Classify
+  // such a stale/half-built table as present-but-invalid so the operator gets a
+  // rebuild hint instead of a false-clean bill of health.
+  const columns = listTableColumns(db, "memory_current");
+  const missing = REQUIRED_MEMORY_CURRENT_COLUMNS.filter((c) => !columns.has(c));
+  if (missing.length > 0) {
+    throw new ProjectionSchemaError(
+      `projection memory_current table is missing required column(s): ${missing.join(", ")}`,
+    );
+  }
+  // Also confirm the table is queryable — catches physical corruption that
+  // only surfaces on first read (the file opens but statements fail).
+  db.prepare("SELECT 1 FROM memory_current LIMIT 1").get();
+}
+
+/**
+ * Stat + attempt-open + schema-validate the memory projection WITHOUT keeping
+ * a handle, for the `remnic doctor` health check (issue #1829 / #1848).
+ * Distinguishes four states so operators can tell "not built yet" (normal) from
+ * "exists but broken" (needs a rebuild / native-binding rebuild). Never throws.
+ */
+export function probeProjectionHealth(memoryDir: string): ProjectionHealthProbe {
+  const dbPath = getMemoryProjectionPath(memoryDir);
+  if (!fs.existsSync(dbPath)) {
+    return { state: "absent", detail: "", nativeBindingMismatch: false };
+  }
+  let db: BetterSqlite3Database | null = null;
+  try {
+    db = projectionReadonlyOpener(dbPath, { readonly: true, fileMustExist: true });
+    // Validate the projection is actually USABLE, not just that the file
+    // opens (issue #1848 round 2): a file that opens but has the schema
+    // missing/corrupt previously reported ok, so doctor said healthy while
+    // browse silently fell back to full-corpus scans.
+    assertProjectionSchemaReadable(db);
+    return { state: "openable", detail: "", nativeBindingMismatch: false };
+  } catch (error) {
+    // If the file OPENED (db assigned) but the schema query failed, the
+    // native binding is fine — the projection itself is stale/corrupt.
+    if (db) {
+      return {
+        state: "present-but-invalid",
+        detail: displayErrorDetail(error),
+        nativeBindingMismatch: false,
+      };
+    }
+    return {
+      state: "unopenable",
+      detail: displayErrorDetail(error),
+      nativeBindingMismatch: isLikelyBetterSqlite3NativeBindingError(error),
+    };
+  } finally {
+    db?.close();
+  }
+}
 function updateProjectionBestEffort(
   memoryDir: string,
   sql: string,

package/src/operator-toolkit.ts

@@ -11,6 +11,7 @@ import {
   resolveOpenClawWorkspaceStatePath,
 } from "./native-knowledge.js";
 import { StorageManager } from "./storage.js";
+import { probeProjectionHealth } from "./memory-projection-store.js";
 import { listNamespaces } from "./namespaces/migrate.js";
 import { summarizeNamespaceMaintenanceHealth } from "./maintenance/namespace-maintenance-fanout.js";
 import {
@@ -1094,6 +1095,64 @@ export function summarizeProvenanceCoverage(
   return { counts, total: memories.length };
 }
 
+/**
+ * Memory projection health (issue #1829). A present-but-unopenable projection
+ * (wrong ABI / corrupt / bad perms) previously collapsed into the same silent
+ * null as a missing file, hiding native-binding mismatches behind full-corpus
+ * scans. This check stats + attempt-opens the projection so `remnic doctor`
+ * distinguishes "not built yet" (normal) from "exists but broken" (needs a
+ * rebuild / native-binding rebuild). Never throws.
+ */
+export function summarizeProjectionHealth(
+  config: Pick<PluginConfig, "memoryDir">,
+): OperatorDoctorCheck {
+  const probe = probeProjectionHealth(config.memoryDir);
+  if (probe.state === "absent") {
+    return {
+      key: "memory_projection",
+      status: "ok",
+      summary: "Memory projection index not built yet (normal until first maintenance run).",
+      details: { state: probe.state },
+    };
+  }
+  if (probe.state === "openable") {
+    return {
+      key: "memory_projection",
+      status: "ok",
+      summary: "Memory projection index opens cleanly.",
+      details: { state: probe.state },
+    };
+  }
+  if (probe.state === "present-but-invalid") {
+    const schemaDetailSuffix = probe.detail ? ` (${probe.detail})` : "";
+    return {
+      key: "memory_projection",
+      status: "error",
+      summary: `Memory projection index exists but its schema is missing or unreadable${schemaDetailSuffix}; memory browse is falling back to full-corpus scans.`,
+      remediation:
+        "Rebuild the projection with `remnic rebuild-memory-projection --write`.",
+      details: { state: probe.state, detail: probe.detail },
+    };
+  }
+  const nativeSuffix = probe.nativeBindingMismatch
+    ? " Native binding appears built for the wrong Node.js ABI."
+    : "";
+  const detailSuffix = probe.detail ? ` (${probe.detail})` : "";
+  return {
+    key: "memory_projection",
+    status: "error",
+    summary: `Memory projection index exists but could not be opened${detailSuffix}.${nativeSuffix}`,
+    remediation: probe.nativeBindingMismatch
+      ? "Rebuild the better-sqlite3 native binding for this Node.js (`node scripts/ensure-better-sqlite3.mjs` or `pnpm rebuild better-sqlite3`), then restart."
+      : "Rebuild the projection with `remnic rebuild-memory-projection --write`; check file permissions and integrity.",
+    details: {
+      state: probe.state,
+      detail: probe.detail,
+      nativeBindingMismatch: probe.nativeBindingMismatch,
+    },
+  };
+}
+
 export async function runOperatorDoctor(options: OperatorDoctorOptions): Promise<OperatorDoctorReport> {
   const now = options.now ?? new Date();
   const configStatus = await loadCliPluginConfig(options.configPath);
@@ -1211,6 +1270,11 @@ export async function runOperatorDoctor(options: OperatorDoctorOptions): Promise
     details: meta,
   });
 
+  // Memory projection health (issue #1829). Surfaces a present-but-unopenable
+  // projection (wrong ABI / corrupt) that previously degraded every memory
+  // list to a silent full-corpus scan. Absent and openable are both "ok".
+  checks.push(summarizeProjectionHealth(config));
+
   // Provenance coverage (issue #1575 PR 3). Operators need to see the
   // verified/unverified/none distribution grow as extraction backfills.
   // Best-effort: a read failure surfaces as a warn, not an error.