@remnic/core 9.42.0 → 9.44.0

package/src/access-http.ts

@@ -18,6 +18,7 @@ import {
   type EngramAccessWriteResponse,
 } from "./access-service.js";
 import { maybeHandleLifecycleFlush, type LifecycleFlushHttpDeps } from "./access-http-lifecycle-flush.js";
+import { nonEmptyQueryParam, optionalQueryString, positiveIntQueryParam } from "./access-http-query.js";
 import { CorrectionContractError } from "./correction/correction-contract.js";
 import { WearablesInputError } from "./wearables/errors.js"; import { respondMeetingsList, respondMeetingsGet, respondMeetingsBuild } from "./meetings/http-glue.js";
 import { EngramMcpServer, MCP_SUPPORTED_PROTOCOL_VERSIONS } from "./access-mcp.js";
@@ -1322,6 +1323,31 @@ export class EngramAccessHttpServer {
       return;
     }
 
+    if (
+      req.method === "POST" &&
+      (
+        pathname === "/engram/v1/offline-sync/convergence-complete" ||
+        pathname === "/remnic/v1/offline-sync/convergence-complete"
+      )
+    ) {
+      this.enforceTokenOp("offline_sync_apply_file_content");
+      const namespaceParams = parsed.searchParams.getAll("namespace").filter(Boolean);
+      const requestedNamespaces: Array<string | undefined> =
+        namespaceParams.length > 0 ? namespaceParams : [undefined];
+      const namespaces = requestedNamespaces
+        .map((namespace) => this.resolveNamespace(req, namespace))
+        .filter((namespace): namespace is string => namespace !== undefined);
+      this.ensureWriteRateLimitAvailable(req);
+      const result = await this.service.offlineSyncFinalizeConvergence({
+        ...(namespaces.length > 0 ? { namespaces } : {}),
+        principal: this.resolveRequestPrincipal(req),
+        sourceId: this.readRequiredDecodedHeader(req, "x-remnic-source-id"),
+      });
+      this.recordWriteRateLimitHit(req);
+      this.respondJson(res, 200, result);
+      return;
+    }
+
     if (
       req.method === "POST" &&
       (pathname === "/engram/v1/offline-sync/apply" || pathname === "/remnic/v1/offline-sync/apply")
@@ -3925,29 +3951,3 @@ export class EngramAccessHttpServer {
     return false;
   }
 }
-
-/** Optional string field from a JSON body: absent/null/"" → undefined. */
-function optionalQueryString(value: unknown, label: string): string | undefined {
-  if (value === undefined || value === null || value === "") return undefined;
-  if (typeof value !== "string") {
-    throw new EngramAccessInputError(
-      `${label} must be a string (got ${JSON.stringify(value)})`,
-    );
-  }
-  return value;
-}
-
-/** Optional non-empty query param: null/"" → undefined. */
-function nonEmptyQueryParam(value: string | null): string | undefined {
-  return value !== null && value.length > 0 ? value : undefined;
-}
-
-/** Optional positive-integer query param; rejects invalid values. */
-function positiveIntQueryParam(value: string | null, label: string): number | undefined {
-  if (value === null || value.length === 0) return undefined;
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed) || parsed <= 0 || !Number.isInteger(parsed)) {
-    throw new EngramAccessInputError(`${label} expects a positive integer`);
-  }
-  return parsed;
-}

package/src/access-service-offline-file-content.test.ts

@@ -52,3 +52,43 @@ test("offline apply-file-content reports invalid metadata as input errors", asyn
       /mtimeMs must be within JavaScript Date range/.test(error.message),
   );
 });
