@remnic/core 9.17.1 → 9.18.0

package/src/maintenance/projection-support.ts

@@ -0,0 +1,56 @@
+/**
+ * Projection maintenance support (issue #2119) — helpers shared by the
+ * scheduled projection rebuild, the CLI rebuild, and the ledger rebuild.
+ * Lives beside the rebuild ops so the at-ceiling store/rebuild modules stay
+ * within their structural ratchets.
+ */
+
+import path from "node:path";
+import { openProjectionReadonly } from "../memory-projection-store.js";
+
+/** Read the projection meta rebuiltAt timestamp; null when absent/unopenable. */
+export function readProjectionRebuiltAt(memoryDir: string): string | null {
+  const db = openProjectionReadonly(memoryDir);
+  if (!db) return null;
+  try {
+    const row = db.prepare("SELECT value FROM meta WHERE key = 'rebuiltAt'").get() as
+      | { value?: unknown }
+      | undefined;
+    return typeof row?.value === "string" && row.value.length > 0 ? row.value : null;
+  } catch {
+    return null;
+  } finally {
+    db.close();
+  }
+}
+
+/**
+ * Assert an optionally injected storage (e.g. the daemon's live unlocked
+ * secure-store instance) is rooted at `memoryDir`, and hand it back. Shared
+ * by the projection and lifecycle-ledger rebuilds so the containment guard
+ * cannot drift between them; callers construct their own StorageManager when
+ * nothing was injected (keeps this module off the direct-storage-import
+ * ratchet, issue #1533).
+ */
+export function assertInjectedStorageRooted<T extends { dir: string }>(
+  label: string,
+  memoryDir: string,
+  injected: T | undefined,
+): T | undefined {
+  if (injected && path.resolve(injected.dir) !== path.resolve(memoryDir)) {
+    throw new Error(
+      `${label}: storage.dir (${injected.dir}) must match memoryDir (${memoryDir})`,
+    );
+  }
+  return injected;
+}
+
+export interface SkippedDuplicateMemory {
+  memoryId: string;
+  keptPath: string;
+  skippedPath: string;
+}
+
+export interface SkippedBlankIdMemory {
+  path: string;
+}

package/src/maintenance/rebuild-memory-lifecycle-ledger.ts

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { stat } from "node:fs/promises";
 import { StorageManager } from "../storage.js";
+import { assertInjectedStorageRooted } from "./projection-support.js";
 import { log } from "../logger.js";
 import { displayErrorDetail } from "../runtime/better-sqlite.js";
 import type { MemoryLifecycleEvent } from "../types.js";
@@ -205,13 +206,7 @@ export async function rebuildMemoryLifecycleLedger(
   const dryRun = options.dryRun !== false;
   const now = options.now ?? new Date();
   const outputPath = path.join(options.memoryDir, "state", "memory-lifecycle-ledger.jsonl");
-  const storage = options.storage ?? new StorageManager(options.memoryDir);
-  if (options.storage && path.resolve(storage.dir) !== path.resolve(options.memoryDir)) {
-    throw new Error(
-      `rebuildMemoryLifecycleLedger: storage.dir (${storage.dir}) must match `
-      + `memoryDir (${options.memoryDir})`,
-    );
-  }
+  const storage = assertInjectedStorageRooted("rebuildMemoryLifecycleLedger", options.memoryDir, options.storage) ?? new StorageManager(options.memoryDir);
   const secureRewrite = options.storage !== undefined;
   const tiers = [
     await storage.readAllMemories(),

package/src/maintenance/rebuild-memory-projection.ts

@@ -46,6 +46,8 @@ import { commitPreparedFileAtomically } from "./atomic-file.js";
 
 export interface RebuildMemoryProjectionOptions {
   memoryDir: string;
+  /** Reuse the caller's live StorageManager (must be rooted at memoryDir). */
+  storage?: StorageManager;
   defaultNamespace?: string;
   dryRun?: boolean;
   now?: Date;
@@ -53,15 +55,9 @@ export interface RebuildMemoryProjectionOptions {
   updatedBefore?: string;
 }
 
-export interface SkippedDuplicateMemory {
-  memoryId: string;
-  keptPath: string;
-  skippedPath: string;
-}
-
-export interface SkippedBlankIdMemory {
-  path: string;
-}
+export type { SkippedBlankIdMemory, SkippedDuplicateMemory } from "./projection-support.js";
+import { assertInjectedStorageRooted } from "./projection-support.js";
+import type { SkippedBlankIdMemory, SkippedDuplicateMemory } from "./projection-support.js";
 
 export interface SkippedDuplicateTimelineEvent {
   eventId: string;
@@ -550,6 +546,7 @@ function deduplicateTimelineEvents(
 async function loadAuthoritativeProjectionSnapshot(options: {
   memoryDir: string;
   defaultNamespace?: string;
+  storage?: StorageManager;
   updatedAfter?: string;
   updatedBefore?: string;
 }): Promise<{
@@ -581,7 +578,7 @@ async function loadAuthoritativeProjectionSnapshot(options: {
   skippedDuplicateTimelineEvents: SkippedDuplicateTimelineEvent[];
   skippedBlankIdTimelineEvents: SkippedBlankIdTimelineEvent[];
 }> {
-  const storage = new StorageManager(options.memoryDir);
+  const storage = assertInjectedStorageRooted("rebuildMemoryProjection", options.memoryDir, options.storage) ?? new StorageManager(options.memoryDir);
   // Force a fresh disk read — projection verify/rebuild must see the true
   // on-disk state, not a potentially stale in-process cache.
   storage.invalidateAllMemoriesCacheForDir();

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/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);