@remnic/core 9.3.760 → 9.3.762

package/src/namespaces/catalog.ts

@@ -5,8 +5,8 @@ import {
   appendFile,
   lstat,
   mkdir,
+  open,
   readdir,
-  readFile,
   realpath,
   rename,
   stat,
@@ -426,6 +426,18 @@ function inferKind(namespace: string, config: PluginConfig): NamespaceKind {
   return "explicit";
 }
 
+interface CatalogFileIdentity {
+  size: number;
+  mtimeMs: number;
+  ctimeMs: number;
+  ino: number;
+}
+
+interface CompactedCatalogCache {
+  identity: CatalogFileIdentity;
+  records: Map<string, NamespaceRecord>;
+}
+
 export class NamespaceCatalog {
   private readonly memoryDir: string;
   private readonly stateDir: string;
@@ -441,12 +453,19 @@ export class NamespaceCatalog {
   // neither mistakes the other's lock for self-held (round 6, codex P2 — NBsGP
   // invariant preserved and tightened).
   private readonly criticalSection = new MutationSerializer();
+  private compactedCache: CompactedCatalogCache | undefined;
   // Test-only seam (round 7 — NEZkA): fires inside a touch's HELD-lock critical
   // section, after the lock is acquired but BEFORE the read→merge→append. A
   // deterministic concurrency test installs a hook here to widen the (otherwise
   // microscopic) window and prove that a cross-process rebuild CANNOT run its
   // load→rename while a touch holds the lock. Never set in production code.
   protected onTouchCriticalSectionForTest?: () => Promise<void>;
+  // Test-only observation seam: fires only when the JSONL file is fully read.
+  // Cached loads do not invoke it.
+  protected onCatalogReadForTest?: () => void;
+  // Test-only seam: fires after this process appends but before it stats the
+  // file to refresh the cache identity.
+  protected onAfterCatalogAppendForTest?: () => Promise<void>;
   // Test-only seam (round 7 — NEZkA): fires inside a mutating rebuild's HELD-lock
   // critical section, after the final cross-process re-merge `loadCompacted()` and
   // BEFORE the atomic `rename()`. This is the EXACT window in which a check-then-
@@ -597,19 +616,20 @@ export class NamespaceCatalog {
     }
     return [...byStorageDir.values()];
   }
-
-  private async loadSanitizedRecords(): Promise<NamespaceRecord[]> {
-    const records = await this.loadCompacted();
-    const sanitized = await Promise.all(
-      [...records.values()].map((r) => this.sanitizeRecordForRead(r)),
-    );
-    // Drop unsafe-namespace rows (sanitizer returned null) at the read boundary.
-    // Then collapse duplicate root aliases so maintenance/QMD see exactly one
-    // namespace owner for a physical storage root, matching rebuild ownership,
-    // while preserving touch recency from every alias row.
-    return this.dropDuplicateStorageRootAliases(
-      sanitized.filter((r): r is NamespaceRecord => r !== null),
-    );
+  private loadSanitizedRecords(): Promise<NamespaceRecord[]> {
+    return this.queueCritical(async () => {
+      const records = await this.loadCompacted();
+      const sanitized = await Promise.all(
+        [...records.values()].map((r) => this.sanitizeRecordForRead(r)),
+      );
+      // Drop unsafe-namespace rows (sanitizer returned null) at the read boundary.
+      // Then collapse duplicate root aliases so maintenance/QMD see exactly one
+      // namespace owner for a physical storage root, matching rebuild ownership,
+      // while preserving touch recency from every alias row.
+      return this.dropDuplicateStorageRootAliases(
+        sanitized.filter((r): r is NamespaceRecord => r !== null),
+      );
+    });
   }
 
   async listNamespaces(filter?: NamespaceCatalogFilter): Promise<NamespaceRecord[]> {
@@ -1701,7 +1721,7 @@ export class NamespaceCatalog {
       // scan, which the in-process `queueCritical` alone cannot see. Only runs
       // when we hold the lock (round 6, codex P2 — NBPmY): an unlocked rebuild
       // must not re-merge then rename, or it races a concurrent lock holder.
-      const latest = await this.loadCompacted();
+      const latest = await this.loadCompacted(true);
       for (const [ns, fresh] of latest) {
         const current = rebuilt.get(ns);
         if (!current) {
@@ -1897,53 +1917,96 @@ export class NamespaceCatalog {
     if (prior.parentNamespace !== undefined) merged.parentNamespace = prior.parentNamespace;
     return merged;
   }
-
   // ── Persistence ──────────────────────────────────────────────────────────
 
   /** Load the JSONL log and fold it into current state (last-record-wins). */
-  private async loadCompacted(): Promise<Map<string, NamespaceRecord>> {
+  private async loadCompacted(forceFresh = false): Promise<Map<string, NamespaceRecord>> {
     const records = new Map<string, NamespaceRecord>();
-    let raw: string;
+    let handle;
     try {
-      raw = await readFile(this.catalogPath, "utf8");
+      handle = await open(this.catalogPath, "r");
     } catch {
+      this.compactedCache = undefined;
       return records;
     }
-    for (const line of raw.split("\n")) {
-      const trimmed = line.trim();
-      if (trimmed.length === 0) continue;
-      let parsed: unknown;
-      try {
-        parsed = JSON.parse(trimmed);
-      } catch {
-        // Skip corrupt lines (CLAUDE.md rule #18 robustness).
-        continue;
+
+    let identity: CatalogFileIdentity | undefined;
+    try {
+      const fileStat = await handle.stat();
+      identity = {
+        size: fileStat.size,
+        mtimeMs: fileStat.mtimeMs,
+        ctimeMs: fileStat.ctimeMs,
+        ino: fileStat.ino,
+      };
+      if (
+        !forceFresh &&
+        this.compactedCache &&
+        this.compactedCache.identity.size === identity.size &&
+        this.compactedCache.identity.mtimeMs === identity.mtimeMs &&
+        this.compactedCache.identity.ctimeMs === identity.ctimeMs &&
+        this.compactedCache.identity.ino === identity.ino
+      ) {
+        await handle.close().catch(() => undefined);
+        return this.cloneCompactedRecords(this.compactedCache.records);
       }
-      const record = coerceRecord(parsed);
-      if (!record) continue;
-      // Field-level touch merge during compaction (round 6, codex P2 — ND6Cz).
-      // Touches run on PER-PROCESS write chains, so two processes (a gateway write
-      // racing a CLI/second-server read or maintenance touch) can each load the
-      // same prior record and append a full snapshot. Plain last-record-wins
-      // compaction would then discard the earlier snapshot's `lastReadAt` /
-      // `lastWriteAt` / `lastMaintenanceAt`, erasing a real touch and skewing
-      // `writtenSince`. We instead take the LATER record as the base (most recent
-      // identity/disk-derived state) and fold in the MAX of each touch field from
-      // both, so no cross-process touch recency is lost without locking the hot
-      // touch path. A destructive overwrite of real memory is never at stake here
-      // — only best-effort recency metadata.
-      const prior = records.get(record.namespace);
-      records.set(record.namespace, prior ? mergeNewerTouchFields(record, prior) : record);
+    } catch {
+      // A failed fstat cannot prove freshness. Read and parse the open file, but
+      // do not cache the result without a trustworthy identity.
     }
-    return records;
+
+    try {
+      this.onCatalogReadForTest?.();
+      const raw = await handle.readFile("utf8");
+      for (const line of raw.split("\n")) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0) continue;
+        let parsed: unknown;
+        try {
+          parsed = JSON.parse(trimmed);
+        } catch {
+          // Skip corrupt lines (CLAUDE.md rule #18 robustness).
+          continue;
+        }
+        const record = coerceRecord(parsed);
+        if (!record) continue;
+        // Preserve each touch field across cross-process full-snapshot appends.
+        // Field-level touch merge preserves the newest value for every touch
+        // field when full-snapshot appends from separate processes interleave.
+        const prior = records.get(record.namespace);
+        records.set(record.namespace, prior ? mergeNewerTouchFields(record, prior) : record);
+      }
+    } catch {
+      this.compactedCache = undefined;
+      return new Map();
+    } finally {
+      await handle.close().catch(() => undefined);
+    }
+
+    this.compactedCache = identity ? { identity, records } : undefined;
+    return this.cloneCompactedRecords(records);
+  }
+
+  private cloneCompactedRecords(
+    records: Map<string, NamespaceRecord>,
+  ): Map<string, NamespaceRecord> {
+    return new Map(
+      [...records].map(([namespace, record]) => [
+        namespace,
+        {
+          ...record,
+          lastMaintenanceAt: record.lastMaintenanceAt
+            ? { ...record.lastMaintenanceAt }
+            : undefined,
+        },
+      ]),
+    );
   }
 
   /**
    * Serialize an arbitrary read-modify-write critical section through the single
-   * per-instance chain. Every catalog mutation (touch read+merge+append, full
-   * rewrite) runs through this so they are mutually exclusive: a touch always
-   * reads the latest persisted state before appending, and a rebuild rewrite
-   * cannot interleave with a touch's append.
+   * per-instance chain. Every catalog mutation and cached catalog read runs
+   * through this queue, so cache validation and updates cannot race in-process.
    *
    * Issue #1524 adoption: delegates to the shared `MutationSerializer` (stored
    * as `criticalSection`). The util owns the rejection-recovery invariant
@@ -1964,8 +2027,13 @@ export class NamespaceCatalog {
    */
   private async appendUnchained(record: NamespaceRecord): Promise<void> {
     const line = serializeRecord(record) + "\n";
+    const lineByteLength = Buffer.byteLength(line, "utf8");
     await mkdir(this.stateDir, { recursive: true });
     await appendFile(this.catalogPath, line, "utf8");
+    if (this.onAfterCatalogAppendForTest) {
+      await this.onAfterCatalogAppendForTest();
+    }
+    await this.refreshCacheAfterAppend(record, lineByteLength);
   }
 
   /**
@@ -1982,6 +2050,53 @@ export class NamespaceCatalog {
     const tmp = `${this.catalogPath}.${process.pid}.${Date.now()}.tmp`;
     await writeFile(tmp, body, "utf8");
     await rename(tmp, this.catalogPath);
+    await this.refreshCacheIdentity(new Map(records.map((record) => [record.namespace, record])));
+  }
+
+  private async refreshCacheAfterAppend(
+    record: NamespaceRecord,
+    lineByteLength: number,
+  ): Promise<void> {
+    const cached = this.compactedCache;
+    if (!cached) return;
+    const expectedSize = cached.identity.size + lineByteLength;
+    try {
+      const fileStat = await stat(this.catalogPath);
+      if (fileStat.size !== expectedSize || fileStat.ino !== cached.identity.ino) {
+        this.compactedCache = undefined;
+        return;
+      }
+      const prior = cached.records.get(record.namespace);
+      cached.records.set(record.namespace, prior ? mergeNewerTouchFields(record, prior) : record);
+      this.compactedCache = {
+        identity: {
+          size: fileStat.size,
+          mtimeMs: fileStat.mtimeMs,
+          ctimeMs: fileStat.ctimeMs,
+          ino: fileStat.ino,
+        },
+        records: cached.records,
+      };
+    } catch {
+      this.compactedCache = undefined;
+    }
+  }
+
+  private async refreshCacheIdentity(records: Map<string, NamespaceRecord>): Promise<void> {
+    try {
+      const fileStat = await stat(this.catalogPath);
+      this.compactedCache = {
+        identity: {
+          size: fileStat.size,
+          mtimeMs: fileStat.mtimeMs,
+          ctimeMs: fileStat.ctimeMs,
+          ino: fileStat.ino,
+        },
+        records,
+      };
+    } catch {
+      this.compactedCache = undefined;
+    }
   }
 }
 

package/src/namespaces/identity.ts

@@ -1,5 +1,5 @@
-export function normalizeNamespaceIdentity(namespace: string): string {
-  return namespace.trim();
+export function normalizeNamespaceIdentity(namespace: string | null | undefined): string {
+  return namespace?.trim() ?? "";
 }
 
 export function namespaceIdentityToken(namespace: string): string {

package/src/storage/secure-line-reader.ts

@@ -0,0 +1,79 @@
+import { createReadStream } from "node:fs";
+import { open } from "node:fs/promises";
+import { createInterface } from "node:readline";
+
+import { isEncryptedFile, MAGIC_HEADER_SIZE } from "../secure-store/secure-fs.js";
+import type { MemoryActionEvent } from "../types.js";
+
+/**
+ * Stream plaintext files by line while preserving authenticated whole-file
+ * reads for encrypted files.
+ */
+export async function* readMaybeEncryptedLines(
+  filePath: string,
+  readEncryptedFile: () => Promise<string>,
+): AsyncGenerator<string> {
+  const file = await open(filePath, "r");
+  const header = Buffer.alloc(MAGIC_HEADER_SIZE);
+  try {
+    const { bytesRead } = await file.read(header, 0, header.length, 0);
+    if (isEncryptedFile(header.subarray(0, bytesRead))) {
+      yield* (await readEncryptedFile()).split("\n");
+      return;
+    }
+
+    const input = createReadStream(filePath, {
+      autoClose: false,
+      encoding: "utf8",
+      fd: file.fd,
+      start: 0,
+    });
+    const lines = createInterface({ input, crlfDelay: Infinity });
+    try {
+      for await (const line of lines) yield line;
+    } finally {
+      lines.close();
+    }
+  } finally {
+    await file.close();
+  }
+}
+
+export async function readMemoryActionEventRowsFromLines(
+  lines: AsyncIterable<string>,
+  limit: number,
+): Promise<Array<{ line: number; event: MemoryActionEvent }>> {
+  const out: Array<{ line: number; event: MemoryActionEvent }> = [];
+  let writeIndex = 0;
+  let lineNumber = 0;
+  for await (const row of lines) {
+    lineNumber += 1;
+    const line = row.trim();
+    if (!line) continue;
+    try {
+      const parsed = JSON.parse(line) as Partial<MemoryActionEvent>;
+      const outcome = parsed.outcome === "applied" || parsed.outcome === "skipped" || parsed.outcome === "failed"
+        ? parsed.outcome
+        : null;
+      if (
+        typeof parsed.timestamp === "string" &&
+        typeof parsed.action === "string" &&
+        outcome !== null
+      ) {
+        const entry = {
+          line: lineNumber,
+          event: { ...parsed, outcome } as MemoryActionEvent,
+        };
+        if (out.length < limit) {
+          out.push(entry);
+        } else {
+          out[writeIndex] = entry;
+          writeIndex = (writeIndex + 1) % limit;
+        }
+      }
+    } catch {
+      // Ignore malformed rows (fail-open).
+    }
+  }
+  return writeIndex === 0 ? out : [...out.slice(writeIndex), ...out.slice(0, writeIndex)];
+}

package/src/storage-guards.ts

@@ -0,0 +1,30 @@
+import { log } from "./logger.js";
+
+const PROJECTION_FALLBACK_WARN_INTERVAL_MS = 5 * 60_000;
+const projectionFallbackWarnedAt = new Map<string, number>();
+
+export function assertMemoryFrontmatterId(
+  fm: { id: string; category?: string; created?: string; entityRef?: string },
+): void {
+  if (typeof fm.id !== "string" || fm.id.trim().length === 0) {
+    const context = [
+      fm.category ? `category=${fm.category}` : null,
+      fm.created ? `created=${fm.created}` : null,
+      fm.entityRef ? `entityRef=${fm.entityRef}` : null,
+    ].filter(Boolean).join(" ");
+    throw new Error(
+      `memory frontmatter id must not be blank${context ? ` (${context})` : ""}`,
+    );
+  }
+}
+
+export function warnProjectionFallback(memoryDir: string, consumer: string): 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`);
+  }
+  return null;
+}

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

@@ -0,0 +1,130 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { StorageManager } from "./storage.js";
+import { encryptFileBody, filePathAad } from "./secure-store/secure-fs.js";
+import type { MemoryLifecycleEvent } from "./types.js";
+
+function lifecycleEvent(
+  eventId: string,
+  memoryId: string,
+  timestamp: string,
+): MemoryLifecycleEvent {
+  return {
+    eventId,
+    memoryId,
+    eventType: "created",
+    timestamp,
+    actor: "test",
+    ruleVersion: "1",
+  };
+}
+
+async function withLifecycleLedger(
+  rows: string[],
+  run: (storage: StorageManager, ledgerPath: string) => Promise<void>,
+): Promise<void> {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-lifecycle-stream-"));
+  const ledgerPath = path.join(memoryDir, "state", "memory-lifecycle-ledger.jsonl");
+  await mkdir(path.dirname(ledgerPath), { recursive: true });
+  await writeFile(ledgerPath, `${rows.join("\n")}\n`, "utf8");
+  try {
+    await run(new StorageManager(memoryDir), ledgerPath);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+}
+
+test("readAllMemoryLifecycleEvents streams plaintext rows and preserves fail-open sorting", async () => {
+  const later = lifecycleEvent("event-z", "memory-b", "2026-01-03T00:00:00.000Z");
+  const earlier = lifecycleEvent("event-a", "memory-a", "2026-01-02T00:00:00.000Z");
+  const earliest = lifecycleEvent("event-b", "memory-a", "2026-01-01T00:00:00.000Z");
+
+  await withLifecycleLedger([
+    JSON.stringify(later),
+    "{malformed-json",
+    JSON.stringify({ ...earlier, actor: 42 }),
+    JSON.stringify(earlier),
+    "   ",
+    JSON.stringify(earliest),
+  ], async (storage) => {
+    let secureWholeFileReads = 0;
+    const privateStorage = storage as unknown as {
+      readStorageSecureFile(filePath: string): Promise<string>;
+    };
+    privateStorage.readStorageSecureFile = async () => {
+      secureWholeFileReads += 1;
+      throw new Error("plaintext lifecycle ledger must not use whole-file reads");
+    };
+
+    const events = await storage.readAllMemoryLifecycleEvents();
+
+    assert.deepEqual(events, [earliest, earlier, later]);
+    assert.equal(secureWholeFileReads, 0);
+  });
+});
+
+test("readMemoryLifecycleEvents applies its limit after streamed lifecycle sorting", async () => {
+  const first = lifecycleEvent("event-1", "memory-a", "2026-01-01T00:00:00.000Z");
+  const second = lifecycleEvent("event-2", "memory-a", "2026-01-02T00:00:00.000Z");
+  const third = lifecycleEvent("event-3", "memory-b", "2026-01-01T00:00:00.000Z");
+
+  await withLifecycleLedger([
+    JSON.stringify(third),
+    JSON.stringify(first),
+    JSON.stringify(second),
+  ], async (storage) => {
+    assert.deepEqual(await storage.readMemoryLifecycleEvents(2), [second, third]);
+  });
+});
+
+test("readAllMemoryLifecycleEvents keeps the authenticated encrypted-file fallback", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-lifecycle-encrypted-"));
+  const ledgerPath = path.join(memoryDir, "state", "memory-lifecycle-ledger.jsonl");
+  const event = lifecycleEvent("event-encrypted", "memory-a", "2026-01-01T00:00:00.000Z");
+  const key = Buffer.alloc(32, 7);
+  await mkdir(path.dirname(ledgerPath), { recursive: true });
+  await writeFile(
+    ledgerPath,
+    encryptFileBody(`${JSON.stringify(event)}\n`, key, filePathAad(ledgerPath, memoryDir)),
+  );
+  try {
+    const storage = new StorageManager(memoryDir);
+    storage.setSecureStoreKey(key);
+    assert.deepEqual(await storage.readAllMemoryLifecycleEvents(), [event]);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("readMemoryActionEventRows streams the action ledger and keeps source line numbers", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-action-stream-"));
+  const ledgerPath = path.join(memoryDir, "state", "memory-actions.jsonl");
+  const first = { timestamp: "2026-01-01T00:00:00.000Z", action: "store_note", outcome: "applied" };
+  const second = { timestamp: "2026-01-02T00:00:00.000Z", action: "discard", outcome: "skipped" };
+  await mkdir(path.dirname(ledgerPath), { recursive: true });
+  await writeFile(
+    ledgerPath,
+    `${JSON.stringify(first)}\n{malformed-json\n${JSON.stringify(second)}\n`,
+    "utf8",
+  );
+  try {
+    const storage = new StorageManager(memoryDir);
+    let secureWholeFileReads = 0;
+    const privateStorage = storage as unknown as {
+      readStorageSecureFile(filePath: string): Promise<string>;
+    };
+    privateStorage.readStorageSecureFile = async () => {
+      secureWholeFileReads += 1;
+      throw new Error("plaintext action ledger must not use whole-file reads");
+    };
+
+    assert.deepEqual(await storage.readMemoryActionEventRows(1), [{ line: 3, event: second }]);
+    assert.equal(secureWholeFileReads, 0);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/storage.ts

@@ -4,7 +4,12 @@ import { createHash } from "node:crypto"
 import { normalizeContent, computeContentHash } from "./content-hash.js";;
 import path from "node:path";
 import { log } from "./logger.js";
+import { assertMemoryFrontmatterId, warnProjectionFallback } from "./storage-guards.js";
 import { MemoryReadStore } from "./storage/memory-read-store.js";
+import {
+  readMaybeEncryptedLines,
+  readMemoryActionEventRowsFromLines,
+} from "./storage/secure-line-reader.js";
 import { selfDeps } from "./orchestration/self-deps.js";
 import { EntityStore } from "./storage/entity-store.js";
 import { IdentityContinuityStore } from "./storage/identity-continuity-store.js";
@@ -304,6 +309,7 @@ function stripCitationMarkersForHashRemoval(value: string, template: string): st
 }
 
 function serializeFrontmatter(fm: MemoryFrontmatter): string {
+  assertMemoryFrontmatterId(fm);
   const lines = [
     "---",
     `id: ${fm.id}`,
@@ -5180,38 +5186,16 @@ export class StorageManager {
 
   async readMemoryActionEventRows(limit: number = 200): Promise<Array<{ line: number; event: MemoryActionEvent }>> {
     const cappedLimit = Math.max(0, Math.floor(limit));
-    if (cappedLimit === 0) return [];
+    if (cappedLimit === 0 || Number.isNaN(cappedLimit)) return [];
 
     try {
-      const raw = await this.readStorageSecureFile(this.memoryActionsPath);
-      const out: Array<{ line: number; event: MemoryActionEvent }> = [];
-      const lines = raw.split("\n");
-      for (let i = lines.length - 1; i >= 0 && out.length < cappedLimit; i -= 1) {
-        const line = lines[i]?.trim();
-        if (!line) continue;
-        try {
-          const parsed = JSON.parse(line) as Partial<MemoryActionEvent>;
-          const outcome = parsed.outcome === "applied" || parsed.outcome === "skipped" || parsed.outcome === "failed"
-            ? parsed.outcome
-            : null;
-          if (
-            typeof parsed.timestamp === "string" &&
-            typeof parsed.action === "string" &&
-            outcome !== null
-          ) {
-            out.push({
-              line: i + 1,
-              event: {
-                ...parsed,
-                outcome,
-              } as MemoryActionEvent,
-            });
-          }
-        } catch {
-          // Ignore malformed rows (fail-open).
-        }
-      }
-      return out.reverse();
+      return await readMemoryActionEventRowsFromLines(
+        readMaybeEncryptedLines(
+          this.memoryActionsPath,
+          () => this.readStorageSecureFile(this.memoryActionsPath),
+        ),
+        cappedLimit,
+      );
     } catch (err) {
       if (err instanceof SecureStoreLockedError) throw err;
       if (!isErrnoCode(err, "ENOENT")) throw err;
@@ -5221,10 +5205,11 @@ export class StorageManager {
 
   async readAllMemoryLifecycleEvents(): Promise<MemoryLifecycleEvent[]> {
     try {
-      const raw = await this.readStorageSecureFile(this.memoryLifecycleLedgerPath);
       const out: MemoryLifecycleEvent[] = [];
-      const lines = raw.split("\n");
-      for (const line of lines) {
+      for await (const line of readMaybeEncryptedLines(
+        this.memoryLifecycleLedgerPath,
+        () => this.readStorageSecureFile(this.memoryLifecycleLedgerPath),
+      )) {
         const row = line.trim();
         if (!row) continue;
         try {
@@ -6037,8 +6022,8 @@ export class StorageManager {
         lastAccessed: entry.lastAccessed,
       };
 
-      const fileContent = `${serializeFrontmatter(newFm)}\n\n${memory.content}\n`;
       try {
+        const fileContent = `${serializeFrontmatter(newFm)}\n\n${memory.content}\n`;
         await this.writeStorageSecureFile(memory.path, fileContent);
         updated++;
       } catch (err) {
@@ -6087,8 +6072,7 @@ export class StorageManager {
 
   async getProjectedMemoryState(id: string): Promise<MemoryProjectionCurrentState | null> {
     const projected = readProjectedMemoryState(this.baseDir, id);
-    if (projected) return projected;
-
+    if (projected) return projected; warnProjectionFallback(this.baseDir, "getProjectedMemoryState");
     const active = await this.getMemoryById(id);
     if (active) return this.toProjectedCurrentState(active, "active");
 
@@ -6101,7 +6085,8 @@ export class StorageManager {
   async browseProjectedMemories(
     options: ProjectedMemoryBrowseOptions,
   ): Promise<ProjectedMemoryBrowsePage | null> {
-    return readProjectedMemoryBrowse(this.baseDir, options);
+    return readProjectedMemoryBrowse(this.baseDir, options)
+      ?? warnProjectionFallback(this.baseDir, "browseProjectedMemories");
   }
 
   async getProjectedGovernanceRecord(): Promise<ReturnType<typeof readProjectedGovernanceRecord>> {
@@ -6141,8 +6126,7 @@ export class StorageManager {
     if (cappedLimit === 0) return [];
 
     const projected = readProjectedMemoryTimeline(this.baseDir, memoryId, cappedLimit);
-    if (projected && projected.length > 0) return projected;
-
+    if (projected && projected.length > 0) return projected; warnProjectionFallback(this.baseDir, "getMemoryTimeline");
     const events = await this.readAllMemoryLifecycleEvents();
     return events.filter((event) => event.memoryId === memoryId).slice(-cappedLimit);
   }
@@ -6399,9 +6383,8 @@ export class StorageManager {
         updated: now,
       };
 
-      const fileContent = `${serializeFrontmatter(updatedFm)}\n\n${memory.content}\n`;
-
       try {
+        const fileContent = `${serializeFrontmatter(updatedFm)}\n\n${memory.content}\n`;
         await this.writeStorageSecureFile(memory.path, fileContent);
         await this.appendGeneratedMemoryLifecycleEventFailOpen("storage.archiveMemories", {
           memoryId: id,