@remnic/core 9.42.0 → 9.43.0

package/dist/search/index.js

@@ -2,7 +2,10 @@ import {
   createConversationIndexRuntime,
   createConversationSearchBackend,
   createSearchBackend
-} from "../chunk-UZQCNOPS.js";
+} from "../chunk-EHKDORQN.js";
+import {
+  NoopSearchBackend
+} from "../chunk-CYEPCZN5.js";
 import {
   OramaBackend
 } from "../chunk-ES36HTSC.js";
@@ -22,9 +25,6 @@ import {
   scanMemoryDir
 } from "../chunk-W7IGLX4G.js";
 import "../chunk-CINZGPSJ.js";
-import {
-  NoopSearchBackend
-} from "../chunk-CYEPCZN5.js";
 import "../chunk-LEPOP46W.js";
 import "../chunk-72A4L5JJ.js";
 import "../chunk-A7Q43EUZ.js";

package/dist/transfer/import-sqlite.js

@@ -1,8 +1,8 @@
 import {
   importSqlite
-} from "../chunk-LRGSLV7M.js";
-import "../chunk-G4IAEX6D.js";
+} from "../chunk-PYHOAXTI.js";
 import "../chunk-Z734BLO3.js";
+import "../chunk-G4IAEX6D.js";
 import "../chunk-RL6NEVXT.js";
 import "../chunk-GCGJW34D.js";
 import "../chunk-PZ5AY32C.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remnic/core",
-  "version": "9.42.0",
+  "version": "9.43.0",
   "description": "Framework-agnostic Remnic memory engine — orchestrator, storage, extraction, search, trust zones",
   "type": "module",
   "main": "dist/index.js",
@@ -166,6 +166,16 @@
       "remnic-source": "./src/reconcile/plan.ts",
       "import": "./dist/reconcile/plan.js"
     },