+
+test("offline convergence completion refreshes authorized namespaces as one batch and rejects other sources", async () => {
+  const refreshed: string[][] = [];
+  const orchestratorStub = {
+    config: {
+      memoryDir: "/tmp/remnic-access-service-convergence-test",
+      namespacesEnabled: false,
+      defaultNamespace: "global",
+      sharedNamespace: "shared",
+    },
+    refreshNamespacesAfterConvergence: async (namespaces: readonly string[]) => {
+      refreshed.push([...namespaces]);
+    },
+  };
+  const service = new EngramAccessService(
+    orchestratorStub as unknown as ConstructorParameters<typeof EngramAccessService>[0],
+  );
+  const convergenceService = service as unknown as {
+    offlineSyncFinalizeConvergence(options: {
+      namespaces?: string[];
+      principal?: string;
+      sourceId: string;
+    }): Promise<{ namespaces: string[]; refreshed: true }>;
+  };
+
+  await assert.rejects(
+    () => convergenceService.offlineSyncFinalizeConvergence({ sourceId: "laptop" }),
+    (error) =>
+      error instanceof EngramAccessInputError
+      && /sourceId must be remnic-converge/.test(error.message),
+  );
+  assert.deepEqual(refreshed, []);
+
+  const result = await convergenceService.offlineSyncFinalizeConvergence({
+    sourceId: "remnic-converge",
+  });
+
+  assert.deepEqual(result, { namespaces: ["global"], refreshed: true });
+  assert.deepEqual(refreshed, [["global"]]);
+});

package/src/access-service.ts

@@ -818,6 +818,12 @@ export interface EngramAccessOfflineSyncApplyRequest {
   returnCurrentFiles?: boolean;
 }
 
+export interface EngramAccessOfflineSyncFinalizeConvergenceRequest {
+  namespaces?: string[];
+  principal?: string;
+  sourceId: string;
+}
+
 export interface EngramAccessOfflineSyncSnapshotResponse extends OfflineSyncSnapshot {
   namespace: string;
 }
@@ -843,6 +849,11 @@ export interface EngramAccessOfflineSyncApplyResponse extends OfflineSyncApplyCh
   namespace: string;
 }
 
+export interface EngramAccessOfflineSyncFinalizeConvergenceResponse {
+  namespaces: string[];
+  refreshed: true;
+}
+
 export type EngramAccessActionConfidenceRequest = ActionConfidenceInput;
 export type EngramAccessActionConfidenceResponse = ActionConfidenceResult;
 
@@ -5621,6 +5632,29 @@ export class EngramAccessService {
     }
   }
 
