@remnic/core 10.0.13 → 10.0.15

package/src/cli.ts

@@ -13,6 +13,7 @@ import { ThreadingManager } from "./threading.js";
 import { bumpMemoryCorpusVersionForDir } from "./memory-corpus-version.js";
 import { utcDayRange } from "./transcript.js";
 import { padEndDisplay, truncateGraphemeSafe } from "./whitespace.js";
+import { isMacOsReplicationJunkBasename } from "./utils/macos-replication-junk.js";
 import { runWearablesCliCommand } from "./wearables/cli.js";
 import { registerMeetingsCommands } from "./cli/meetings-commands.js"; import { registerDeepRecallCommands } from "./cli/deep-recall-commands.js"; import { registerRecallNavigationCommands } from "./cli/recall-navigation-commands.js"; import { registerMemoryBrowseCommands } from "./cli/memory-browse-commands.js";
 import { registerExportOkfCommand, registerOkfCommands } from "./cli/okf-commands.js";
@@ -3334,7 +3335,6 @@ export async function resolveMemoryDirForNamespace(
   }
   return candidate;
 }
-
 /**
  * Walk every recall category directory under `memoryDir` recursively and invoke
  * `visit` for every `*.md` file. The directory set is `RECALL_FALLBACK_DIRS`
@@ -3392,6 +3392,7 @@ async function walkMemoryMarkdownFiles(
     for (const entry of entries) {
       if (entry.isSymbolicLink()) continue; // never follow symlinked entries
       const entryName = typeof entry.name === "string" ? entry.name : entry.name.toString("utf-8");
+      if (isMacOsReplicationJunkBasename(entryName)) continue;
       const fullPath = path.join(dir, entryName);
       try {
         assertPathInsideRoot(memoryRootReal, await realpath(fullPath), fullPath);
@@ -3412,7 +3413,6 @@ async function walkMemoryMarkdownFiles(
     await walk(root);
   }
 }
-
 /**
  * List absolute paths of every `*.md` file under each recall category directory
  * of `memoryDir` (facts/, corrections/, decisions/, ...; see

package/src/console/trace.ts

@@ -32,6 +32,7 @@ import path from "node:path";
 import readline from "node:readline";
 import { createReadStream } from "node:fs";
 import type { Writable } from "node:stream";
+import { sleepAbortable } from "../utils/sleep.js";
 
 import { renderFrame } from "./tui.js";
 import type { ConsoleStateSnapshot } from "./state.js";
@@ -465,43 +466,11 @@ function normalizeSpeed(speed: number | undefined): number {
 }
 
 /**
- * Abortable sleep used by `replayTrace` between frames.
- *
- * Codex P2 (PR #732): unlike a plain `setTimeout` wrapper, this
- * variant REJECTS with `AbortError` when `signal` fires (or is
- * already aborted on entry). That gives callers a way to
- * *distinguish* timer-expiry from signal-driven early exit, instead
- * of silently resolving on both. The replay loop catches the
- * `AbortError` and exits cleanly so Ctrl-C does not have to wait for
- * the current inter-frame `setTimeout` (capped at 60s) to elapse.
- *
- * Resolves only on timer expiry. Rejects with `AbortError` (DOMException-
- * shaped: `name === "AbortError"`) on abort. Exported so callers in
- * tests and adjacent modules can reuse the same primitive.
+ * Abortable sleep used by `replayTrace` between frames: resolves on timer
+ * expiry, rejects with `AbortError` on abort so Ctrl-C exits without waiting
+ * out the inter-frame delay. Shared implementation lives in utils/sleep.js.
  */
