@remnic/core 9.17.0 → 9.18.0

package/src/memory-projection-store.ts

@@ -366,7 +366,7 @@ function logProjectionOpenFailure(memoryDir: string, error: unknown): void {
   );
 }
 
-function openProjectionReadonly(memoryDir: string): BetterSqlite3Database | null {
+export 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

package/src/offline-sync-impression-drain.test.ts

@@ -8,7 +8,9 @@ import {
   drainPendingImpressionsForOfflineSync,
   drainPendingLifecycleForOfflineSync,
   getOfflineSyncStorage,
+  listOfflineSyncNamespaces,
 } from "./offline-sync-impression-drain.js";
+import { namespaceIdentityToken } from "./namespaces/identity.js";
 import { isEncryptedFile } from "./secure-store/secure-fs.js";
 import { StorageManager } from "./storage.js";
 
@@ -314,3 +316,55 @@ test("getOfflineSyncStorage never double-folds the root ledger when it is listed
 
   assert.deepEqual(lifecycleDrains, ["root", "team"], "root ledger is folded exactly once");
 });
+
+test("listOfflineSyncNamespaces decodes canonical token dirs and skips names the router would reject", async () => {
+  const root = await mkdtemp(path.join(os.tmpdir(), "remnic-offline-ns-enum-"));
+  try {
+    // A project namespace whose canonical token dir `ns-<hex>` exceeds the
+    // 64-char route-namespace cap: `getStorage` on the RAW basename throws
+    // `unsafe namespace` and 500s the whole root snapshot-stream (the regression).
+    const longName = "generalist-project-origin-6d1ad1f2";
+    const longToken = namespaceIdentityToken(longName); // ns-<hex>, 71 chars
+    assert.ok(longToken.length > 64, "token dir must exceed the route-namespace cap");
+    // A namespace whose DECODED name itself exceeds the 64-char route cap:
+    // decoding succeeds but isSafeRouteNamespace must still reject it.
+    const overCapName = `generalist-project-tag-${"x".repeat(60)}`;
+    const overCapToken = namespaceIdentityToken(overCapName);
+    assert.ok(overCapName.length > 64, "decoded name must exceed the route cap");
+    for (const dir of [longToken, overCapToken, "blend", "ns-default"]) {
+      await mkdir(path.join(root, "namespaces", dir, "state"), { recursive: true });
+      await writeFile(
+        path.join(root, "namespaces", dir, LIFECYCLE_LEDGER_REL),
+        "",
+        "utf-8",
+      );
+    }
+    const host = {
+      config: {
+        memoryDir: root,
+        defaultNamespace: "generalist",
+        sharedNamespace: "shared",
+        namespacePolicies: [],
+      },
+      namespaceCatalog: { listNamespaces: async () => [] },
+    } as unknown as Parameters<typeof listOfflineSyncNamespaces>[0];
+
+    const names = new Set(await listOfflineSyncNamespaces(host));
+
+    // The canonical token dir is decoded back to its namespace NAME...
+    assert.ok(names.has(longName), "canonical token dir must be decoded to its namespace name");
+    // ...never surfaced as the raw >64-char token that getStorage would reject.
+    assert.ok(!names.has(longToken), "raw over-cap token must never be enumerated as a namespace");
+    // A decoded name that is ITSELF over the route cap is skipped entirely
+    // (the isSafeRouteNamespace rejection branch).
+    assert.ok(!names.has(overCapName), "over-cap decoded name must be skipped");
+    assert.ok(!names.has(overCapToken), "over-cap raw token must be skipped");
+    // A raw plain-named dir is used verbatim.
+    assert.ok(names.has("blend"), "plain namespace dir must be enumerated verbatim");
+    // The literal ns-default token decodes to the EMPTY default identity and
+    // must map to the configured default namespace, not be skipped as "".
+    assert.ok(names.has("generalist"), "ns-default dir maps to the configured default namespace");
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});

package/src/offline-sync-impression-drain.ts

@@ -12,6 +12,8 @@ import { isErrnoCode } from "./utils/errno.js";
 import { assertPathInsideRoot, pathIsInside } from "./utils/path-containment.js";
 import { displayErrorDetail } from "./runtime/better-sqlite.js";
 import { getConfiguredNamespaces } from "./scopes/scope-plan.js";
+import { isSafeRouteNamespace } from "./routing/engine.js";
+import { namespaceIdentityFromToken } from "./namespaces/identity.js";
 import type { PluginConfig } from "./types.js";
 
 type PendingImpressionDrain = () => Promise<{ pendingDeferred: boolean }>;
@@ -89,7 +91,17 @@ export async function getOfflineSyncStorage<T extends PendingLifecycleDrain & {
   if (path.resolve(storage.dir) === memoryRoot && orchestrator.listOfflineSyncNamespaces) {
     const drained = new Set<string>([memoryRoot]);
     for (const ns of await orchestrator.listOfflineSyncNamespaces()) {
-      const nsStorage = await orchestrator.getStorage(ns);
+      // A single unresolvable namespace (e.g. a legacy canonical token dir whose
+      // name exceeds the route-namespace length cap) must not abort the whole root
+      // snapshot — degrade to draining the rest. listOfflineSyncNamespaces already
+      // normalizes token dirs, so this is defense-in-depth.
+      let nsStorage: T;
+      try {
+        nsStorage = await orchestrator.getStorage(ns);
+      } catch (err) {
+        log.debug(`offline-sync root drain: skipping namespace ${ns} (non-fatal): ${err}`);
+        continue;
+      }
       const nsDir = path.resolve(nsStorage.dir);
       if (drained.has(nsDir)) continue;
       drained.add(nsDir);
@@ -114,8 +126,28 @@ export async function listOfflineSyncNamespaces(host: OfflineSyncNamespaceHost):
   try {
     for (const ledgerPath of await offlineSyncLifecycleLedgerPaths(host.config.memoryDir)) {
       const namespaceDir = path.dirname(path.dirname(ledgerPath));
-      if (path.basename(path.dirname(namespaceDir)) === "namespaces") {
-        names.add(path.basename(namespaceDir));
+      if (path.basename(path.dirname(namespaceDir)) !== "namespaces") continue;
+      // A namespace is stored under its canonical token dir `ns-<hex>`. Decode the
+      // token back to the namespace NAME so the drain fanout resolves the SAME
+      // storage the token dir belongs to (the catalog rebuild scanner decodes the
+      // same way, catalog.ts finishRebuild). A raw dir already named as a plain
+      // namespace is used verbatim. Skip any name the router would reject — e.g. a
+      // canonical token dir whose decoded-or-raw name exceeds isSafeRouteNamespace's
+      // 64-char cap — because getStorage() would throw `unsafe namespace` and 500
+      // the whole root snapshot-stream (the offline-sync regression this fixes).
+      const dirName = path.basename(namespaceDir);
+      // namespaceIdentityFromToken returns "" for the ns-default token (the
+      // default-namespace identity) — map that to the configured default
+      // namespace instead of skipping the directory as an unsafe empty name.
+      const decoded = namespaceIdentityFromToken(dirName);
+      const name =
+        decoded === null
+          ? dirName
+          : decoded.length > 0
+            ? decoded
+            : host.config.defaultNamespace;
+      if (isSafeRouteNamespace(name)) {
+        names.add(name);
       }
     }
   } catch {

package/src/orchestration/maintenance.test.ts

@@ -18,10 +18,22 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import os from "node:os";
 import path from "node:path";
+import { readProjectionRebuiltAt } from "../maintenance/projection-support.js";
 import { lstat, mkdir, mkdtemp, readdir, readFile, rm, stat, symlink, writeFile } from "node:fs/promises";
 import { execFileSync } from "node:child_process";
 
 import { MaintenanceScheduler } from "./maintenance.js";
+import {
+  createProjectionRebuildScheduleState,
+  maybeRebuildMemoryProjectionScheduled,
+  type ProjectionRebuildScheduleState,
+} from "./projection-rebuild-schedule.js";
+import { rebuildMemoryProjection } from "../maintenance/rebuild-memory-projection.js";
+import {
+  probeProjectionHealth,
+  readProjectedMemoryBrowse,
+  
+} from "../memory-projection-store.js";
 import type { PluginConfig } from "../types.js";
 import type { SearchBackend } from "../search/port.js";
 import type {
@@ -2836,3 +2848,107 @@ test("catalog-disabled fallback pending drain skips unsafe spill entries (symlin
     await rm(outside, { recursive: true, force: true });
   }
 });
+
+// ───────────────────────────────────────────────────────────────────────────
+// Memory-projection scheduled rebuild (issue #2119)
+// ───────────────────────────────────────────────────────────────────────────
+
+
+async function seedMemoryDirWithOneFact(): Promise<string> {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-projrebuild-"));
+  await mkdir(path.join(memoryDir, "facts", "2026-07-01"), { recursive: true });
+  await writeFile(
+    path.join(memoryDir, "facts", "2026-07-01", "fact-1.md"),
+    `---
+id: fact-1
+category: fact
+created: 2026-07-01T00:00:00.000Z
+updated: 2026-07-01T01:00:00.000Z
+source: test
+confidence: 0.8
+confidenceTier: implied
+tags: ["alpha"]
+---
+
+alpha
+`,
+    "utf-8",
+  );
+  return memoryDir;
+}
+/** Build the pure-function state the extracted scheduled rebuild owns. */
+function projectionScheduleState(): ProjectionRebuildScheduleState {
+  return createProjectionRebuildScheduleState();
+}
+
+test("scheduled projection rebuild runs when enabled and writes a populated projection (#2119)", async () => {
+  const memoryDir = await seedMemoryDirWithOneFact();
+  try {
+    // No projection built yet — the exact issue-#2119 cold state where timeline
+    // consumers would fall back to full-corpus scans.
+    assert.equal(probeProjectionHealth(memoryDir).state, "absent");
+    await maybeRebuildMemoryProjectionScheduled({
+      config: fixtureConfig({
+        memoryDir,
+        projectionRebuildEnabled: true,
+        projectionRebuildIntervalMs: 6 * 60 * 60 * 1000,
+      }),
+      state: projectionScheduleState(),
+    });
+    // The projection now exists, is openable, and carries the seeded memory.
+    assert.equal(probeProjectionHealth(memoryDir).state, "openable");
+    assert.equal(readProjectedMemoryBrowse(memoryDir, { limit: 5, offset: 0 })?.total, 1);
+    assert.ok(readProjectionRebuiltAt(memoryDir), "rebuiltAt meta must be stamped");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("scheduled projection rebuild is a no-op when disabled by config (#2119)", async () => {
+  const memoryDir = await seedMemoryDirWithOneFact();
+  try {
+    await maybeRebuildMemoryProjectionScheduled({
+      config: fixtureConfig({
+        memoryDir,
+        projectionRebuildEnabled: false,
+        projectionRebuildIntervalMs: 6 * 60 * 60 * 1000,
+      }),
+      state: projectionScheduleState(),
+    });
+    // Gate off: no projection is created, so the CLI/cron path remains the only
+    // way to build it.
+    assert.equal(probeProjectionHealth(memoryDir).state, "absent");
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("scheduled projection rebuild skips when the projection was rebuilt within the interval (#2119)", async () => {
+  const memoryDir = await seedMemoryDirWithOneFact();
+  try {
+    // Seed a projection whose rebuiltAt is one minute ago — inside the 6h
+    // interval, so a scheduled pass must NOT rebuild it again.
+    const oneMinuteAgo = new Date(Date.now() - 60_000);
+    await rebuildMemoryProjection({ memoryDir, dryRun: false, now: oneMinuteAgo });
+    const before = readProjectionRebuiltAt(memoryDir);
+    assert.equal(before, oneMinuteAgo.toISOString());
+
+    await maybeRebuildMemoryProjectionScheduled({
+      config: fixtureConfig({
+        memoryDir,
+        projectionRebuildEnabled: true,
+        projectionRebuildIntervalMs: 6 * 60 * 60 * 1000,
+      }),
+      state: projectionScheduleState(),
+    });
+    // Fresh-within-interval: rebuiltAt is unchanged (no rebuild happened) and no
+    // backup was written (a rebuild would have archived the prior projection).
+    assert.equal(readProjectionRebuiltAt(memoryDir), before, "projection must not be rebuilt when fresh");
+    await assert.rejects(
+      () => readdir(path.join(memoryDir, "archive", "memory-projection")),
+      "no backup means no rebuild occurred",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/orchestration/maintenance.ts

@@ -51,6 +51,10 @@ import {
   graphEdgeDecayCadenceToCronExpr,
 } from "../maintenance/memory-governance-cron.js";
 import { rebuildMemoryLifecycleLedger } from "../maintenance/rebuild-memory-lifecycle-ledger.js";
+import {
+  createProjectionRebuildScheduleState,
+  maybeRebuildMemoryProjectionScheduled,
+} from "./projection-rebuild-schedule.js";
 import {
   drainPendingLifecycleLedgerIfAny,
   pendingLifecycleLedgerDir,
@@ -134,6 +138,9 @@ export class MaintenanceScheduler {
   // fixture.
   private lifecycleLedgerMaxBytes = STATE_FILE_MAX_DECRYPT_BYTES;
 
+  // ── Memory-projection scheduled-rebuild state (issue #2119) ──
+  private readonly projectionRebuild = createProjectionRebuildScheduleState();
+
   // ── Activity (screen-capture) sync scheduler (issue #1900) ──
   // The full arm/re-arm/teardown lifecycle lives in ActivitySyncRegistrar.
   private readonly activityRegistrar: ActivitySyncRegistrar;
@@ -500,6 +507,15 @@ export class MaintenanceScheduler {
     void this.maybeCompactMemoryLifecycleLedger().catch((err) =>
       log.debug(`lifecycle ledger auto-compaction check failed (non-fatal): ${err}`),
     );
+    // Memory-projection scheduled rebuild (#2119): interval-throttled,
+    // single-flighted, never awaited, never throws — see the module docblock.
+    void maybeRebuildMemoryProjectionScheduled({
+      config: this.deps.config,
+      getStorage: this.deps.getStorage,
+      state: this.projectionRebuild,
+    }).catch((err) =>
+      log.debug(`memory projection scheduled rebuild check failed (non-fatal): ${err}`),
+    );
   }
 
   /** Internal: run a single QMD maintenance pass under singleflight guard. */

package/src/orchestration/projection-rebuild-schedule.ts

@@ -0,0 +1,115 @@
+/**
+ * Scheduled rebuild of the root memory projection (issue #2119).
+ *
+ * The projection (`state/memory-projection.sqlite`) is otherwise rebuild-only
+ * (manual CLI / tests), so it goes stale as the lifecycle ledger grows and
+ * timeline/browse consumers silently fall back to full-corpus scans. The
+ * MaintenanceScheduler fires this alongside ledger compaction on every
+ * maintenance request — interval-throttled, single-flighted, never awaited,
+ * never throws.
+ *
+ * `projectionRebuildEnabled` gates it (via the lifecycle capabilities
+ * resolver, default true); `projectionRebuildIntervalMs` is the cadence.
+ *
+ * Skipped when the projection was rebuilt within the interval. The freshness
+ * check reads the on-disk `rebuiltAt` meta (not just an in-process timestamp)
+ * so a daemon restart or an operator's cron `remnic rebuild-memory-projection`
+ * both suppress a redundant rebuild. On a real rebuild it logs the lag it just
+ * cured (age of the projection before the rebuild) plus the fresh row counts,
+ * so operators can see the projection was drifting. Failures are non-fatal
+ * and leave the throttle un-advanced to retry.
+ *
+ * Scope: the root memoryDir projection — the one `getMemoryTimeline` /
+ * browse / current-state serve from `baseDir`. Per-namespace projections are
+ * not yet scheduled here (they are still served by their own rebuild paths);
+ * the fallback WARN surfaces staleness for any namespace that lags.
+ */
+import { log } from "../logger.js";
+import type { PluginConfig } from "../types.js";
+import { resolveMemoryLifecycleCapabilities } from "../capabilities.js";
+import {
+  rebuildMemoryProjection,
+  type RebuildMemoryProjectionOptions,
+} from "../maintenance/rebuild-memory-projection.js";
+import { readProjectionRebuiltAt } from "../maintenance/projection-support.js";
+
+type InjectedStorage = NonNullable<RebuildMemoryProjectionOptions["storage"]>;
+
+export interface ProjectionRebuildScheduleState {
+  inFlight: boolean;
+  lastRebuildAtMs: number;
+  /** Timestamp of the most recent FAILURE; gates a short retry backoff that is
+   * separate from the success interval so a transient cause (e.g. a locked
+   * secure store) retries promptly once cleared instead of waiting a full
+   * interval. */
+  lastFailureAtMs: number;
+}
+
+/** Bounded retry cadence after a failure — short enough to self-heal promptly
+ * once a transient cause clears, long enough to keep a persistently-failing
+ * rebuild off every maintenance tick. */
+const FAILURE_RETRY_BACKOFF_MS = 5 * 60 * 1000;
+
+export function createProjectionRebuildScheduleState(): ProjectionRebuildScheduleState {
+  return { inFlight: false, lastRebuildAtMs: 0, lastFailureAtMs: 0 };
+}
+
+export async function maybeRebuildMemoryProjectionScheduled(opts: {
+  config: PluginConfig;
+  /** The daemon's live root storage, when available (secure-store unlock). */
+  getStorage?: () => InjectedStorage | undefined;
+  state: ProjectionRebuildScheduleState;
+}): Promise<void> {
+  const { config, state } = opts;
+  if (!resolveMemoryLifecycleCapabilities(config).projectionRebuild) return;
+  if (state.inFlight) return;
+  const intervalMs = config.projectionRebuildIntervalMs;
+  const now = Date.now();
+  if (now - state.lastRebuildAtMs < intervalMs) return;
+  if (now - state.lastFailureAtMs < FAILURE_RETRY_BACKOFF_MS) return;
+
+  const rootStorage = opts.getStorage?.();
+  const memoryDir = rootStorage ? rootStorage.dir : config.memoryDir;
+
+  // On-disk freshness check: survives restarts and cross-process CLI rebuilds.
+  const rebuiltAt = readProjectionRebuiltAt(memoryDir);
+  const rebuiltAtMs = rebuiltAt ? Date.parse(rebuiltAt) : Number.NaN;
+  if (Number.isFinite(rebuiltAtMs) && now - rebuiltAtMs < intervalMs) {
+    // Fresh already — adopt its timestamp so the next pass short-circuits on
+    // the cheap in-process guard without re-opening the projection each time.
+    state.lastRebuildAtMs = rebuiltAtMs;
+    return;
+  }
+
+  state.inFlight = true;
+  try {
+    const result = await rebuildMemoryProjection({
+      memoryDir,
+      // Reuse the daemon's live storage so secure-store deployments rebuild
+      // through the unlocked instance instead of a fresh locked one.
+      ...(rootStorage ? { storage: rootStorage } : {}),
+      defaultNamespace: config.defaultNamespace,
+      dryRun: false,
+      now: new Date(now),
+    });
+    state.lastRebuildAtMs = Date.now();
+    const lag = Number.isFinite(rebuiltAtMs)
+      ? `${Math.max(0, Math.round((now - rebuiltAtMs) / 60_000))}m stale`
+      : "never previously built";
+    log.info(
+      `memory projection rebuilt (scheduled) for ${memoryDir}: was ${lag}; `
+      + `${result.currentRows} current, ${result.timelineRows} timeline, `
+      + `${result.entityMentionRows} entity-mention rows`,
+    );
+  } catch (err) {
+    // Non-fatal. Arm a SHORT backoff (not the full success interval) so a
+    // transient cause (locked secure store, momentarily-unavailable storage)
+    // retries promptly once it clears, while a persistently-failing rebuild
+    // still stays off every maintenance tick. lastRebuildAtMs is left as-is so
+    // the success interval is not falsely advanced.
+    state.lastFailureAtMs = Date.now();
+    log.warn(`memory projection scheduled rebuild failed (non-fatal) for ${memoryDir}: ${err}`);
+  } finally {
+    state.inFlight = false;
+  }
+}

package/src/storage-guards.ts

@@ -18,13 +18,30 @@ export function assertMemoryFrontmatterId(
   }
 }
 
-export function warnProjectionFallback(memoryDir: string, consumer: string): null {
+export function warnProjectionFallback(
+  memoryDir: string,
+  consumer: string,
+  // Lazy so the (potentially I/O-bound) lag computation runs only when this
+  // call actually logs, not on every rate-limited-suppressed fallback (#2119).
+  detail?: () => string | undefined,
+): null {
   const key = `${memoryDir}\0${consumer}`;
   const now = Date.now();
   const warnedAt = projectionFallbackWarnedAt.get(key) ?? 0;
   if (now - warnedAt >= PROJECTION_FALLBACK_WARN_INTERVAL_MS) {
     projectionFallbackWarnedAt.set(key, now);
-    log.warn(`storage.${consumer}: memory projection absent or empty; falling back to full corpus`);
+    const suffix = detail?.();
+    log.warn(
+      `storage.${consumer}: memory projection absent or empty; falling back to full corpus`
+      + (suffix ? ` (${suffix})` : ""),
+    );
   }
   return null;
 }
+
+/** @internal Test seam (#2119): clear the fallback-warn rate-limit dedup map so
+ *  a focused test can prove the once-per-interval spam suppression from a clean
+ *  slate regardless of prior tests in the same process. */
+export function __resetProjectionFallbackWarnSuppressionForTest(): void {
+  projectionFallbackWarnedAt.clear();
+}

package/src/storage-memory-lifecycle-ledger.test.ts

@@ -6,6 +6,8 @@ import test from "node:test";
 import { randomUUID } from "node:crypto";
 
 import { StorageManager } from "./storage.js";
+import { initLogger, resetLogger } from "./logger.js";
+import { __resetProjectionFallbackWarnSuppressionForTest } from "./storage-guards.js";
 import { encryptFileBody, filePathAad, isEncryptedFile, readMaybeEncryptedFile, readMaybeEncryptedFileBuffer } from "./secure-store/secure-fs.js";
 import type { MemoryLifecycleEvent } from "./types.js";
 import {
@@ -1271,3 +1273,33 @@ test("compaction buffer reader skips an oversized unterminated row instead of th
     "valid rows returned; the oversized row is skipped without throwing",
   );
 });
+
+test("getMemoryTimeline fallback WARN is loud with lag and rate-limited when the projection is missing (#2119)", async () => {
+  const warns: string[] = [];
+  initLogger({ info() {}, warn: (m) => warns.push(m), error() {}, debug() {} }, false);
+  __resetProjectionFallbackWarnSuppressionForTest();
+  try {
+    const rows = [
+      JSON.stringify(lifecycleEvent("t1", "memory-target", "2026-01-01T00:01:00.000Z")),
+      JSON.stringify(lifecycleEvent("t2", "memory-target", "2026-01-01T00:02:00.000Z")),
+    ];
+    await withLifecycleLedger(rows, async (storage) => {
+      // No projection sqlite exists in this temp dir, so both calls take the
+      // ledger fallback — the exact issue-#2119 regression path.
+      const first = await storage.getMemoryTimeline("memory-target", 5);
+      const second = await storage.getMemoryTimeline("memory-target", 5);
+      assert.equal(first.length, 2);
+      assert.equal(second.length, 2);
+
+      const timelineWarns = warns.filter((w) => w.includes("storage.getMemoryTimeline"));
+      // Rate-limited: two fallbacks, but only ONE WARN in the interval (no spam).
+      assert.equal(timelineWarns.length, 1, "fallback WARN must fire once, not per call");
+      // Loud: the single WARN names the fallback AND the projection lag.
+      assert.match(timelineWarns[0]!, /falling back to full corpus/);
+      assert.match(timelineWarns[0]!, /projection never rebuilt/);
+    });
+  } finally {
+    resetLogger();
+    __resetProjectionFallbackWarnSuppressionForTest();
+  }
+});

package/src/storage.ts

@@ -1,3 +1,4 @@
+import { readProjectionRebuiltAt } from "./maintenance/projection-support.js";
 import {
   access,
   lstat,
@@ -6584,7 +6585,20 @@ export class StorageManager {
 
     const projected = readProjectedMemoryTimeline(this.baseDir, memoryId, cappedLimit);
     if (projected && projected.length > 0) return projected;
-    warnProjectionFallback(this.baseDir, "getMemoryTimeline");
+    // Loud, rate-limited staleness telemetry (#2119): a fallback here means the
+    // projection is missing/empty/stale, so surface HOW stale it is. The lag is
+    // computed lazily — only when warnProjectionFallback actually logs (once per
+    // interval) — so a hot fallback path pays for a projection meta read at most
+    // once per suppression window, not per call.
+    warnProjectionFallback(this.baseDir, "getMemoryTimeline", () => {
+      const rebuiltAt = readProjectionRebuiltAt(this.baseDir);
+      if (!rebuiltAt) return "projection never rebuilt";
+      const ageMs = Date.now() - Date.parse(rebuiltAt);
+      if (!Number.isFinite(ageMs)) return `projection rebuiltAt=${rebuiltAt}`;
+      const ageMin = Math.max(0, Math.round(ageMs / 60_000));
+      const age = ageMin >= 120 ? `${Math.round(ageMin / 60)}h` : `${ageMin}m`;
+      return `projection ${age} stale, last rebuilt ${rebuiltAt}`;
+    });
     return readBoundedLifecycleEventsFromLedger(
       this.memoryLifecycleLedgerPath, (p) => this.readStorageSecureFile(p), cappedLimit, memoryId);
   }

package/src/testing/subjects/memory-projection.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Memory-projection rebuild subject for the scenario-matrix harness
+ * (issue #2119). Each canonical row runs the REAL rebuild path — memory scan,
+ * sqlite build, atomic install, rebuiltAt meta — plus the scheduled-rebuild
+ * wrapper's freshness short-circuit. The matrix dimensions are orthogonal to
+ * this rebuild-only subsystem, so the same durable projection invariant
+ * applies to every row.
+ */
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import os from "node:os";
+import { rebuildMemoryProjection } from "../../maintenance/rebuild-memory-projection.js";
+import { readProjectionRebuiltAt } from "../../maintenance/projection-support.js";
+import {
+  type LifecycleSubject,
+  type MatrixRow,
+  runLifecycleMatrix,
+} from "../lifecycle-matrix.js";
+
+interface MemoryProjectionState {
+  memoryDir: string;
+  memoryId: string;
+}
+
+function memoryFixture(row: MatrixRow, memoryId: string): string {
+  return [
+    "---",
+    `id: ${memoryId}`,
+    "category: fact",
+    "confidence: 0.9",
+    "created: 2026-01-01T00:00:00.000Z",
+    "updated: 2026-01-01T00:00:00.000Z",
+    "status: active",
+    "---",
+    "",
+    `Matrix fixture memory for lifecycle row ${row.id}.`,
+    "",
+  ].join("\n");
+}
+
+const subject: LifecycleSubject<MemoryProjectionState> = {
+  async setup(row): Promise<MemoryProjectionState> {
+    const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-projection-subject-"));
+    const memoryId = `matrix-projection-${row.id}`;
+    const factDir = path.join(memoryDir, "facts", "2026-01-01");
+    await mkdir(factDir, { recursive: true });
+    await writeFile(path.join(factDir, `${memoryId}.md`), memoryFixture(row, memoryId), "utf8");
+    return { memoryDir, memoryId };
+  },
+
+  async exercise(state): Promise<void> {
+    const result = await rebuildMemoryProjection({
+      memoryDir: state.memoryDir,
+      dryRun: false,
+      now: new Date("2026-01-01T12:00:00.000Z"),
+    });
+    assert.equal(result.dryRun, false);
+    assert.equal(result.scannedMemories, 1);
+    assert.equal(result.currentRows, 1);
+    assert.ok(existsSync(result.outputPath), "projection sqlite installed");
+  },
+
+  async invariants(state): Promise<void> {
+    // The on-disk rebuiltAt meta is the scheduled rebuild's cross-process
+    // freshness signal (daemon restart / operator CLI both rely on it).
+    const rebuiltAt = readProjectionRebuiltAt(state.memoryDir);
+    assert.ok(rebuiltAt, "rebuiltAt meta written by the rebuild");
+    assert.ok(Number.isFinite(Date.parse(rebuiltAt)), "rebuiltAt parses as a timestamp");
+  },
+
+  async teardown(state): Promise<void> {
+    await rm(state.memoryDir, { recursive: true, force: true });
+  },
+};
+
+runLifecycleMatrix("memory-projection", subject);

package/src/types.ts

@@ -2121,6 +2121,24 @@ export interface PluginConfig extends BoundedJsonlStateConfig {
   /** Confidence threshold for the "below visibility" telemetry counter. Default 0.2. */
   graphEdgeDecayVisibilityThreshold: number;
 
+  // Issue #2119 — maintenance-scheduled memory-projection rebuild.
+  /**
+   * Enable the maintenance-scheduled rebuild of `state/memory-projection.sqlite`.
+   * The projection is otherwise rebuild-only (manual CLI / tests), so it rots as
+   * the lifecycle ledger grows and timeline/browse consumers silently regress to
+   * full-corpus fallback scans. Default true — mirrors lifecycle-ledger
+   * auto-compaction, which is likewise enabled-by-default to keep a state file
+   * healthy. Set false to disable (operators can still cron the CLI rebuild).
+   */
+  projectionRebuildEnabled: boolean;
+  /**
+   * Minimum interval between scheduled projection rebuilds. A rebuild is skipped
+   * when the projection's `rebuiltAt` meta is younger than this, so a burst of
+   * maintenance requests cannot fan into back-to-back rebuilds. Floored at 60s.
+   * Default 6h (matches memoryLifecycleLedgerCompactMinIntervalMs).
+   */
+  projectionRebuildIntervalMs: number;
+
   /**
    * Issue #681 PR 3/3 — minimum edge confidence to traverse during spreading
    * activation. Edges below are pruned (no activation, no downstream neighbors);