+  async offlineSyncFinalizeConvergence(
+    options: EngramAccessOfflineSyncFinalizeConvergenceRequest,
+  ): Promise<EngramAccessOfflineSyncFinalizeConvergenceResponse> {
+    if (options.sourceId !== "remnic-converge") {
+      throw new EngramAccessInputError("sourceId must be remnic-converge");
+    }
+    const requestedNamespaces = options.namespaces?.length
+      ? options.namespaces
+      : [undefined];
+    const resolvedNamespaces = Array.from(new Set(
+      requestedNamespaces.map((namespace) => this.writableNamespaceFor(
+        namespace,
+        undefined,
+        options.principal,
+      )),
+    ));
+    await this.orchestrator.refreshNamespacesAfterConvergence(resolvedNamespaces);
+    return {
+      namespaces: resolvedNamespaces,
+      refreshed: true,
+    };
+  }
+
   async offlineSyncApply(
     options: EngramAccessOfflineSyncApplyRequest,
   ): Promise<EngramAccessOfflineSyncApplyResponse> {

package/src/access-surface-catalog.ts

@@ -183,6 +183,11 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   { method: "POST", pathname: "/engram/v1/offline-sync/files", operation: "offline_sync_files" },
   { method: "POST", pathname: "/engram/v1/offline-sync/file-content", operation: "offline_sync_file_content" },
   { method: "POST", pathname: "/engram/v1/offline-sync/apply-file-content", operation: "offline_sync_apply_file_content" },
+  {
+    method: "POST",
+    pathname: "/engram/v1/offline-sync/convergence-complete",
+    operation: "offline_sync_apply_file_content",
+  },
   { method: "POST", pathname: "/engram/v1/offline-sync/apply", operation: "offline_sync_apply" },
   { method: "POST", pathname: "/engram/v1/recall/explain", operation: "recall_explain" },
   { method: "POST", pathname: "/engram/v1/action-confidence", operation: "action_confidence" },

package/src/convergence-refresh.ts

@@ -0,0 +1,28 @@
+import {
+  type RebuildMemoryProjectionOptions,
+  rebuildMemoryProjection,
+} from "./maintenance/rebuild-memory-projection.js";
+import type { NamespaceSearchRouter } from "./namespaces/search.js";
+
+type ConvergenceStorage = NonNullable<RebuildMemoryProjectionOptions["storage"]>;
+
+export async function refreshConvergedNamespaces(
+  namespaces: readonly string[],
+  namespaceSearchRouter: Pick<NamespaceSearchRouter, "updateNamespacesDetailed">,
+  getStorage: (namespace: string) => Promise<ConvergenceStorage>
+): Promise<void> {
+  const targetNamespaces = Array.from(new Set(namespaces.map((namespace) => namespace.trim()).filter(Boolean)));
+  if (targetNamespaces.length === 0) return;
+
+  await namespaceSearchRouter.updateNamespacesDetailed(targetNamespaces, undefined, { strict: true });
+
+  for (const namespace of targetNamespaces) {
+    const storage = await getStorage(namespace);
+    await rebuildMemoryProjection({
+      memoryDir: storage.dir,
+      storage,
+      defaultNamespace: namespace,
+      dryRun: false,
+    });
+  }
+}

package/src/orchestrator-convergence-refresh.test.ts

@@ -0,0 +1,114 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { readProjectedMemoryBrowse } from "./memory-projection-store.js";
+import { Orchestrator } from "./orchestrator.js";
+import { StorageManager } from "./storage.js";
+
+test("refreshNamespacesAfterConvergence runs one strict QMD batch and rebuilds each namespace projection once", async () => {
+  const teamDir = await mkdtemp(path.join(os.tmpdir(), "remnic-convergence-team-"));
+  const sharedDir = await mkdtemp(path.join(os.tmpdir(), "remnic-convergence-shared-"));
+  try {
+    const teamStorage = new StorageManager(teamDir);
+    const sharedStorage = new StorageManager(sharedDir);
+    const teamMemory = await teamStorage.writeMemory("fact", "A received team fact.", {
+      source: "test",
+    });
+    const sharedMemory = await sharedStorage.writeMemory("fact", "A received shared fact.", {
+      source: "test",
+    });
+    const qmdCalls: Array<{
+      namespaces: string[];
+      options: { strict?: boolean } | undefined;
+    }> = [];
+    const storageCalls: string[] = [];
+    const orchestrator = Object.create(Orchestrator.prototype) as Orchestrator;
+    const internals = orchestrator as unknown as {
+      config: { defaultNamespace: string };
+      namespaceSearchRouter: {
+        updateNamespacesDetailed(
+          namespaces: string[],
+          execution?: unknown,
+          options?: { strict?: boolean }
+        ): Promise<{ backendCount: number; eligibleNamespaces: string[] }>;
+      };
+      getStorage(namespace: string): Promise<StorageManager>;
+    };
+    internals.config = { defaultNamespace: "default" };
+    internals.namespaceSearchRouter = {
+      async updateNamespacesDetailed(namespaces, _execution, options) {
+        qmdCalls.push({ namespaces, options });
+        return { backendCount: 1, eligibleNamespaces: namespaces };
+      },
+    };
+    const storageByNamespace = new Map([
+      ["team", teamStorage],
+      ["shared", sharedStorage],
+    ]);
+    internals.getStorage = async (namespace) => {
+      storageCalls.push(namespace);
+      const storage = storageByNamespace.get(namespace);
+      assert.ok(storage);
+      return storage;
+    };
+    const refreshSurface = orchestrator as unknown as {
+      refreshNamespacesAfterConvergence(namespaces: readonly string[]): Promise<void>;
+    };
+
+    await refreshSurface.refreshNamespacesAfterConvergence(["team", "shared", "team"]);
+
+    assert.deepEqual(qmdCalls, [
+      {
+        namespaces: ["team", "shared"],
+        options: { strict: true },
+      },
+    ]);
+    assert.deepEqual(storageCalls, ["team", "shared"]);
+    const teamProjection = readProjectedMemoryBrowse(teamDir, { limit: 10, offset: 0 });
+    const sharedProjection = readProjectedMemoryBrowse(sharedDir, { limit: 10, offset: 0 });
+    assert.equal(teamProjection?.memories[0]?.id, teamMemory.id);
+    assert.equal(sharedProjection?.memories[0]?.id, sharedMemory.id);
+  } finally {
+    await Promise.all([rm(teamDir, { recursive: true, force: true }), rm(sharedDir, { recursive: true, force: true })]);
+  }
+});
+
+test("refreshNamespacesAfterConvergence rebuilds projection when search is disabled", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-convergence-no-search-"));
+  try {
+    const storage = new StorageManager(memoryDir);
+    const memory = await storage.writeMemory("fact", "A received fact without search enabled.", {
+      source: "test",
+    });
+    const orchestrator = Object.create(Orchestrator.prototype) as Orchestrator;
+    const internals = orchestrator as unknown as {
+      namespaceSearchRouter: {
+        updateNamespacesDetailed(
+          namespaces: string[],
+          execution?: unknown,
+          options?: { strict?: boolean }
+        ): Promise<{ backendCount: number; eligibleNamespaces: string[] }>;
+      };
+      getStorage(namespace: string): Promise<StorageManager>;
+    };
+    internals.namespaceSearchRouter = {
+      async updateNamespacesDetailed() {
+        return { backendCount: 0, eligibleNamespaces: [] };
+      },
+    };
+    internals.getStorage = async () => storage;
+    const refreshSurface = orchestrator as unknown as {
+      refreshNamespacesAfterConvergence(namespaces: readonly string[]): Promise<void>;
+    };
+
+    await refreshSurface.refreshNamespacesAfterConvergence(["default"]);
+
+    const projection = readProjectedMemoryBrowse(memoryDir, { limit: 10, offset: 0 });
+    assert.equal(projection?.memories[0]?.id, memory.id);
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/orchestrator.ts

@@ -218,6 +218,7 @@ import {
   runPatternReinforcement,
   type PatternReinforcementResult,
 } from "./maintenance/pattern-reinforcement.js";
+import { refreshConvergedNamespaces } from "./convergence-refresh.js";
 import { ModelRegistry } from "./model-registry.js";
 import { applyRuntimeRetrievalPolicy, expandQuery } from "./retrieval.js";
 import {
@@ -1278,11 +1279,11 @@ export class Orchestrator {
     return await this.namespaceSearchRouter.healthForNamespace(namespace, execution);
   }
 
-  private isSearchAvailableForNamespaceRouting(): boolean {
-    if (resolveNamespaceCapabilities(this.config).namespaces) return true;
-    return this.qmd.isAvailable();
+  async refreshNamespacesAfterConvergence(namespaces: readonly string[]): Promise<void> {
+    return refreshConvergedNamespaces(namespaces, this.namespaceSearchRouter, this.getStorage.bind(this));
   }
 
+
   invalidateLiveContentHashIndex(): void {
     this.contentHashIndex = null;
     this.contentHashIndexesByStorageDir.clear();
@@ -1530,7 +1531,7 @@ export class Orchestrator {
     });
     this.contradictionLinkingCoordinator = new ContradictionLinkingCoordinator({
       getConfig: () => this.config,
-      isSearchAvailable: () => this.isSearchAvailableForNamespaceRouting(),
+      isSearchAvailable: () => resolveNamespaceCapabilities(this.config).namespaces || this.qmd.isAvailable(),
       searchAcrossNamespaces: (options) => this.searchAcrossNamespaces(options),
       extractMemoryIdsFromResults: (results) => this.extractMemoryIdsFromResults(results),
       namespaceFromPath: (p) => this.namespaceFromPath(p),

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;
+  }
+}