+    "./reconcile/cursor": {
+      "types": "./dist/reconcile/cursor.d.ts",
+      "remnic-source": "./src/reconcile/cursor.ts",
+      "import": "./dist/reconcile/cursor.js"
+    },
+    "./reconcile/cursor.js": {
+      "types": "./dist/reconcile/cursor.d.ts",
+      "remnic-source": "./src/reconcile/cursor.ts",
+      "import": "./dist/reconcile/cursor.js"
+    },
     "./adapters/codex": {
       "types": "./dist/adapters/codex.d.ts",
       "remnic-source": "./src/adapters/codex.ts",
@@ -3086,7 +3096,7 @@
     "core"
   ],
   "peerDependencies": {
-    "@remnic/coding-graph": "^9.42.0"
+    "@remnic/coding-graph": "^9.43.0"
   },
   "peerDependenciesMeta": {
     "@remnic/coding-graph": {

package/src/reconcile/cursor.test.ts

@@ -0,0 +1,123 @@
+import * as assert from "node:assert/strict";
+import * as fs from "node:fs/promises";
+import * as os from "node:os";
+import * as path from "node:path";
+import { test } from "node:test";
+import {
+  defaultConvergeCursorPath,
+  hashPeerNamespace,
+  normalizeConvergeCursor,
+  readConvergeCursor,
+  writeConvergeCursor,
+  type ConvergeCursorState,
+} from "./cursor.js";
+
+const shaA = "a".repeat(64);
+
+test("hashPeerNamespace: deterministic key normalization", () => {
+  const k1 = hashPeerNamespace("http://peer.example.com/", "default");
+  const k2 = hashPeerNamespace("http://peer.example.com", "DEFAULT ");
+  assert.equal(k1, k2);
+  assert.equal(k1.length, 16);
+});
+
+test("hashPeerNamespace: accepts non-URL local peer identifiers", () => {
+  assert.equal(hashPeerNamespace("local", "default").length, 16);
+});
+
+test("hashPeerNamespace: preserves path case while normalizing URL authority and trailing slash", () => {
+  const uppercasePath = hashPeerNamespace("HTTP://PEER.EXAMPLE.COM/Memory/", "default");
+  const lowercasePath = hashPeerNamespace("http://peer.example.com/memory", "default");
+
+  assert.notEqual(uppercasePath, lowercasePath);
+  assert.equal(
+    uppercasePath,
+    hashPeerNamespace("http://peer.example.com/Memory", "DEFAULT "),
+  );
+  assert.equal(
+    lowercasePath,
+    hashPeerNamespace("HTTP://PEER.EXAMPLE.COM/memory/", "default"),
+  );
+});
+
+test("defaultConvergeCursorPath: constructs path under memoryDir state", () => {
+  const p = defaultConvergeCursorPath("/tmp/mem", "http://localhost:4318", "general");
+  assert.ok(p.includes(path.join(".remnic", "state", "converge-cursors")));
+  assert.ok(p.endsWith(".json"));
+});
+
+test("normalizeConvergeCursor: validates envelope shape", () => {
+  assert.throws(() => normalizeConvergeCursor(null), /must be an object/);
+  assert.throws(() => normalizeConvergeCursor({ version: 2 }), /version must be 1/);
+  assert.throws(
+    () => normalizeConvergeCursor({ version: 1, peerUrl: "" }),
+    /missing peerUrl/,
+  );
+  assert.throws(
+    () => normalizeConvergeCursor({ version: 1, peerUrl: "http://peer", namespace: "" }),
+    /missing namespace/,
+  );
+
+  const valid = normalizeConvergeCursor({
+    version: 1,
+    peerUrl: "http://peer",
+    namespace: "default",
+    baseFiles: [{ path: "a.md", sha256: shaA }],
+  });
+  assert.equal(valid.peerUrl, "http://peer");
+  assert.equal(valid.namespace, "default");
+  assert.equal(valid.baseFiles.length, 1);
+  assert.equal(valid.baseFiles[0]?.path, "a.md");
+});
+
+test("readConvergeCursor: returns null when file is missing or invalid", async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "remnic-cursor-test-"));
+  try {
+    const missing = await readConvergeCursor(path.join(tmpDir, "missing.json"));
+    assert.equal(missing, null);
+
+    const invalidPath = path.join(tmpDir, "invalid.json");
+    await fs.writeFile(invalidPath, "{ invalid json", "utf-8");
+    const invalid = await readConvergeCursor(invalidPath);
+    assert.equal(invalid, null);
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test("writeConvergeCursor & readConvergeCursor: atomic write roundtrip", async () => {
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "remnic-cursor-test-"));
+  const cursorPath = path.join(tmpDir, "state", "cursor.json");
+  try {
+    const cursor: ConvergeCursorState = {
+      version: 1,
+      peerUrl: "http://localhost:4318",
+      namespace: "default",
+      lastConvergedAt: new Date().toISOString(),
+      baseFiles: [{ path: "facts/a.md", sha256: shaA, bytes: 120, mtimeMs: 1000 }],
+      completedPaths: ["facts/a.md"],
+    };
+
+    await writeConvergeCursor(cursorPath, cursor);
+    const read = await readConvergeCursor(cursorPath);
+    assert.ok(read);
+    assert.equal(read.peerUrl, "http://localhost:4318");
+    assert.equal(read.namespace, "default");
+    assert.equal(read.baseFiles.length, 1);
+    assert.equal(read.baseFiles[0]?.sha256, shaA);
+    assert.deepEqual(read.completedPaths, ["facts/a.md"]);
+
+    // Update existing cursor atomically
+    const updated: ConvergeCursorState = {
+      ...read,
+      lastConvergedAt: new Date().toISOString(),
+      completedPaths: ["facts/a.md", "facts/b.md"],
+    };
+    await writeConvergeCursor(cursorPath, updated);
+    const readUpdated = await readConvergeCursor(cursorPath);
+    assert.ok(readUpdated);
+    assert.equal(readUpdated.completedPaths?.length, 2);
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});

package/src/reconcile/cursor.ts

@@ -0,0 +1,130 @@
+import { createHash, randomUUID } from "node:crypto";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+
+export interface ConvergeCursorFileState {
+  path: string;
+  sha256: string;
+  mtimeMs?: number;
+  bytes?: number;
+}
+
+export interface ConvergeCursorState {
+  version: 1;
+  peerUrl: string;
+  namespace: string;
+  lastConvergedAt?: string;
+  baseFiles: ConvergeCursorFileState[];
+  completedPaths?: string[];
+}
+
+export function hashPeerNamespace(peerUrl: string, namespace: string): string {
+  let normalizedUrl: string;
+  try {
+    const url = new URL(peerUrl);
+    const credentials =
+      url.username || url.password
+        ? `${url.username}${url.password ? `:${url.password}` : ""}@`
+        : "";
+    normalizedUrl =
+      `${url.protocol.toLowerCase()}//${credentials}${url.hostname.toLowerCase()}` +
+      `${url.port ? `:${url.port}` : ""}${url.pathname.replace(/\/+$/, "")}${url.search}${url.hash}`;
+  } catch {
+    normalizedUrl = peerUrl.trim().replace(/\/+$/, "").toLowerCase();
+  }
+  const normalizedNs = namespace.trim().toLowerCase();
+  return createHash("sha256")
+    .update(`${normalizedUrl}\0${normalizedNs}`)
+    .digest("hex")
+    .slice(0, 16);
+}
+
+export function defaultConvergeCursorPath(
+  memoryDir: string,
+  peerUrl: string,
+  namespace: string,
+): string {
+  const key = hashPeerNamespace(peerUrl, namespace);
+  return path.join(path.resolve(memoryDir), ".remnic", "state", "converge-cursors", `${key}.json`);
+}
+
+export function normalizeConvergeCursor(input: unknown): ConvergeCursorState {
+  if (!input || typeof input !== "object" || Array.isArray(input)) {
+    throw new Error("converge cursor must be an object");
+  }
+  const obj = input as Record<string, unknown>;
+  if (obj.version !== 1) {
+    throw new Error("converge cursor version must be 1");
+  }
+  if (typeof obj.peerUrl !== "string" || !obj.peerUrl.trim()) {
+    throw new Error("converge cursor missing peerUrl");
+  }
+  if (typeof obj.namespace !== "string" || !obj.namespace.trim()) {
+    throw new Error("converge cursor missing namespace");
+  }
+  const baseFiles: ConvergeCursorFileState[] = [];
+  if (Array.isArray(obj.baseFiles)) {
+    for (const item of obj.baseFiles) {
+      if (item && typeof item === "object") {
+        const fileItem = item as Record<string, unknown>;
+        if (typeof fileItem.path === "string" && typeof fileItem.sha256 === "string") {
+          baseFiles.push({
+            path: fileItem.path,
+            sha256: fileItem.sha256,
+            mtimeMs: typeof fileItem.mtimeMs === "number" ? fileItem.mtimeMs : undefined,
+            bytes: typeof fileItem.bytes === "number" ? fileItem.bytes : undefined,
+          });
+        }
+      }
+    }
+  }
+  const completedPaths: string[] = [];
+  if (Array.isArray(obj.completedPaths)) {
+    for (const item of obj.completedPaths) {
+      if (typeof item === "string") {
+        completedPaths.push(item);
+      }
+    }
+  }
+  return {
+    version: 1,
+    peerUrl: obj.peerUrl.trim(),
+    namespace: obj.namespace.trim(),
+    lastConvergedAt: typeof obj.lastConvergedAt === "string" ? obj.lastConvergedAt : undefined,
+    baseFiles,
+    completedPaths,
+  };
+}
+
+export async function readConvergeCursor(
+  cursorPath: string,
+): Promise<ConvergeCursorState | null> {
+  try {
+    const raw = await fs.readFile(path.resolve(cursorPath), "utf-8");
+    const parsed = JSON.parse(raw);
+    return normalizeConvergeCursor(parsed);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    return null;
+  }
+}
+
+export async function writeConvergeCursor(
+  cursorPath: string,
+  cursor: ConvergeCursorState,
+): Promise<void> {
+  const normalized = normalizeConvergeCursor(cursor);
+  const target = path.resolve(cursorPath);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const tmp = path.join(
+    path.dirname(target),
+    `.converge-cursor.${process.pid}.${randomUUID()}.tmp`,
+  );
+  await fs.writeFile(tmp, JSON.stringify(normalized, null, 2) + "\n", "utf-8");
+  try {
+    await fs.rename(tmp, target);
+  } catch (error) {
+    await fs.unlink(tmp).catch(() => {});
+    throw error;
+  }
+}