-export function sleepAbortable(
-  ms: number,
-  signal?: AbortSignal,
-): Promise<void> {
-  return new Promise((resolve, reject) => {
-    if (signal?.aborted) {
-      reject(makeAbortError());
-      return;
-    }
-    const timer = setTimeout(() => {
-      if (signal && onAbort) signal.removeEventListener("abort", onAbort);
-      resolve();
-    }, ms);
-    let onAbort: (() => void) | null = null;
-    if (signal) {
-      onAbort = () => {
-        clearTimeout(timer);
-        reject(makeAbortError());
-      };
-      signal.addEventListener("abort", onAbort, { once: true });
-    }
-  });
-}
+export { sleepAbortable };
 
 /**
  * Construct an `AbortError`-shaped error. Prefers the standard

package/src/consolidation-provenance-check.ts

@@ -30,6 +30,7 @@ import {
 // lock-step with the doctor scan.
 import { sidecarKey } from "./page-versioning.js";
 import { RECALL_FALLBACK_DIRS } from "./utils/category-dir.js";
+import { isMacOsReplicationJunkBasename } from "./utils/macos-replication-junk.js";
 
 /**
  * Regex to spot a `derived_via: <value>` line in the raw YAML frontmatter
@@ -549,6 +550,7 @@ async function* walkMarkdownFiles(root: string, memoryDir: string): AsyncGenerat
     return;
   }
   for (const entry of entries) {
+    if (isMacOsReplicationJunkBasename(entry.name)) continue;
     const full = path.join(root, entry.name);
     if (entry.isSymbolicLink()) continue;
     if (entry.isDirectory()) {

package/src/converge-config.ts

@@ -1,3 +1,9 @@
+import {
+  type CaptureWriteLockBackoffLimits,
+  normalizeCaptureWriteLockWaitMs,
+  resolveCaptureWriteLockBackoffLimits,
+} from "./capture-write-lock-backoff.js";
+import { readEnvVar } from "./runtime/env.js";
 import type { ConvergeConfig, ConvergeConflictPolicy } from "./types.js";
 
 export const CONVERGE_CONFLICT_POLICIES = [
@@ -38,6 +44,46 @@ function parsePeerRequestTimeoutMs(value: unknown, label: string): number {
   return normalizeConvergePeerRequestTimeoutMs(value, label);
 }
 
+function parseOptionalCaptureLockMs(value: unknown, label: string): number | undefined {
+  if (value === undefined) return undefined;
+  return normalizeCaptureWriteLockWaitMs(value, label);
+}
+
+/**
+ * Config values win over env. An omitted knob stays omitted here so the
+ * caller can still fall through to the built-in default. Env is read with
+ * the REMNIC_ name and the legacy ENGRAM_ name.
+ */
+function envCaptureLockMs(name: string): number | undefined {
+  const raw = readEnvVar(name);
+  if (raw === undefined) return undefined;
+  const trimmed = raw.trim();
+  if (trimmed.length === 0) return undefined;
+  if (trimmed.length > 15) {
+    throw new Error(`${name} must be a positive integer number of milliseconds; got ${JSON.stringify(raw)}`);
+  }
+  for (let index = 0; index < trimmed.length; index += 1) {
+    const code = trimmed.charCodeAt(index);
+    if (code < 48 || code > 57) {
+      throw new Error(`${name} must be a positive integer number of milliseconds; got ${JSON.stringify(raw)}`);
+    }
+  }
+  return normalizeCaptureWriteLockWaitMs(Number(trimmed), name);
+}
+
+export function resolveConvergeCaptureWriteLockBackoff(
+  config: ConvergeConfig | undefined
+): CaptureWriteLockBackoffLimits {
+  return resolveCaptureWriteLockBackoffLimits({
+    captureWriteLockInitialDelayMs:
+      config?.captureWriteLockInitialDelayMs ?? envCaptureLockMs("REMNIC_CONVERGE_CAPTURE_LOCK_INITIAL_DELAY_MS"),
+    captureWriteLockMaxDelayMs:
+      config?.captureWriteLockMaxDelayMs ?? envCaptureLockMs("REMNIC_CONVERGE_CAPTURE_LOCK_MAX_DELAY_MS"),
+    captureWriteLockDeadlineMs:
+      config?.captureWriteLockDeadlineMs ?? envCaptureLockMs("REMNIC_CONVERGE_CAPTURE_LOCK_DEADLINE_MS"),
+  });
+}
+
 export function parseConvergeConfig(block: unknown): ConvergeConfig {
   if (block === undefined) {
     return { conflictPolicy: DEFAULT_CONVERGE_CONFLICT_POLICY };
@@ -49,7 +95,14 @@ export function parseConvergeConfig(block: unknown): ConvergeConfig {
   if (prototype !== Object.prototype && prototype !== null) {
     throw new Error("converge must be a plain object");
   }
-  const { conflictPolicy: rawConflictPolicy, peerRequestTimeoutMs, ...unknown } = block as Record<string, unknown>;
+  const {
+    conflictPolicy: rawConflictPolicy,
+    peerRequestTimeoutMs,
+    captureWriteLockInitialDelayMs,
+    captureWriteLockMaxDelayMs,
+    captureWriteLockDeadlineMs,
+    ...unknown
+  } = block as Record<string, unknown>;
   let conflictPolicy: unknown = rawConflictPolicy;
   const unknownKey = Object.keys(unknown)[0];
   if (unknownKey !== undefined) {
@@ -62,11 +115,37 @@ export function parseConvergeConfig(block: unknown): ConvergeConfig {
     typeof conflictPolicy === "string" &&
     CONVERGE_CONFLICT_POLICIES.includes(conflictPolicy as ConvergeConflictPolicy)
   ) {
+    const initialDelayMs = parseOptionalCaptureLockMs(
+      captureWriteLockInitialDelayMs,
+      "converge.captureWriteLockInitialDelayMs"
+    );
+    const maxDelayMs = parseOptionalCaptureLockMs(captureWriteLockMaxDelayMs, "converge.captureWriteLockMaxDelayMs");
+    const deadlineMs = parseOptionalCaptureLockMs(captureWriteLockDeadlineMs, "converge.captureWriteLockDeadlineMs");
+    // Reject an inverted schedule at parse time. Omitted knobs stay omitted
+    // and are filled from defaults only when the acquire runs.
+    if (initialDelayMs !== undefined && maxDelayMs !== undefined && initialDelayMs > maxDelayMs) {
+      throw new Error(
+        `converge.captureWriteLockInitialDelayMs (${initialDelayMs}) must be <= converge.captureWriteLockMaxDelayMs (${maxDelayMs})`
+      );
+    }
+    if (maxDelayMs !== undefined && deadlineMs !== undefined && maxDelayMs > deadlineMs) {
+      throw new Error(
+        `converge.captureWriteLockMaxDelayMs (${maxDelayMs}) must be <= converge.captureWriteLockDeadlineMs (${deadlineMs})`
+      );
+    }
+    if (initialDelayMs !== undefined && deadlineMs !== undefined && initialDelayMs > deadlineMs) {
+      throw new Error(
+        `converge.captureWriteLockInitialDelayMs (${initialDelayMs}) must be <= converge.captureWriteLockDeadlineMs (${deadlineMs})`
+      );
+    }
     return {
       conflictPolicy: conflictPolicy as ConvergeConflictPolicy,
       ...(peerRequestTimeoutMs !== undefined
         ? { peerRequestTimeoutMs: parsePeerRequestTimeoutMs(peerRequestTimeoutMs, "converge.peerRequestTimeoutMs") }
         : {}),
+      ...(initialDelayMs !== undefined ? { captureWriteLockInitialDelayMs: initialDelayMs } : {}),
+      ...(maxDelayMs !== undefined ? { captureWriteLockMaxDelayMs: maxDelayMs } : {}),
+      ...(deadlineMs !== undefined ? { captureWriteLockDeadlineMs: deadlineMs } : {}),
     };
   }
 

package/src/correction/correction-planner.ts

@@ -26,6 +26,7 @@ import { readFile, readdir, unlink } from "node:fs/promises";
 import path from "node:path";
 import { throwIfAborted } from "../abort-error.js";
 import { writeFileAtomically } from "../maintenance/atomic-file.js";
+import { isMacOsReplicationJunkBasename } from "../utils/macos-replication-junk.js";
 import { serializeMutations } from "../utils/serialize-mutations.js";
 import {
   CORRECTION_TEXT_MAX,
@@ -576,7 +577,7 @@ export class CorrectionPlanner {
     }
     const plans: CorrectionPlan[] = [];
     for (const f of files) {
-      if (!f.endsWith(".json")) continue;
+      if (isMacOsReplicationJunkBasename(f) || !f.endsWith(".json")) continue;
       let plan: CorrectionPlan | null = null;
       try {
         plan = await this.loadPlan(namespace, f.replace(/\.json$/, ""));
@@ -702,7 +703,7 @@ export class CorrectionPlanner {
     }
     const recovered: string[] = [];
     for (const f of files) {
-      if (!f.endsWith(".json")) continue;
+      if (isMacOsReplicationJunkBasename(f) || !f.endsWith(".json")) continue;
       const planId = f.replace(/\.json$/, "");
       let plan: CorrectionPlan | null;
       try {