@remnic/core 9.43.0 → 9.45.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/manifest.test.ts

@@ -0,0 +1,261 @@
+import * as assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { test } from "node:test";
+import { ContentHashIndex } from "../storage/content-hash-index.js";
+import { type ReconcileManifest, buildReconcileManifest, collapseActiveFactDuplicates } from "./manifest.js";
+import { planReconciliation } from "./plan.js";
+
+const fileHash = (content: string): string => createHash("sha256").update(content).digest("hex");
+
+function memoryFile(options: {
+  id: string;
+  content: string;
+  contentHash?: string;
+  status?: string;
+}): string {
+  return [
+    "---",
+    `id: ${options.id}`,
+    "category: fact",
+    "created: 2026-01-01T00:00:00.000Z",
+    "updated: 2026-01-01T00:00:00.000Z",
+    ...(options.contentHash ? [`contentHash: ${options.contentHash}`] : []),
+    ...(options.status ? [`status: ${options.status}`] : []),
+    "---",
+    options.content,
+  ].join("\n");
+}
+
+test("reconcile manifest keeps file identity separate from canonical semantic identity", async () => {
+  const content = "The deployment uses a durable queue with an enrichment suffix.";
+  const semanticHash = ContentHashIndex.computeHash("The deployment uses a durable queue.");
+  const serialized = memoryFile({ id: "fact-a", content, contentHash: semanticHash, status: "active" });
+  const serializedHash = fileHash(serialized);
+
+  const manifest = await buildReconcileManifest({
+    files: [{ path: "facts/fact-a.md", sha256: serializedHash, bytes: Buffer.byteLength(serialized) }],
+    readFile: async () => Buffer.from(serialized),
+  });
+
+  assert.equal(manifest.format, "remnic-reconcile-manifest");
+  assert.equal(manifest.schemaVersion, 1);
+  assert.equal(manifest.files[0]?.sha256, serializedHash);
+  assert.notEqual(serializedHash, semanticHash);
+  assert.deepEqual(manifest.files[0]?.memory, {
+    id: "fact-a",
+    category: "fact",
+    contentHash: semanticHash,
+    status: "active",
+  });
+});
+
+test("reconcile manifest hashes parsed legacy content and uses effective lifecycle status", async () => {
+  const active = memoryFile({ id: "legacy", content: "Legacy fact body" });
+  const archived = memoryFile({ id: "archived", content: "Archived fact body", status: "active" });
+  const rawByPath = new Map([
+    ["facts/legacy.md", Buffer.from(active)],
+    ["archive/facts/archived.md", Buffer.from(archived)],
+  ]);
+
+  const manifest = await buildReconcileManifest({
+    files: [...rawByPath].map(([path, raw]) => ({ path, sha256: fileHash(raw.toString()) })),
+    readFile: async (file) => rawByPath.get(file.path) ?? null,
+  });
+
+  assert.equal(manifest.files[0]?.memory?.contentHash, ContentHashIndex.computeHash("Archived fact body"));
+  assert.equal(manifest.files[0]?.memory?.status, "archived");
+  assert.equal(manifest.files[1]?.memory?.contentHash, ContentHashIndex.computeHash("Legacy fact body"));
+  assert.equal(manifest.files[1]?.memory?.status, "active");
+});
+
+test("reconcile manifest keeps file identity when memory bytes cannot be trusted", async () => {
+  const readable = memoryFile({ id: "readable", content: "Readable fact" });
+  const changed = memoryFile({ id: "changed", content: "Changed after census" });
+  const files = [
+    { path: "facts/readable.md", sha256: fileHash(readable) },
+    { path: "facts/locked.md", sha256: "f".repeat(64) },
+    { path: "facts/changed.md", sha256: fileHash("bytes from census") },
+  ];
+
+  const manifest = await buildReconcileManifest({
+    files,
+    readFile: async (file) => {
+      if (file.path === "facts/locked.md") throw new Error("locked");
+      return file.path === "facts/changed.md" ? changed : readable;
+    },
+  });
+
+  assert.equal(manifest.files.length, 3);
+  assert.equal(manifest.files.find((file) => file.path === "facts/readable.md")?.memory?.id, "readable");
+  assert.equal(manifest.files.find((file) => file.path === "facts/locked.md")?.memory, undefined);
+  assert.equal(manifest.files.find((file) => file.path === "facts/changed.md")?.memory, undefined);
+});
+
+test("ContentHashIndex resolves a semantic hash to a stable canonical path without changing membership", () => {
+  const semanticHash = ContentHashIndex.computeHash("same fact");
+  const entries = [
+    { path: "facts/z.md", contentHash: semanticHash },
+    { path: "facts/a.md", contentHash: semanticHash },
+    { path: "facts/other.md", contentHash: ContentHashIndex.computeHash("other fact") },
+  ];
+  const index = new ContentHashIndex("unused");
+
+  assert.equal(ContentHashIndex.resolvePathByHash(semanticHash, entries), "facts/a.md");
+  assert.equal(ContentHashIndex.resolvePathByHash("f".repeat(64), entries), undefined);
+  assert.equal(index.has("same fact"), false);
+});
+
+test("semantic collapse prevents different active fact paths from transferring both directions", () => {
+  const semanticHash = ContentHashIndex.computeHash("same active fact");
+  const localFile = { path: "facts/local-id.md", sha256: "a".repeat(64) };
+  const peerFile = { path: "facts/peer-id.md", sha256: "b".repeat(64) };
+  const plan = planReconciliation([{ namespace: "default", local: [localFile], peer: [peerFile] }]);
+  const local: ReconcileManifest = {
+    format: "remnic-reconcile-manifest",
+    schemaVersion: 1,
+    files: [
+      { ...localFile, memory: { id: "local-id", category: "fact", contentHash: semanticHash, status: "active" } },
+    ],
+  };
+  const peer: ReconcileManifest = {
+    format: "remnic-reconcile-manifest",
+    schemaVersion: 1,
+    files: [{ ...peerFile, memory: { id: "peer-id", category: "fact", contentHash: semanticHash, status: "active" } }],
+  };
+
+  const collapsed = collapseActiveFactDuplicates(plan, new Map([["default", local]]), new Map([["default", peer]]));
+
+  assert.equal(collapsed.converged, true);
+  assert.deepEqual(collapsed.entries, [
+    {
+      path: "facts/local-id.md",
+      namespace: "default",
+      action: "identical",
+      reason: "semantic_duplicate",
+      localSha256: localFile.sha256,
+      peerSha256: peerFile.sha256,
+    },
+  ]);
+  assert.equal(collapsed.byNamespace[0]?.identical, 1);
+  assert.equal(collapsed.byNamespace[0]?.pull, 0);
+  assert.equal(collapsed.byNamespace[0]?.push, 0);
+});
+
+test("semantic collapse does not fold non-active facts or unrelated path conflicts", () => {
+  const semanticHash = ContentHashIndex.computeHash("same inactive fact");
+  const localFile = { path: "facts/local.md", sha256: "a".repeat(64) };
+  const peerFile = { path: "facts/peer.md", sha256: "b".repeat(64) };
+  const plan = planReconciliation([{ namespace: "default", local: [localFile], peer: [peerFile] }]);
+  const manifest = (file: typeof localFile, id: string, status: "active" | "archived"): ReconcileManifest => ({
+    format: "remnic-reconcile-manifest",
+    schemaVersion: 1,
+    files: [{ ...file, memory: { id, category: "fact", contentHash: semanticHash, status } }],
+  });
+
+  const collapsed = collapseActiveFactDuplicates(
+    plan,
+    new Map([["default", manifest(localFile, "local", "active")]]),
+    new Map([["default", manifest(peerFile, "peer", "archived")]])
+  );
+
+  assert.deepEqual(collapsed, plan);
+});
+
+test("semantic collapse leaves tombstone suppression authoritative", () => {
+  const semanticHash = ContentHashIndex.computeHash("retracted fact");
+  const localFile = { path: "facts/local.md", sha256: "a".repeat(64) };
+  const peerFile = { path: "facts/peer.md", sha256: "b".repeat(64) };
+  const plan = planReconciliation([
+    {
+      namespace: "default",
+      local: [localFile],
+      peer: [peerFile],
+      tombstonedFileSha256: [localFile.sha256],
+    },
+  ]);
+  const manifest = (file: typeof localFile, id: string): ReconcileManifest => ({
+    format: "remnic-reconcile-manifest",
+    schemaVersion: 1,
+    files: [{ ...file, memory: { id, category: "fact", contentHash: semanticHash, status: "active" } }],
+  });
+
+  const collapsed = collapseActiveFactDuplicates(
+    plan,
+    new Map([["default", manifest(localFile, "local")]]),
+    new Map([["default", manifest(peerFile, "peer")]])
+  );
+
+  assert.deepEqual(collapsed, plan);
+  assert.equal(
+    collapsed.entries.some((entry) => entry.action === "suppress"),
+    true
+  );
+});
+
+test("semantic collapse preserves same-path metadata updates", () => {
+  const path = "facts/shared.md";
+  const localFile = { path, sha256: "a".repeat(64) };
+  const peerFile = { path, sha256: "b".repeat(64) };
+  const baseFile = { path, sha256: peerFile.sha256 };
+  const semanticHash = ContentHashIndex.computeHash("same raw fact");
+  const plan = planReconciliation([{ namespace: "default", local: [localFile], peer: [peerFile], base: [baseFile] }]);
+  const manifest = (file: typeof localFile, id: string): ReconcileManifest => ({
+    format: "remnic-reconcile-manifest",
+    schemaVersion: 1,
+    files: [{ ...file, memory: { id, category: "fact", contentHash: semanticHash, status: "active" } }],
+  });
+
+  const collapsed = collapseActiveFactDuplicates(
+    plan,
+    new Map([["default", manifest(localFile, "local")]]),
+    new Map([["default", manifest(peerFile, "peer")]])
+  );
+
+  assert.deepEqual(collapsed, plan);
+  assert.equal(collapsed.entries[0]?.action, "push");
+});
+
+test("semantic collapse remains converged after transferring the canonical one-sided duplicate", () => {
+  const semanticHash = ContentHashIndex.computeHash("same one-sided fact");
+  const canonical = { path: "facts/a.md", sha256: "a".repeat(64) };
+  const duplicate = { path: "facts/b.md", sha256: "b".repeat(64) };
+  const manifest = (files: Array<{ path: string; sha256: string }>): ReconcileManifest => ({
+    format: "remnic-reconcile-manifest",
+    schemaVersion: 1,
+    files: files.map((file) => ({
+      ...file,
+      memory: {
+        id: file.path,
+        category: "fact",
+        contentHash: semanticHash,
+        status: "active",
+      },
+    })),
+  });
+  const localManifest = manifest([canonical, duplicate]);
+  const firstPlan = planReconciliation([{ namespace: "default", local: [canonical, duplicate], peer: [] }]);
+
+  const firstCollapsed = collapseActiveFactDuplicates(
+    firstPlan,
+    new Map([["default", localManifest]]),
+    new Map([["default", manifest([])]])
+  );
+
+  assert.deepEqual(
+    firstCollapsed.entries.map((entry) => [entry.path, entry.action]),
+    [[canonical.path, "push"]]
+  );
+
+  const rerunPlan = planReconciliation([{ namespace: "default", local: [canonical, duplicate], peer: [canonical] }]);
+  const rerunCollapsed = collapseActiveFactDuplicates(
+    rerunPlan,
+    new Map([["default", localManifest]]),
+    new Map([["default", manifest([canonical])]])
+  );
+
+  assert.equal(rerunCollapsed.converged, true, JSON.stringify(rerunCollapsed));
+  assert.deepEqual(
+    rerunCollapsed.entries.map((entry) => [entry.path, entry.action]),
+    [[canonical.path, "identical"]]
+  );
+});