@remnic/core 10.0.13 → 10.0.15

package/src/storage/tombstone-blocked-capture-mutation.ts

@@ -2,17 +2,30 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { createHash } from "node:crypto";
 import { mkdir } from "node:fs/promises";
 import path from "node:path";
-import { withHeldFileLock } from "../utils/serialize-mutations.js";
+import { raceAbort, throwIfAborted } from "../abort-error.js";
+import {
+  CAPTURE_WRITE_LOCK_BUSY_MESSAGE,
+  type CaptureWriteLockLimitSource,
+  captureWriteLockDelayMs,
+  resolveCaptureWriteLockBackoffLimits,
+} from "../capture-write-lock-backoff.js";
+import { log } from "../logger.js";
 import type { MemoryFile, MemoryFrontmatter } from "../types.js";
+import { withHeldFileLock } from "../utils/serialize-mutations.js";
+import { sleepAbortable } from "../utils/sleep.js";
 import type { CasRevisionTransaction } from "./cas-revision-store.js";
-const TOMBSTONE_CAPTURE_WRITE_LOCK_STALE_MS = 60_000;
-const CAPTURE_WRITE_LOCK_MAX_ATTEMPTS = 3;
-const CAPTURE_WRITE_LOCK_RETRY_BASE_MS = 25;
-const CAPTURE_WRITE_LOCK_BUSY_MESSAGE = "tombstone-blocked capture write lock remained busy";
 
