@remnic/core 10.0.14 → 10.0.16

package/src/storage/entity-canonical-id-migration.ts

@@ -22,6 +22,11 @@ import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
 import { assertPathInsideRoot } from "../utils/path-containment.js";
 import { withEntityCanonicalMutationLock } from "./entity-canonical-id-lock.js";
 import { assertSafeEntityId } from "./entity-id-safety.js";
+import { isMalformedEntityRecord } from "../utils/malformed-entity-record.js";
+import {
+  isMacOsReplicationJunkBasename,
+  warnIgnoredMacOsReplicationJunk,
+} from "../utils/macos-replication-junk.js";
 
 import {
   ENTITY_CANONICAL_ID_MIGRATION_FILE,
@@ -100,7 +105,7 @@ async function fingerprintEntityEntries(entitiesDir: string): Promise<string> {
   let names: string[];
   try {
     names = (await readdir(entitiesDir))
-      .filter((name) => path.extname(name) === ".md")
+      .filter((name) => path.extname(name) === ".md" && !isMacOsReplicationJunkBasename(name))
       .sort();
   } catch (error) {
     if (isErrnoCode(error, "ENOENT")) return "missing";
@@ -386,10 +391,16 @@ async function readSafeEntityEntries(entitiesDir: string): Promise<string[]> {
  */
 export type BlockedEntityPairs = Map<string, string>;
 
+interface EntityScanNotes {
+  junk: Set<string>;
+  malformed: Set<string>;
+}
+
 async function discoverMappings(
   deps: EntityCanonicalIdMigrationDependencies,
   knownMappings: Readonly<Record<string, string>> = {},
   blocked: BlockedEntityPairs = new Map(),
+  scanNotes?: EntityScanNotes,
 ): Promise<Record<string, string>> {
   const mappings: Record<string, string> = {};
   const canonicalOwners = new Map<string, string[]>();
@@ -401,21 +412,29 @@ async function discoverMappings(
   blocked.clear();
   const entityEntries = await readSafeEntityEntries(deps.entitiesDir);
   for (const entry of entityEntries) {
+    // AppleDouble (`._*`) and `.DS_Store` are Finder metadata, not entity
+    // files. A real file that cannot be parsed is left in place: this scan
+    // runs during directory init, and aborting it took the daemon down.
+    // Skipping is the same outcome as the old throw (the file is not
+    // rewritten) without refusing to boot. Symlink checks above still run.
+    if (isMacOsReplicationJunkBasename(entry)) {
+      scanNotes?.junk.add(entry);
+      continue;
+    }
     if (!entry.endsWith(".md")) continue;
     const legacyId = entry.slice(0, -".md".length);
     assertSafeEntityId(legacyId);
     const legacyPath = deps.resolveEntityFilePath(legacyId);
     if (legacyPath === null) continue;
     const entityContent = await deps.readStorageSecureFile(legacyPath);
-    if (
-      !/^#[ \t]+[^\r\n \t]/m.test(entityContent)
-      || !/^\*\*Type:\*\*[ \t]*[^\r\n \t]/m.test(entityContent)
-    ) {
-      throw new Error(`Cannot migrate malformed entity file ${entry}: missing name heading or type.`);
+    if (isMalformedEntityRecord(entityContent)) {
+      scanNotes?.malformed.add(entry);
+      continue;
     }
     const entity = deps.parseEntityFile(entityContent);
     if (!entity.name.trim() || !entity.type.trim()) {
-      throw new Error(`Cannot migrate malformed entity file ${entry}: missing name or type.`);
+      scanNotes?.malformed.add(entry);
+      continue;
     }
     const canonicalId = deps.normalizeEntityName(entity.name, entity.type);
     assertSafeEntityId(canonicalId);
@@ -596,12 +615,14 @@ async function rewriteRelationshipTargets(
   let rewritten = false;
   const entries = await readSafeEntityEntries(deps.entitiesDir);
   for (const entry of entries) {
-    if (!entry.endsWith(".md")) continue;
+    if (!entry.endsWith(".md") || isMacOsReplicationJunkBasename(entry)) continue;
     const entityPath = deps.resolveEntityFilePath(entry.slice(0, -".md".length));
     if (entityPath === null) continue;
     const observedEntityFingerprint = await fingerprintPath(entityPath);
     if (observedEntityFingerprint === "missing") continue;
-    const entity = deps.parseEntityFile(await deps.readStorageSecureFile(entityPath));
+    const entityRaw = await deps.readStorageSecureFile(entityPath);
+    if (isMalformedEntityRecord(entityRaw)) continue;
+    const entity = deps.parseEntityFile(entityRaw);
     const relationships = entity.relationships.map((relationship) => {
       const target = mappings[relationship.target];
       return target ? { ...relationship, target } : relationship;
@@ -611,7 +632,9 @@ async function rewriteRelationshipTargets(
       deps.stateDir,
       async (refreshEntityLock) => {
         if (!(await refreshLock())) throw new Error("Lost entity canonical-id migration lock.");
-        const latestEntity = deps.parseEntityFile(await deps.readStorageSecureFile(entityPath));
+        const latestRaw = await deps.readStorageSecureFile(entityPath);
+        if (isMalformedEntityRecord(latestRaw)) return false;
+        const latestEntity = deps.parseEntityFile(latestRaw);
         if ((await fingerprintPath(entityPath)) !== observedEntityFingerprint) return false;
         const latestRelationships = latestEntity.relationships.map((relationship) => {
           const target = mappings[relationship.target];
@@ -794,6 +817,15 @@ async function migrateEntityFilePair(
     const entityContent = await deps.readStorageSecureFile(legacyPath);
     await assertNotSymlink(legacyPath, legacyId);
     await assertEntityContentUnchanged(deps, legacyPath, entityContent, legacyId);
+    // A journal entry must not relocate Finder metadata or a record this scan
+    // would leave in place. readStorageSecureFile has already decrypted, so
+    // the check is on that plaintext. The mapping stays for a later repair.
+    if (
+      isMacOsReplicationJunkBasename(path.basename(legacyPath))
+      || isMalformedEntityRecord(entityContent)
+    ) {
+      return { deferred: false, progressed: false };
+    }
     let canonicalFingerprintAfterWrite: string | null = null;
     try {
       await deps.writeStorageSecureFile(canonicalPath, entityContent, entityEncrypted);
@@ -864,6 +896,7 @@ export async function migrateLegacyEntityCanonicalIds(
         };
       }
       const blocked: BlockedEntityPairs = new Map();
+      const scanNotes: EntityScanNotes = { junk: new Set(), malformed: new Set() };
       // Parks for pairs whose files are GONE, tracked separately from
       // collision parks: pruneBlocked drops these (the canonical file is gone
       // too), and the rescan's blocked.clear() would otherwise silence them
@@ -886,6 +919,16 @@ export async function migrateLegacyEntityCanonicalIds(
             + "The stale journal entries were removed; references to those legacy ids do not resolve either way.",
           );
         }
+        warnIgnoredMacOsReplicationJunk(deps.entitiesDir, scanNotes.junk.size, (message) => {
+          log.warn(`entity canonical-id migration ${message}`);
+        });
+        if (scanNotes.malformed.size > 0) {
+          const names = [...scanNotes.malformed].sort().join(", ");
+          log.warn(
+            `entity canonical-id migration skipped ${scanNotes.malformed.size} malformed entity file(s): ${names}. `
+            + "Each file was left in place; startup continues. Fix or remove the file to migrate it.",
+          );
+        }
         // Every finish() path either just rewrote references (main/reconcile
         // paths), has none to rewrite (empty mappings), or observed no marker
         // (stable no-op) — so the CONSUMED generation is removed here. A fresh
@@ -997,7 +1040,7 @@ export async function migrateLegacyEntityCanonicalIds(
         if (!(await lock.refresh())) throw new Error("Lost entity canonical-id migration lock.");
         const discoveredBefore = rejectMappingCycles(
           state.mappings,
-          await discoverMappings(deps, state.mappings, blocked),
+          await discoverMappings(deps, state.mappings, blocked, scanNotes),
         );
         const revivedBefore = await pruneBlocked();
         const mergedBefore = collapseMappings(mergeDiscoveredMappings(state.mappings, discoveredBefore));
@@ -1046,7 +1089,7 @@ export async function migrateLegacyEntityCanonicalIds(
           if (!(await lock.refresh())) throw new Error("Lost entity canonical-id migration lock.");
           const discoveredAfter = rejectMappingCycles(
             state.mappings,
-            await discoverMappings(deps, state.mappings, blocked),
+            await discoverMappings(deps, state.mappings, blocked, scanNotes),
           );
           // Reconcile before declaring completion: this rescan can resolve a
           // park (another writer removed the legacy file), and completing
@@ -1107,7 +1150,7 @@ export async function migrateLegacyEntityCanonicalIds(
         if (!(await lock.refresh())) throw new Error("Lost entity canonical-id migration lock.");
         const discoveredAfter = rejectMappingCycles(
           state.mappings,
-          await discoverMappings(deps, state.mappings, blocked),
+          await discoverMappings(deps, state.mappings, blocked, scanNotes),
         );
         // A park resolved after the rewrite pass is promoted here, and a
         // promotion still has to be APPLIED. Completing on `discoveredAfter`

package/src/storage/entity-store.ts

@@ -10,12 +10,17 @@
  *   - fragmented-entity merge (consolidation)
  */
 
-import { readdir, unlink } from "node:fs/promises";
+import { lstat, readdir, realpath, unlink } from "node:fs/promises";
 import path from "node:path";
 import { checkCorpusReadAbort, type CorpusReadOptions } from "../corpus-read-cancellation.js";
 import { normalizeEntityStructuredSection, sortStructuredSectionsBySchema } from "../entity-schema.js";
 import { withEntityCanonicalMutationLock } from "./entity-canonical-id-lock.js";
+import { isMalformedEntityRecord } from "../utils/malformed-entity-record.js";
 import { log } from "../logger.js";
+import {
+  warnIgnoredMacOsReplicationJunk,
+  withoutMacOsReplicationJunk,
+} from "../utils/macos-replication-junk.js";
 import { getCachedEntities, setCachedEntities } from "../memory-cache.js";
 import type { VersionTrigger } from "../page-versioning.js";
 import { SecureStoreLockedError } from "../secure-store/secure-fs.js";
@@ -28,6 +33,7 @@ import type {
   ScoredEntity,
 } from "../types.js";
 import { isErrnoCode } from "../utils/errno.js";
+import { pathIsInside } from "../utils/path-containment.js";
 import {
   reconcileIfJournalMovedSync,
   requestEntityCanonicalIdReconcileSync,
@@ -79,6 +85,9 @@ export interface EntityStoreDeps {
 }
 
 export class EntityStore {
+  /** Filename → file identity of the last indexable check. Unchanged files are not reread. */
+  private readonly entityIndexableCache = new Map<string, { identity: string; ok: boolean }>();
+
   constructor(
     private readonly deps: EntityStoreDeps,
   ) {}
@@ -378,15 +387,127 @@ export class EntityStore {
     }
   }
 
-  /** Return sorted list of entity filenames (without .md extension) */
+  /**
+   * True when `entities/` is a real directory inside this memory root.
+   * `realpath` on a symlinked root would treat the link target as trusted,
+   * so the check uses `lstat` first and refuses the scan when the root
+   * itself is a symlink.
+   */
+  private async isTrustedEntitiesRoot(): Promise<boolean> {
+    let rootStat;
+    try {
+      rootStat = await lstat(this.deps.entitiesDir);
+    } catch (err) {
+      if (isErrnoCode(err, "ENOENT")) return false;
+      throw err;
+    }
+    if (rootStat.isSymbolicLink() || !rootStat.isDirectory()) return false;
+    let memoryRoot: string;
+    let entitiesReal: string;
+    try {
+      memoryRoot = await realpath(this.deps.baseDir);
+      entitiesReal = await realpath(this.deps.entitiesDir);
+    } catch (err) {
+      if (isErrnoCode(err, "ENOENT")) return false;
+      throw err;
+    }
+    return pathIsInside(memoryRoot, entitiesReal);
+  }
+
+  /**
+   * Entity directory listing with macOS replication junk removed.
+   * One summary warning per directory and count, shared with migration.
+   * A symlinked entities root yields an empty list and is not read.
+   */
+  private async readEntityDirectoryNames(): Promise<string[]> {
+    if (!(await this.isTrustedEntitiesRoot())) return [];
+    const entries = await readdir(this.deps.entitiesDir);
+    const { kept, ignored } = withoutMacOsReplicationJunk(entries, (name) => name);
+    warnIgnoredMacOsReplicationJunk(this.deps.entitiesDir, ignored, (message) => {
+      log.warn(`entity load ${message}`);
+    });
+    return kept;
+  }
+
+  /**
+   * A directory entry is readable only when it is a regular file.
+   * Symlinks, FIFOs, and devices are skipped before any read. The entities
+   * root is refused separately, before the directory is listed.
+   */
+  private async isContainedRegularEntityFile(file: string): Promise<boolean> {
+    const filePath = path.join(this.deps.entitiesDir, file);
+    let entryStat;
+    try {
+      entryStat = await lstat(filePath);
+    } catch (err) {
+      if (isErrnoCode(err, "ENOENT")) return false;
+      throw err;
+    }
+    return !entryStat.isSymbolicLink() && entryStat.isFile();
+  }
+
+  /**
+   * Malformed entity files stay on disk (startup must not relocate them)
+   * and stay out of merge, so a fragment merge cannot delete them.
+   * Unchanged files reuse the previous result so a name listing does not
+   * reread the whole directory on every extraction write.
+   */
+  private async isIndexableEntityMarkdown(file: string): Promise<boolean> {
+    const filePath = path.join(this.deps.entitiesDir, file);
+    let entryStat;
+    try {
+      entryStat = await lstat(filePath);
+    } catch (err) {
+      if (isErrnoCode(err, "ENOENT")) return false;
+      throw err;
+    }
+    if (entryStat.isSymbolicLink() || !entryStat.isFile()) return false;
+    const identity = `${entryStat.dev}:${entryStat.ino}:${entryStat.mtimeMs}:${entryStat.size}`;
+    const cached = this.entityIndexableCache.get(file);
+    if (cached?.identity === identity) return cached.ok;
+    try {
+      const content = await this.deps.readStorageSecureFile(filePath);
+      // Missing `**Type:**` still parses (type defaults to "other"). Only an
+      // empty name, including a tab heading, stays out of the name list.
+      const parsed = parseEntityFile(content, this.deps.entitySchemas);
+      const ok = parsed.name.trim().length > 0 && parsed.type.trim().length > 0;
+      this.entityIndexableCache.set(file, { identity, ok });
+      return ok;
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
+      if (!isErrnoCode(err, "ENOENT")) throw err;
+      return false;
+    }
+  }
+
+  /**
+   * Sorted entity filenames (without .md). Malformed records stay on disk
+   * and are omitted, so extraction, matching, and entity list cannot reuse them.
+   */
   async listEntityNames(): Promise<string[]> {
     try {
-      const entries = await readdir(this.deps.entitiesDir);
-      return entries
-        .filter((e) => e.endsWith(".md"))
-        .map((e) => e.replace(".md", ""))
-        .sort();
-    } catch {
+      const entries = await this.readEntityDirectoryNames();
+      const mdFiles = entries.filter((e) => e.endsWith(".md"));
+      const names: string[] = [];
+      const batchSize = 100;
+      for (let i = 0; i < mdFiles.length; i += batchSize) {
+        const resolved = await Promise.all(mdFiles.slice(i, i + batchSize).map(async (file) => {
+          try {
+            if (!(await this.isIndexableEntityMarkdown(file))) return null;
+          } catch (err) {
+            if (err instanceof SecureStoreLockedError) throw err;
+            return null;
+          }
+          return file.slice(0, -3);
+        }));
+        for (const name of resolved) {
+          if (name) names.push(name);
+        }
+      }
+      names.sort();
+      return names;
+    } catch (err) {
+      if (err instanceof SecureStoreLockedError) throw err;
       return [];
     }
   }
@@ -404,8 +525,10 @@ export class EntityStore {
       // completed migration's reference scan.
       const wrote = await withEntityCanonicalMutationLock(stateDir, async () => {
         const raw = await this.readEntity(entityName);
-        if (!raw) return false;
-        const serialized = serializeEntityFile(parseEntityFile(raw, this.deps.entitySchemas), this.deps.entitySchemas, this.deps.okfConformanceEnabled());
+        if (!raw || isMalformedEntityRecord(raw)) return false;
+        const parsed = parseEntityFile(raw, this.deps.entitySchemas);
+        if (!parsed.name.trim() || !parsed.type.trim()) return false;
+        const serialized = serializeEntityFile(parsed, this.deps.entitySchemas, this.deps.okfConformanceEnabled());
         if (raw.trimEnd() === serialized.trimEnd()) return false;
         const filePath = this.deps.resolveEntityFilePath(entityName);
         if (filePath === null) return false;
@@ -513,7 +636,7 @@ export class EntityStore {
     if (cached) return cached;
 
     try {
-      const entries = await readdir(this.deps.entitiesDir);
+      const entries = await this.readEntityDirectoryNames();
       const mdFiles = entries.filter((e) => e.endsWith(".md"));
       if (mdFiles.length === 0) return [];
 
@@ -530,6 +653,7 @@ export class EntityStore {
         const results = await Promise.all(
           batch.map(async (entry) => {
             try {
+              if (!(await this.isContainedRegularEntityFile(entry))) return null;
               return await this.deps.readStorageSecureFile(path.join(this.deps.entitiesDir, entry));
             } catch (err) {
               if (err instanceof SecureStoreLockedError) throw err;
@@ -539,7 +663,10 @@ export class EntityStore {
           }),
         );
         for (const content of results) {
-          if (content !== null) entities.push(parseEntityFile(content, this.deps.entitySchemas));
+          if (content === null) continue;
+          const entity = parseEntityFile(content, this.deps.entitySchemas);
+          if (!entity.name.trim() || !entity.type.trim()) continue;
+          entities.push(entity);
         }
       }
       // A signal that fired during the last batch's await would otherwise publish
@@ -642,8 +769,13 @@ export class EntityStore {
   private async mergeFragmentedEntitiesUnlocked(): Promise<number> {
     let merged = 0;
     try {
-      const entries = await readdir(this.deps.entitiesDir);
-      const mdFiles = entries.filter((e) => e.endsWith(".md"));
+      const entries = await this.readEntityDirectoryNames();
+      const mdFiles: string[] = [];
+      for (const file of entries) {
+        if (!file.endsWith(".md")) continue;
+        if (!(await this.isIndexableEntityMarkdown(file))) continue;
+        mdFiles.push(file);
+      }
 
       // Group files by their canonical name
       const groups = new Map<string, string[]>();
@@ -660,9 +792,31 @@ export class EntityStore {
         groups.get(canonical)!.push(file);
       }
 
+      // A malformed or otherwise non-indexable file is absent from `files`.
+      // Writing the canonical path anyway would replace that file, then
+      // delete the fragments that still hold the only readable copy.
+      const canonicalDestinationOccupied = async (
+        canonicalName: string,
+        members: readonly string[],
+      ): Promise<boolean> => {
+        if (members.includes(canonicalName)) return false;
+        try {
+          await lstat(path.join(this.deps.entitiesDir, canonicalName));
+          return true;
+        } catch (err) {
+          if (isErrnoCode(err, "ENOENT")) return false;
+          throw err;
+        }
+      };
+
       // Merge groups with more than one file
       for (const [canonical, files] of groups) {
         if (files.length <= 1) continue;
+        const canonicalName = `${canonical}.md`;
+        if (await canonicalDestinationOccupied(canonicalName, files)) {
+          log.warn(`skipped entity merge into occupied ${canonicalName}`);
+          continue;
+        }
 
         // Parse all files and merge into a single EntityFile
         const mergedEntity: EntityFile = {
@@ -901,7 +1055,11 @@ export class EntityStore {
         mergedEntity.created = mergedEntity.created || mergedEntity.updated || new Date().toISOString();
         mergedEntity.updated = mergedEntity.updated || new Date().toISOString();
 
-        const canonicalPath = path.join(this.deps.entitiesDir, `${canonical}.md`);
+        const canonicalPath = path.join(this.deps.entitiesDir, canonicalName);
+        if (await canonicalDestinationOccupied(canonicalName, files)) {
+          log.warn(`skipped entity merge into occupied ${canonicalName}`);
+          continue;
+        }
         await this.deps.writeStorageSecureFile(canonicalPath, serializeEntityFile(mergedEntity, this.deps.entitySchemas, this.deps.okfConformanceEnabled()));
         this.deps.bumpEntityMutationVersion();
 

package/src/storage/memory-read-store.ts

@@ -17,6 +17,8 @@ import { SecureStoreLockedError, readMaybeEncryptedFile } from "../secure-store/
 import { type BufferSurpriseEvent, type CompressionGuidelineOptimizerState, type MemoryFile, type PluginConfig, confidenceTier } from "../types.js";
 import { RECALL_FALLBACK_DIRS } from "../utils/category-dir.js";
 import { isErrnoCode } from "../utils/errno.js";
+import { isPopulatedUnnamedEntityRecord } from "../utils/malformed-entity-record.js";
+import { isMacOsReplicationJunkBasename } from "../utils/macos-replication-junk.js";
 import { assertPathInsideRoot } from "../utils/path-containment.js";
 import { isAbortError } from "../abort-error.js";
 import { checkCorpusReadAbort, type CorpusReadOptions } from "../corpus-read-cancellation.js";
@@ -97,6 +99,18 @@ function isPropagatableReadError(err: unknown): boolean {
   return typeof code === "string" && code !== "ENOENT";
 }
 
+/**
+ * Markdown under this store's `entities/` directory. The first relative
+ * segment must be `entities`; a memory root whose absolute path contains
+ * that name is not an entity store.
+ */
+function isStoreEntityMarkdown(baseDir: string, filePath: string): boolean {
+  if (!filePath.endsWith(".md")) return false;
+  const relative = path.relative(baseDir, filePath);
+  if (relative.length === 0 || relative.startsWith("..") || path.isAbsolute(relative)) return false;
+  return relative.split(path.sep)[0] === "entities";
+}
+
 export class MemoryReadStore {
   constructor(
     private readonly deps: MemoryReadStoreDeps,
@@ -117,7 +131,7 @@ export class MemoryReadStore {
       try {
         const entries = await readdir(this.deps.wearablesDir, { withFileTypes: true });
         sources = entries
-          .filter((entry) => entry.isDirectory())
+          .filter((entry) => entry.isDirectory() && !isMacOsReplicationJunkBasename(entry.name))
           .map((entry) => entry.name);
       } catch (err) {
         if ((err as NodeJS.ErrnoException).code === "ENOENT") return [];
@@ -134,7 +148,7 @@ export class MemoryReadStore {
         throw err;
       }
       for (const entry of entries) {
-        if (!entry.endsWith(".md")) continue;
+        if (isMacOsReplicationJunkBasename(entry) || !entry.endsWith(".md")) continue;
         const date = entry.slice(0, -3);
         if (!isValidTranscriptDate(date)) continue;
         days.push({ source, date });
@@ -170,6 +184,7 @@ export class MemoryReadStore {
             // in-flight dedup, so every abandoned recall used to start another
             // full walk of it (issue #2307).
             checkCorpusReadAbort(options);
+            if (isMacOsReplicationJunkBasename(entry.name)) continue;
             const fullPath = path.join(dir, entry.name);
             if (entry.isDirectory()) {
               await readDir(fullPath);
@@ -287,6 +302,7 @@ export class MemoryReadStore {
         checkCorpusReadAbort(options);
         // Never follow symlinked entries out of the store.
         if (entry.isSymbolicLink()) continue;
+        if (isMacOsReplicationJunkBasename(entry.name)) continue;
         const fullPath = path.join(dir, entry.name);
         if (entry.isDirectory()) {
           subdirs.push(fullPath);
@@ -500,6 +516,7 @@ export class MemoryReadStore {
         const entries = await readdir(dir, { withFileTypes: true });
         const subdirs: string[] = [];
         for (const entry of entries) {
+          if (isMacOsReplicationJunkBasename(entry.name)) continue;
           const fullPath = path.join(dir, entry.name);
           if (entry.isDirectory()) {
             subdirs.push(fullPath);
@@ -536,6 +553,15 @@ export class MemoryReadStore {
   async readMemoryByPath(filePath: string): Promise<MemoryFile | null> {
     try {
       const raw = await readMaybeEncryptedFile(filePath, this.deps._secureStoreKey, this.deps.baseDir);
+      // Entity bodies with text but no name heading stay out of recall,
+      // including contextual QMD hits. An empty body still resolves through
+      // frontmatter and the canonical filename. A missing type line is still
+      // an entity. QMD query behavior is unchanged. Classification is
+      // relative to this store root: an absolute path that merely contains
+      // an `entities` segment is still an ordinary fact.
+      if (isStoreEntityMarkdown(this.deps.baseDir, filePath) && isPopulatedUnnamedEntityRecord(raw)) {
+        return null;
+      }
       // Note: the outer catch intentionally swallows most errors (ENOENT etc.)
       // but SecureStoreLockedError must propagate — see re-throw below.
       const parsed = parseFrontmatter(raw);
@@ -555,8 +581,7 @@ export class MemoryReadStore {
       // YAML frontmatter. Build a synthetic MemoryFile so entity files returned by
       // the direct retrieval agent participate in boostSearchResults and last-recall
       // tracking rather than being silently dropped.
-      const normalizedPath = filePath.split(path.sep).join("/");
-      if (normalizedPath.includes("/entities/") && filePath.endsWith(".md")) {
+      if (isStoreEntityMarkdown(this.deps.baseDir, filePath)) {
         const entity = parseEntityFile(raw, this.deps.entitySchemas);
         if (!entity.name) return null;
         const nameWithoutExt = path.basename(filePath, ".md");
@@ -859,7 +884,7 @@ export class MemoryReadStore {
       const files = await readdir(this.deps.questionsDir);
       const questions = [];
       for (const file of files) {
-        if (!file.endsWith(".md")) continue;
+        if (isMacOsReplicationJunkBasename(file) || !file.endsWith(".md")) continue;
         const filePath = path.join(this.deps.questionsDir, file);
         const raw = await readMaybeEncryptedFile(filePath, this.deps._secureStoreKey, this.deps.baseDir);
         const parsed = this.deps.parseQuestionFile(raw, filePath);

package/src/storage/supersession-audit.ts

@@ -5,6 +5,7 @@ import path from "node:path";
 import { stripAttributesSuffix } from "../structured-attributes.js";
 import type { MemoryFile } from "../types.js";
 import { isErrnoCode } from "../utils/errno.js";
+import { isMacOsReplicationJunkBasename } from "../utils/macos-replication-junk.js";
 
 export interface SupersessionAuditLookup {
   correctionsDir: string;
@@ -27,6 +28,7 @@ export async function hasSupersessionAudit(
   }
 
   for (const entry of entries) {
+    if (isMacOsReplicationJunkBasename(entry.name)) continue;
     if (!entry.isFile() || !entry.name.endsWith(".md")) continue;
     const memory = await lookup.readMemoryByPath(path.join(lookup.correctionsDir, entry.name));
     if (

package/src/storage.ts

@@ -65,6 +65,7 @@ import { readEntityAliasConfigSync } from "./storage/entity-alias-config.js";
 import { assertSafeEntityId } from "./storage/entity-id-safety.js";
 export { normalizeEntityName } from "./entity-id-normalization.js";
 import { isErrnoCode } from "./utils/errno.js";
+import { isMacOsReplicationJunkBasename } from "./utils/macos-replication-junk.js";
 import { getCategoryDir, categoryDirName } from "./utils/category-dir.js";
 import { decodeYamlScalar } from "./utils/yaml-scalar.js";
 import { qmdCollectionPathParts, qmdResultPathCandidates } from "./orchestration/qmd-result-resolver.js";
@@ -4882,7 +4883,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
 
     const readDir = async (dir: string) => {
       try {
-        const entries = await readdir(dir, { withFileTypes: true });
+        const entries = (await readdir(dir, { withFileTypes: true })).filter((e) => !isMacOsReplicationJunkBasename(e.name));
         for (const entry of entries) {
           checkCorpusReadAbort(options);
           const fullPath = path.join(dir, entry.name);
@@ -7133,7 +7134,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       const summaries: MemorySummary[] = [];
 
       for (const file of files) {
-        if (!file.endsWith(".json")) continue;
+        if (isMacOsReplicationJunkBasename(file) || !file.endsWith(".json")) continue;
         const filePath = path.join(this.summariesDir, file);
         const raw = await this.readStorageSecureFile(filePath);
         summaries.push(JSON.parse(raw) as MemorySummary);