-export function isTombstoneBlockedCaptureWriteLockBusy(error: unknown): boolean {
-  return error instanceof Error && error.message === CAPTURE_WRITE_LOCK_BUSY_MESSAGE;
-}
+export { isTombstoneBlockedCaptureWriteLockBusy } from "../capture-write-lock-backoff.js";
+
+const TOMBSTONE_CAPTURE_WRITE_LOCK_STALE_MS = 60_000;
+/**
+ * One exclusive-create probe. The bounded wait lives in the outer backoff,
+ * which runs only after every lock from this attempt has been released.
+ * A multi-second poll here would hold an already-acquired sibling lock.
+ */
+const CAPTURE_WRITE_LOCK_PROBE_MS = 1;
+const CAPTURE_WRITE_LOCK_RETRY = Symbol("capture-write-lock-retry");
+const CAPTURE_WRITE_LOCK_PERMANENT = Symbol("capture-write-lock-permanent-failure");
 
 export function normalizeExplicitCaptureContent(value: string): string {
   return value.toLowerCase().replace(/\s+/g, " ").trim();
@@ -46,6 +59,15 @@ export function captureIdentityHash(memory: MemoryFile): string {
 export type TombstoneBlockedCaptureWriteLockOptions = {
   readonly stateDir: string;
   readonly withHeldFileLock?: typeof withHeldFileLock;
+  /** Read when an acquire starts, after the caller has installed converge config. */
+  readonly lockOptions?: () => CaptureWriteLockLimitSource | undefined;
+  readonly now?: () => number;
+  readonly random?: () => number;
+  readonly sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+  readonly logDebug?: (message: string) => void;
+  readonly logWarn?: (message: string) => void;
+  /** Direct seam. Converge passes the same signal through `lockOptions` instead. */
+  readonly signal?: AbortSignal;
 };
 
 export class TombstoneBlockedCaptureWriteLock {
@@ -59,45 +81,107 @@ export class TombstoneBlockedCaptureWriteLock {
     return path.join(this.options.stateDir, "tombstone-blocked-capture", filename);
   }
 
-  private async withSingleCaptureWriteLock<T>(lockPath: string, task: () => Promise<T>): Promise<T> {
+  private now(): number {
+    return this.options.now?.() ?? Date.now();
+  }
+
+  private debug(message: string): void {
+    if (this.options.logDebug) {
+      this.options.logDebug(message);
+      return;
+    }
+    log.debug(message);
+  }
+
+  private warn(message: string): void {
+    if (this.options.logWarn) {
+      this.options.logWarn(message);
+      return;
+    }
+    log.warn(message);
+  }
+
+  /** Prefer the constructor seam; converge installs the signal on lock options at acquire time. */
+  private captureAbortSignal(): AbortSignal | undefined {
+    return this.options.signal ?? this.options.lockOptions?.()?.captureWriteLockSignal;
+  }
+
+  /**
+   * One probe of a single lock file. Returns the retry symbol when the lock
+   * is busy and the permanent symbol on a filesystem error. Does not sleep:
+   * the caller backs off only after the whole chain has unwound.
+   */
+  private async withSingleCaptureWriteLockOnce<T>(
+    lockPath: string,
+    task: () => Promise<T | typeof CAPTURE_WRITE_LOCK_RETRY>
+  ): Promise<T | typeof CAPTURE_WRITE_LOCK_RETRY | typeof CAPTURE_WRITE_LOCK_PERMANENT> {
     await mkdir(path.dirname(lockPath), { recursive: true });
-    const retry = Symbol("retry");
-    const permanentFailure = Symbol("permanent-failure");
     const runWithHeldFileLock = this.options.withHeldFileLock ?? withHeldFileLock;
-    for (let attempt = 0; attempt < CAPTURE_WRITE_LOCK_MAX_ATTEMPTS; attempt += 1) {
-      const result = await runWithHeldFileLock<T | typeof retry | typeof permanentFailure>(
-        lockPath,
-        {
-          staleMs: TOMBSTONE_CAPTURE_WRITE_LOCK_STALE_MS,
-          maxWaitMs: 1_000,
-          pollMs: 25,
-        },
-        async (acquired, controller) => {
-          if (acquired) return await task();
-          return controller.failure === "error" ? permanentFailure : retry;
-        }
-      );
-      if (result === permanentFailure) {
-        throw new Error("tombstone-blocked capture write lock acquisition failed");
+    return await runWithHeldFileLock(
+      lockPath,
+      {
+        staleMs: TOMBSTONE_CAPTURE_WRITE_LOCK_STALE_MS,
+        maxWaitMs: CAPTURE_WRITE_LOCK_PROBE_MS,
+        pollMs: CAPTURE_WRITE_LOCK_PROBE_MS,
+      },
+      async (acquired, controller) => {
+        if (acquired) return await task();
+        return controller.failure === "error" ? CAPTURE_WRITE_LOCK_PERMANENT : CAPTURE_WRITE_LOCK_RETRY;
       }
-      if (result !== retry) return result;
-      if (attempt === CAPTURE_WRITE_LOCK_MAX_ATTEMPTS - 1) break;
-      const delayState = Promise.withResolvers<void>();
-      setTimeout(delayState.resolve, CAPTURE_WRITE_LOCK_RETRY_BASE_MS * 2 ** attempt);
-      await delayState.promise;
-    }
-    throw new Error(CAPTURE_WRITE_LOCK_BUSY_MESSAGE);
+    );
   }
+
   private async withPhysicalCaptureWriteLocks<T>(
     task: () => Promise<T>,
     identityHashes: readonly string[]
   ): Promise<T> {
+    const signal = this.captureAbortSignal();
     const lockPaths = [...new Set(identityHashes.map((hash) => this.captureWriteLockPathForHash(hash)))];
-    const acquire = async (index: number): Promise<T> => {
-      if (index === lockPaths.length) return await task();
-      return await this.withSingleCaptureWriteLock(lockPaths[index], () => acquire(index + 1));
+    const limits = resolveCaptureWriteLockBackoffLimits(this.options.lockOptions?.());
+    const deadline = this.now() + limits.deadlineMs;
+    const giveUp = (): never => {
+      throwIfAborted(signal);
+      this.warn(
+        `tombstone-blocked capture write lock remained busy after ${limits.deadlineMs}ms; failing this write so the rest of the cycle can continue`
+      );
+      throw new Error(CAPTURE_WRITE_LOCK_BUSY_MESSAGE);
     };
-    return await acquire(0);
+    const acquire = async (
+      index: number
+    ): Promise<T | typeof CAPTURE_WRITE_LOCK_RETRY | typeof CAPTURE_WRITE_LOCK_PERMANENT> => {
+      throwIfAborted(signal);
+      // The deadline gates each probe: a chain that started before the
+      // deadline must not keep probing locks (or run the write) after it.
+      const runTask = async (): Promise<T> => {
+        if (this.now() >= deadline) giveUp();
+        return await task();
+      };
+      if (index === lockPaths.length) return await runTask();
+      const lockPath = lockPaths[index];
+      if (lockPath === undefined) return await runTask();
+      if (this.now() >= deadline) giveUp();
+      return await this.withSingleCaptureWriteLockOnce(lockPath, () => acquire(index + 1));
+    };
+    for (let attempt = 0; ; attempt += 1) {
+      throwIfAborted(signal);
+      const outcome = await acquire(0);
+      if (outcome === CAPTURE_WRITE_LOCK_PERMANENT) {
+        throw new Error("tombstone-blocked capture write lock acquisition failed");
+      }
+      if (outcome !== CAPTURE_WRITE_LOCK_RETRY) return outcome;
+      throwIfAborted(signal);
+      const now = this.now();
+      if (now >= deadline) giveUp();
+      const delay = Math.min(
+        captureWriteLockDelayMs(attempt, limits, this.options.random ?? Math.random),
+        deadline - now
+      );
+      if (delay <= 0) giveUp();
+      this.debug(`tombstone-blocked capture write lock busy; backing off ${delay}ms before retry ${attempt + 1}`);
+      // raceAbort covers seam sleeps that ignore the signal; the default
+      // sleepAbortable also clears its timer so abort holds no Timeout.
+      await raceAbort((this.options.sleep ?? sleepAbortable)(delay, signal), signal);
+    }
   }
 
   async withCaptureWriteLock<T>(task: () => Promise<T>, identity?: string | readonly string[]): Promise<T> {
@@ -125,6 +209,7 @@ export class TombstoneBlockedCaptureWriteLock {
     identities: readonly string[],
     identityHashes: readonly string[]
   ): Promise<T> {
+    throwIfAborted(this.captureAbortSignal());
     const current = this.context.getStore();
     const hashToken = (key: string): string =>
       `\u0000${key.length === 0 ? "" : createHash("sha256").update(key).digest("hex")}`;
@@ -179,7 +264,10 @@ export class TombstoneBlockedCaptureWriteLock {
       next.add(hashToken(key));
     }
     for (const hash of hashes) next.add(`\u0000${hash}`);
-    const run = () => this.context.run(next, task);
+    const run = () => {
+      throwIfAborted(this.captureAbortSignal());
+      return this.context.run(next, task);
+    };
     if (physicalMissing.length === 0) return await run();
     return await this.withPhysicalCaptureWriteLocks(run, physicalMissing);
   }
@@ -197,7 +285,10 @@ export type TombstoneBlockedMutationHost = {
   writeStorageSecureFile: (pathname: string, fileContent: string) => Promise<void>;
   withCaptureWriteLock: (task: () => Promise<void>, identity: string | readonly string[]) => Promise<void>;
   logWarning: (message: string) => void;
-  beginDurableMemoryRevision?: (pathname: string, expectedContent?: string | Buffer | null) => Promise<CasRevisionTransaction | undefined>;
+  beginDurableMemoryRevision?: (
+    pathname: string,
+    expectedContent?: string | Buffer | null
+  ) => Promise<CasRevisionTransaction | undefined>;
 };
 
 export type TombstoneBlockedMutation = {
@@ -263,7 +354,7 @@ export async function runTombstoneBlockedMutation(
             await transaction.abort();
           } catch (abortError) {
             host.logWarning(
-              `storage.tombstoneBlocked failed to abort the reserved receipt (pending marker preserved): ${abortError}`,
+              `storage.tombstoneBlocked failed to abort the reserved receipt (pending marker preserved): ${abortError}`
             );
           }
         }
@@ -280,7 +371,7 @@ export async function runTombstoneBlockedMutation(
           await transaction.writeLanded();
         } catch (evidenceError) {
           host.logWarning(
-            `storage.tombstoneBlocked failed to record receipt crash evidence (pending marker preserved): ${evidenceError}`,
+            `storage.tombstoneBlocked failed to record receipt crash evidence (pending marker preserved): ${evidenceError}`
           );
         }
         try {
@@ -292,7 +383,7 @@ export async function runTombstoneBlockedMutation(
           // and promotion/rollback refuse until recovery reconciles. The
           // reservation must NOT be aborted: the write is on disk.
           host.logWarning(
-            `storage.tombstoneBlocked receipt publication failed after the memory write (pending marker preserved for recovery): ${err}`,
+            `storage.tombstoneBlocked receipt publication failed after the memory write (pending marker preserved for recovery): ${err}`
           );
           await discardRebuildMarker();
           throw err;
@@ -318,7 +409,6 @@ export async function runTombstoneBlockedMutation(
   }
 }
 
-
 export function tombstoneBlocked(frontmatter: MemoryFrontmatter): boolean {
   return frontmatter.status === "pending_review" && Boolean(frontmatter.blockedBy);
 }

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";
@@ -3219,6 +3220,7 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       secureStoreKeyProvider: () => this._secureStoreKey,
       secureStoreWriteKeyProvider: () => this.resolveWriteKey(),
       lockOptions: () => this.factHashIndexLockOptions,
+      captureLockLimitSource: () => this.captureLockLimitSource(),
       parseMemory: (filePath, content) =>
         parseTombstoneBlockedOfflineSyncMemory(
           filePath,
@@ -3232,6 +3234,18 @@ export class StorageManager extends TombstoneBlockedCaptureIndexHost {
       readAllColdMemories: () => this.readAllColdMemories(),
     };
   }
+
+  /**
+   * Lock-limit source for tombstone-blocked captures. Undefined until the
+   * converge path installs capture-lock limits, so an ordinary capture
+   * resolves to the legacy short bounds instead of the converge deadline.
+   */
+  private captureLockLimitSource(): ContentHashIndexLockOptions | undefined {
+    const options = this.factHashIndexLockOptions;
+    const keys = ["captureWriteLockInitialDelayMs", "captureWriteLockMaxDelayMs", "captureWriteLockDeadlineMs", "captureWriteLockSignal"] as const;
+    return keys.some((key) => options[key] !== undefined) ? options : undefined;
+  }
+
   private async getFactHashIndex(): Promise<ContentHashIndex> {
     if (this.factHashIndex) {
       return this.factHashIndex;
@@ -4869,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);
@@ -7120,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);

package/src/transcript.ts

@@ -6,6 +6,7 @@ import { analyzeSessionIntegrity, type SessionIntegrityReport } from "./session-
 import { isDailyFileDatedBefore, resolveSafeStoragePath } from "./storage-paths.js";
 import { sessionStoragePaths } from "./session-identity.js";
 import { estimateTokenCount } from "./token-estimate.js";
+import { isMacOsReplicationJunkBasename } from "./utils/macos-replication-junk.js";
 
 type DirectorySessionStatus = "missing" | "empty" | "matches" | "occupied";
 type DirectoryOwnershipCacheEntry = {
@@ -166,7 +167,7 @@ export class TranscriptManager {
         for (const idEnt of idEntries) {
           if (!idEnt.isDirectory()) continue;
           const chanDir = path.join(typeDir, idEnt.name);
-          const files = (await readdir(chanDir)).filter((f) => f.endsWith(".jsonl")).sort();
+          const files = (await readdir(chanDir)).filter((f) => f.endsWith(".jsonl") && !isMacOsReplicationJunkBasename(f)).sort();
           const last = files[files.length - 1];
           if (!last) continue;
           try {
@@ -261,7 +262,7 @@ export class TranscriptManager {
 
     let names: string[];
     try {
-      names = (await readdir(channelDir)).filter((file) => file.endsWith(".jsonl"));
+      names = (await readdir(channelDir)).filter((file) => file.endsWith(".jsonl") && !isMacOsReplicationJunkBasename(file));
     } catch {
       return "occupied";
     }
@@ -345,7 +346,7 @@ export class TranscriptManager {
   ): Promise<void> {
     try {
       const channelDir = await resolveSafeStoragePath(root, dir);
-      const names = (await readdir(channelDir)).filter((file) => file.endsWith(".jsonl"));
+      const names = (await readdir(channelDir)).filter((file) => file.endsWith(".jsonl") && !isMacOsReplicationJunkBasename(file));
       const fileSizes = await this.directoryJsonlFileSizes(root, dir, names);
       if (!fileSizes) return;
       this.directoryOwnershipCache.set(
@@ -380,7 +381,7 @@ export class TranscriptManager {
 
       let names: string[];
       try {
-        names = (await readdir(channelDir)).filter((file) => file.endsWith(".jsonl")).sort();
+        names = (await readdir(channelDir)).filter((file) => file.endsWith(".jsonl") && !isMacOsReplicationJunkBasename(file)).sort();
       } catch {
         continue;
       }
@@ -641,14 +642,14 @@ export class TranscriptManager {
                 try {
                   const channelFiles = await readdir(channelDir);
                   for (const file of channelFiles) {
-                    if (file.endsWith(".jsonl")) {
+                    if (file.endsWith(".jsonl") && !isMacOsReplicationJunkBasename(file)) {
                       files.push(path.join(entry.name, channelTypeEntry.name, file));
                     }
                   }
                 } catch {
                   // Skip unreadable directories
                 }
-              } else if (channelTypeEntry.isFile() && channelTypeEntry.name.endsWith(".jsonl")) {
+              } else if (channelTypeEntry.isFile() && channelTypeEntry.name.endsWith(".jsonl") && !isMacOsReplicationJunkBasename(channelTypeEntry.name)) {
                 // Legacy: channel type dir contains .jsonl files directly
                 files.push(path.join(entry.name, channelTypeEntry.name));
               }
@@ -656,7 +657,7 @@ export class TranscriptManager {
           } catch {
             // Skip unreadable directories
           }
-        } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+        } else if (entry.isFile() && entry.name.endsWith(".jsonl") && !isMacOsReplicationJunkBasename(entry.name)) {
           // Legacy flat file - still include for backward compatibility
           files.push(entry.name);
         }
@@ -865,7 +866,7 @@ export class TranscriptManager {
                 try {
                   const channelFiles = await readdir(channelDir);
                   for (const file of channelFiles) {
-                    if (!file.endsWith(".jsonl")) continue;
+                    if (isMacOsReplicationJunkBasename(file) || !file.endsWith(".jsonl")) continue;
 
                     const filePath = path.join(channelDir, file);
 
@@ -894,7 +895,7 @@ export class TranscriptManager {
                 } catch (err) {
                   log.debug(`failed to process channel directory ${entry.name}/${channelTypeEntry.name}:`, err);
                 }
-              } else if (channelTypeEntry.isFile() && channelTypeEntry.name.endsWith(".jsonl")) {
+              } else if (channelTypeEntry.isFile() && channelTypeEntry.name.endsWith(".jsonl") && !isMacOsReplicationJunkBasename(channelTypeEntry.name)) {
                 // Legacy: channel type dir contains .jsonl files directly
                 const filePath = path.join(channelTypeDir, channelTypeEntry.name);
                 const cleaned = await this.cleanupTranscriptFile(filePath, cutoff);
@@ -906,7 +907,7 @@ export class TranscriptManager {
           } catch (err) {
             log.debug(`failed to process channel type directory ${entry.name}:`, err);
           }
-        } else if (entry.isFile() && entry.name.endsWith(".jsonl")) {
+        } else if (entry.isFile() && entry.name.endsWith(".jsonl") && !isMacOsReplicationJunkBasename(entry.name)) {
           // Handle legacy flat files - delete if older than retentionDays
           if (this.isLegacyTranscriptFile(entry.name)) {
             const dateStr = entry.name.slice(0, 10);

package/src/types.ts

@@ -41,6 +41,15 @@ export interface ConvergeConfig {
   conflictPolicy: ConvergeConflictPolicy;
   /** Per-request peer HTTP timeout in ms (plan/apply/watch). Default 30000; clamped to <= 3600000. */
   peerRequestTimeoutMs?: number;
+  /**
+   * Tombstone-blocked capture write-lock backoff for converge apply/watch.
+   * Defaults: 50ms initial (jittered to 25–50), 2000ms cap per wait, 60000ms
+   * deadline. Positive integers, clamped to <= 3600000. An inverted schedule
+   * (initial > max, or max > deadline) is rejected.
+   */
+  captureWriteLockInitialDelayMs?: number;
+  captureWriteLockMaxDelayMs?: number;
+  captureWriteLockDeadlineMs?: number;
 }
 export type SignalLevel = "none" | "low" | "medium" | "high";
 export type MemoryCategory =

package/src/utils/macos-replication-junk.test.ts

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  isMacOsReplicationJunkBasename,
+  isMacOsReplicationJunkRelativePath,
+  warnIgnoredMacOsReplicationJunk,
+  withoutMacOsReplicationJunk,
+} from "./macos-replication-junk.js";
+
+test("macOS replication junk is AppleDouble sidecars and .DS_Store only", () => {
+  assert.equal(isMacOsReplicationJunkBasename("._project-notes.md"), true);
+  assert.equal(isMacOsReplicationJunkBasename("._"), true);
+  assert.equal(isMacOsReplicationJunkBasename(".DS_Store"), true);
+  assert.equal(isMacOsReplicationJunkBasename("project-notes.md"), false);
+  assert.equal(isMacOsReplicationJunkBasename(".gitignore"), false);
+  assert.equal(isMacOsReplicationJunkBasename("DS_Store"), false);
+  assert.equal(isMacOsReplicationJunkRelativePath("namespaces/lab/entities/._project-notes.md"), true);
+  assert.equal(isMacOsReplicationJunkRelativePath("namespaces\\lab\\.DS_Store"), true);
+  assert.equal(isMacOsReplicationJunkRelativePath("entities/project-notes.md"), false);
+});
+
+test("withoutMacOsReplicationJunk keeps real names and counts junk once", () => {
+  const { kept, ignored } = withoutMacOsReplicationJunk(
+    ["project-notes.md", "._project-notes.md", ".DS_Store", "correction-1.md"],
+    (name) => name
+  );
+  assert.deepEqual(kept, ["project-notes.md", "correction-1.md"]);
+  assert.equal(ignored, 2);
+});
+
+test("warnIgnoredMacOsReplicationJunk emits one summary per directory and count", () => {
+  const messages: string[] = [];
+  const warn = (message: string) => {
+    messages.push(message);
+  };
+  const directory = `junk-warn-${process.pid}-${Date.now()}`;
+  warnIgnoredMacOsReplicationJunk(directory, 2, warn);
+  warnIgnoredMacOsReplicationJunk(directory, 2, warn);
+  warnIgnoredMacOsReplicationJunk(directory, 0, warn);
+  warnIgnoredMacOsReplicationJunk(directory, 3, warn);
+  assert.deepEqual(messages, [
+    "ignored 2 macOS replication junk file(s) (._* and .DS_Store)",
+    "ignored 3 macOS replication junk file(s) (._* and .DS_Store)",
+  ]);
+});

package/src/utils/macos-replication-junk.ts

@@ -0,0 +1,65 @@
+/**
+ * macOS Finder metadata that arrives through Mac-to-Linux copies.
+ *
+ * AppleDouble sidecars are named `._` plus the real file's basename
+ * (`._project-notes.md` beside `project-notes.md`). Finder also writes
+ * `.DS_Store` into any directory it opens. Neither is a Remnic record.
+ * Directory scanners and replication must ignore them so they are never
+ * parsed as entities, memories, or sync objects.
+ *
+ * QMD's own indexer already drops every hidden path (`dot: false` plus a
+ * hidden-segment filter). Callers that build index inputs themselves still
+ * use this helper so the non-QMD scanners stay in parity.
+ */
+
+const warnedJunkDirectories = new Set<string>();
+
+/** True for an AppleDouble sidecar or a Finder `.DS_Store` file. */
+export function isMacOsReplicationJunkBasename(basename: string): boolean {
+  return basename === ".DS_Store" || basename.startsWith("._");
+}
+
+/** True when the final path segment is macOS replication junk. */
+export function isMacOsReplicationJunkRelativePath(relPath: string): boolean {
+  const normalized = relPath.includes("\\") ? relPath.replaceAll("\\", "/") : relPath;
+  const slash = normalized.lastIndexOf("/");
+  const basename = slash === -1 ? normalized : normalized.slice(slash + 1);
+  return isMacOsReplicationJunkBasename(basename);
+}
+
+/**
+ * Drop junk names from a directory listing. `ignored` is the count of
+ * names removed, so the caller can emit one summary warning.
+ */
+export function withoutMacOsReplicationJunk<T>(
+  entries: readonly T[],
+  basenameOf: (entry: T) => string
+): { kept: T[]; ignored: number } {
+  const kept: T[] = [];
+  let ignored = 0;
+  for (const entry of entries) {
+    if (isMacOsReplicationJunkBasename(basenameOf(entry))) {
+      ignored += 1;
+      continue;
+    }
+    kept.push(entry);
+  }
+  return { kept, ignored };
+}
+
+/**
+ * Emit at most one junk warning per directory and count. A later scan of
+ * the same directory (entity migration, then entity load) stays quiet
+ * instead of repeating the same summary.
+ */
+export function warnIgnoredMacOsReplicationJunk(
+  directoryKey: string,
+  count: number,
+  warn: (message: string) => void
+): void {
+  if (count <= 0) return;
+  const key = `${directoryKey}\0${count}`;
+  if (warnedJunkDirectories.has(key)) return;
+  warnedJunkDirectories.add(key);
+  warn(`ignored ${count} macOS replication junk file(s) (._* and .DS_Store)`);
+}

package/src/utils/malformed-entity-record.ts

@@ -0,0 +1,101 @@
+/**
+ * Heading and type flags for an entity markdown body.
+ *
+ * The heading rule matches `parseEntityFile`: a line must start with `# `
+ * (hash, space) and the remainder must contain a name. A tab after `#`
+ * is not a heading. The type rule matches a `**Type:**` line with a
+ * non-empty value. A missing type line is still readable: the parser
+ * defaults the type to `other`.
+ */
+function entityRecordFlags(content: string): { hasName: boolean; hasType: boolean } {
+  const body = entityRecordBody(content);
+  let hasName = false;
+  let hasType = false;
+  let start = 0;
+  while (start <= body.length) {
+    const newline = body.indexOf("\n", start);
+    const end = newline === -1 ? body.length : newline;
+    let line = body.slice(start, end);
+    if (line.endsWith("\r")) line = line.slice(0, -1);
+    if (!hasName && line.startsWith("# ") && line.slice(2).trim().length > 0) hasName = true;
+    if (!hasType && line.startsWith("**Type:**") && line.slice("**Type:**".length).trim().length > 0) {
+      hasType = true;
+    }
+    if (hasName && hasType) return { hasName, hasType };
+    if (newline === -1) break;
+    start = newline + 1;
+  }
+  return { hasName, hasType };
+}
+
+/**
+ * No `# ` name. A named file whose type line is absent stays readable:
+ * `parseEntityFile` defaults the type to `other`.
+ */
+export function isUnnamedEntityRecord(content: string): boolean {
+  return !entityRecordFlags(content).hasName;
+}
+
+function entityBodyHasText(content: string): boolean {
+  const body = entityRecordBody(content);
+  for (let i = 0; i < body.length; i++) {
+    const char = body.charCodeAt(i);
+    if (char !== 32 && char !== 9 && char !== 10 && char !== 13) return true;
+  }
+  return false;
+}
+
+/**
+ * Unnamed entity body that still has text. An empty body under frontmatter
+ * stays readable so a canonical filename can supply the type. A tab heading,
+ * a blank `# ` heading, or prose with no name does not.
+ */
+export function isPopulatedUnnamedEntityRecord(content: string): boolean {
+  return isUnnamedEntityRecord(content) && entityBodyHasText(content);
+}
+
+/**
+ * Unnamed file that still looks like an entity record (`#` or `**Type:**`).
+ * Direct filename recall keeps unstructured placeholders such as "content".
+ */
+export function isShapedUnnamedEntityRecord(content: string): boolean {
+  if (!isUnnamedEntityRecord(content)) return false;
+  const body = entityRecordBody(content);
+  let start = 0;
+  while (start <= body.length) {
+    const newline = body.indexOf("\n", start);
+    const end = newline === -1 ? body.length : newline;
+    let line = body.slice(start, end);
+    if (line.endsWith("\r")) line = line.slice(0, -1);
+    if (line.startsWith("#") || line.startsWith("**Type:**")) return true;
+    if (newline === -1) break;
+    start = newline + 1;
+  }
+  return false;
+}
+
+/**
+ * Migration gate. Canonical ids are derived from name and type, and the
+ * old startup throw required an explicit `**Type:**` line. Files that
+ * only have a heading stay on disk and are not renamed. Listing does not
+ * use this predicate: `parseEntityFile` defaults a missing type to `other`.
+ */
+export function isMalformedEntityRecord(content: string): boolean {
+  const flags = entityRecordFlags(content);
+  return !flags.hasName || !flags.hasType;
+}
+
+function entityRecordBody(content: string): string {
+  const firstNewline = content.indexOf("\n");
+  if (firstNewline === -1) return content;
+  const firstLine = content.slice(0, firstNewline).endsWith("\r")
+    ? content.slice(0, firstNewline - 1)
+    : content.slice(0, firstNewline);
+  if (firstLine !== "---") return content;
+  const close = content.indexOf("\n---", firstNewline + 1);
+  if (close === -1) return content;
+  let rest = close + "\n---".length;
+  if (content.charAt(rest) === "\r") rest += 1;
+  if (content.charAt(rest) === "\n") rest += 1;
+  return content.slice(rest);
+}

package/src/utils/sleep.ts

@@ -3,3 +3,31 @@ export function sleep(ms: number): Promise<void> {
   // Constructor form keeps this reachable utility compatible with ES2022 adapter type graphs.
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
+
+import { abortError } from "../abort-error.js";
+
+/**
+ * Wait until `ms` elapses, or reject with `AbortError` when `signal` fires.
+ * The timer is cleared on abort so a cancelled wait holds no Timeout handle.
+ * Executor form: this module targets ES2022 type graphs (no withResolvers).
+ */
+export function sleepAbortable(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(abortError("operation aborted"));
+      return;
+    }
+    const timer = setTimeout(() => {
+      if (signal && onAbort) signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    let onAbort: (() => void) | null = null;
+    if (signal) {
+      onAbort = () => {
+        clearTimeout(timer);
+        reject(abortError("operation aborted"));
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}