@remnic/core 1.1.30 → 9.3.515

package/src/migrate/from-engram.ts

@@ -58,6 +58,8 @@ interface TokenEntry {
   token: string;
 }
 
+type PersistRollbackManifest = () => Promise<void>;
+
 const MARKER_FILE = ".migrated-from-engram";
 const LOCK_FILE = ".migration.lock";
 const ROLLBACK_MANIFEST = ".rollback.json";
@@ -163,11 +165,32 @@ async function pathExistsNoFollow(filePath: string): Promise<boolean> {
   }
 }
 
+async function assertExistingRegularFileNoFollow(filePath: string, label: string): Promise<void> {
+  const fileStat = await lstat(filePath);
+  if (fileStat.isSymbolicLink()) {
+    throw new Error(`${label} must not be a symlink: ${filePath}`);
+  }
+  if (!fileStat.isFile()) {
+    throw new Error(`${label} must be a regular file: ${filePath}`);
+  }
+}
+
+async function isExistingRegularFileNoFollow(filePath: string): Promise<boolean> {
+  try {
+    const fileStat = await lstat(filePath);
+    return fileStat.isFile() && !fileStat.isSymbolicLink();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return false;
+    throw error;
+  }
+}
+
 async function copyTreeMissing(
   source: string,
   destination: string,
   copied: string[],
   manifest: RollbackManifest,
+  persistManifest?: PersistRollbackManifest,
   isRoot = true,
 ): Promise<void> {
   if (!existsSync(source)) return;
@@ -190,6 +213,7 @@ async function copyTreeMissing(
         path.join(destination, entry.name),
         copied,
         manifest,
+        persistManifest,
         false,
       );
     }
@@ -199,7 +223,7 @@ async function copyTreeMissing(
   if (await pathExistsNoFollow(destination)) return;
   await ensureParent(destination);
   await copyFile(source, destination);
-  await recordCreatedPath(destination, manifest);
+  await recordCreatedPath(destination, manifest, persistManifest);
   copied.push(destination);
 }
 
@@ -251,6 +275,7 @@ function isPlainJsonObject(value: unknown): value is Record<string, unknown> {
 
 async function rewriteTokensIfPresent(filePath: string): Promise<number> {
   if (!existsSync(filePath)) return 0;
+  await assertExistingRegularFileNoFollow(filePath, "Remnic token store");
   await secureTokenFilePermissions(filePath);
   let raw: Record<string, unknown>;
   try {
@@ -294,8 +319,13 @@ async function mergeLegacyTokens(
   homeDir: string,
   manifest: RollbackManifest,
   backupExisting: boolean,
+  persistManifest?: PersistRollbackManifest,
 ): Promise<number> {
+  if (existsSync(legacyTokensPath)) {
+    await assertExistingRegularFileNoFollow(legacyTokensPath, "legacy Engram token store");
+  }
   if (!existsSync(remnicTokensPath)) return 0;
+  await assertExistingRegularFileNoFollow(remnicTokensPath, "Remnic token store");
   await secureTokenFilePermissions(remnicTokensPath);
   if (!existsSync(legacyTokensPath)) return rewriteTokensIfPresent(remnicTokensPath);
 
@@ -325,7 +355,7 @@ async function mergeLegacyTokens(
     });
 
     if (backupExisting) {
-      await backupFile(remnicTokensPath, originalRemnic, homeDir, manifest);
+      await backupFile(remnicTokensPath, originalRemnic, homeDir, manifest, persistManifest);
     }
 
     await writeTokenStoreFile(
@@ -364,7 +394,7 @@ async function mergeLegacyTokens(
   if (!changed) return rewritten;
 
   if (backupExisting) {
-    await backupFile(remnicTokensPath, originalRemnic, homeDir, manifest);
+    await backupFile(remnicTokensPath, originalRemnic, homeDir, manifest, persistManifest);
   }
 
   await writeTokenStoreFile(
@@ -378,8 +408,16 @@ async function rewriteJsonFile(
   targetPath: string,
   homeDir: string,
   manifest: RollbackManifest,
+  persistManifest?: PersistRollbackManifest,
 ): Promise<boolean> {
   if (!existsSync(targetPath)) return false;
+  const targetStat = await lstat(targetPath);
+  if (targetStat.isSymbolicLink()) return false;
+  if (!targetStat.isFile()) {
+    const error = new Error(`connector config must be a regular file: ${targetPath}`) as NodeJS.ErrnoException;
+    error.code = targetStat.isDirectory() ? "EISDIR" : "EINVAL";
+    throw error;
+  }
 
   const original = await readFile(targetPath, "utf8");
   let parsed: unknown;
@@ -408,7 +446,7 @@ async function rewriteJsonFile(
   const next = `${rewritten}\n`;
   if (!changed && next === original) return false;
 
-  await backupFile(targetPath, original, homeDir, manifest);
+  await backupFile(targetPath, original, homeDir, manifest, persistManifest);
   await writeFile(targetPath, next, "utf8");
   return true;
 }
@@ -418,6 +456,7 @@ async function backupFile(
   originalContent: string,
   homeDir: string,
   manifest: RollbackManifest,
+  persistManifest?: PersistRollbackManifest,
 ): Promise<void> {
   if (manifest.entries.some((entry) => entry.targetPath === targetPath && entry.backupPath)) {
     return;
@@ -433,11 +472,17 @@ async function backupFile(
     await chmod(backupPath, originalMode);
   }
   manifest.entries.push({ targetPath, backupPath });
+  await persistManifest?.();
 }
 
-async function recordCreatedPath(filePath: string, manifest: RollbackManifest): Promise<void> {
+async function recordCreatedPath(
+  filePath: string,
+  manifest: RollbackManifest,
+  persistManifest?: PersistRollbackManifest,
+): Promise<void> {
   if (manifest.entries.some((entry) => entry.targetPath === filePath)) return;
   manifest.entries.push({ targetPath: filePath, createdByMigration: true });
+  await persistManifest?.();
 }
 
 function defaultConnectorConfigPaths(homeDir: string, cwd: string): string[] {
@@ -454,11 +499,12 @@ async function updateConnectorConfigs(
   cwd: string,
   options: MigrationOptions | undefined,
   manifest: RollbackManifest,
+  persistManifest?: PersistRollbackManifest,
 ): Promise<string[]> {
   const updated: string[] = [];
   const candidates = options?.connectorConfigPaths ?? defaultConnectorConfigPaths(homeDir, cwd);
   for (const targetPath of candidates) {
-    if (await rewriteJsonFile(targetPath, homeDir, manifest)) {
+    if (await rewriteJsonFile(targetPath, homeDir, manifest, persistManifest)) {
       updated.push(targetPath);
     }
   }
@@ -469,10 +515,12 @@ async function copyLegacyConfig(
   homeDir: string,
   copied: string[],
   manifest: RollbackManifest,
+  persistManifest?: PersistRollbackManifest,
 ): Promise<void> {
   const source = legacyConfigPath(homeDir);
   const destination = remnicConfigPath(homeDir);
   if (!existsSync(source) || existsSync(destination)) return;
+  if (!(await isExistingRegularFileNoFollow(source))) return;
   await ensureParent(destination);
   const original = await readFile(source, "utf8");
   let next = rewriteRemnicText(original);
@@ -487,7 +535,7 @@ async function copyLegacyConfig(
     // Keep rewritten text when config is not JSON.
   }
   await writeFile(destination, `${next.trimEnd()}\n`, "utf8");
-  await recordCreatedPath(destination, manifest);
+  await recordCreatedPath(destination, manifest, persistManifest);
   copied.push(destination);
 }
 
@@ -499,6 +547,7 @@ async function migrateServices(
   homeDir: string,
   options: MigrationOptions | undefined,
   manifest: RollbackManifest,
+  persistManifest?: PersistRollbackManifest,
 ): Promise<string[]> {
   const logger = resolveLogger(options);
   const exec = resolveExec(options);
@@ -509,10 +558,11 @@ async function migrateServices(
     const legacyPlist = path.join(homeDir, "Library", "LaunchAgents", "ai.engram.daemon.plist");
     const remnicPlist = path.join(homeDir, "Library", "LaunchAgents", "ai.remnic.daemon.plist");
     if (existsSync(legacyPlist) && !existsSync(remnicPlist)) {
+      if (!(await isExistingRegularFileNoFollow(legacyPlist))) return servicesReinstalled;
       const next = rewriteServiceText(await readFile(legacyPlist, "utf8"));
       await ensureParent(remnicPlist);
       await writeFile(remnicPlist, next, "utf8");
-      await recordCreatedPath(remnicPlist, manifest);
+      await recordCreatedPath(remnicPlist, manifest, persistManifest);
       try {
         exec("launchctl", ["unload", legacyPlist]);
       } catch {
@@ -533,10 +583,11 @@ async function migrateServices(
     const legacyUnit = path.join(homeDir, ".config", "systemd", "user", "engram.service");
     const remnicUnit = path.join(homeDir, ".config", "systemd", "user", "remnic.service");
     if (existsSync(legacyUnit) && !existsSync(remnicUnit)) {
+      if (!(await isExistingRegularFileNoFollow(legacyUnit))) return servicesReinstalled;
       const next = rewriteServiceText(await readFile(legacyUnit, "utf8"));
       await ensureParent(remnicUnit);
       await writeFile(remnicUnit, next, "utf8");
-      await recordCreatedPath(remnicUnit, manifest);
+      await recordCreatedPath(remnicUnit, manifest, persistManifest);
       try {
         exec("systemctl", ["--user", "stop", "engram.service"]);
         exec("systemctl", ["--user", "disable", "engram.service"]);
@@ -738,16 +789,18 @@ export async function migrateFromEngram(options?: MigrationOptions): Promise<Mig
       };
     }
 
-    const manifest: RollbackManifest = {
+    const manifest: RollbackManifest = await readRollbackManifest(homeDir) ?? {
       version: 1,
       createdAt: new Date().toISOString(),
       entries: [],
     };
+    const persistManifest = () => writeRollbackManifest(homeDir, manifest);
 
     logger("First run after Engram -> Remnic rename. Migrating...");
     await mkdir(remnicRoot(homeDir), { recursive: true });
-    await copyTreeMissing(legacyRoot(homeDir), remnicRoot(homeDir), copied, manifest);
-    await copyLegacyConfig(homeDir, copied, manifest);
+    await persistManifest();
+    await copyTreeMissing(legacyRoot(homeDir), remnicRoot(homeDir), copied, manifest, persistManifest);
+    await copyLegacyConfig(homeDir, copied, manifest, persistManifest);
 
     const legacyTokens = path.join(legacyRoot(homeDir), "tokens.json");
     const remnicTokens = path.join(remnicRoot(homeDir), "tokens.json");
@@ -760,18 +813,19 @@ export async function migrateFromEngram(options?: MigrationOptions): Promise<Mig
         homeDir,
         manifest,
         true,
+        persistManifest,
       );
     }
     if (existsSync(remnicTokens)) {
       logger("tokens copied to ~/.remnic/tokens.json (legacy prefixes rewritten)");
     }
 
-    const updatedConfigs = await updateConnectorConfigs(homeDir, cwd, options, manifest);
+    const updatedConfigs = await updateConnectorConfigs(homeDir, cwd, options, manifest, persistManifest);
     for (const updated of updatedConfigs) {
       logger(`Updated connector config: ${updated}`);
     }
 
-    servicesReinstalled = await migrateServices(homeDir, options, manifest);
+    servicesReinstalled = await migrateServices(homeDir, options, manifest, persistManifest);
     await writeRollbackManifest(homeDir, manifest);
     await writeFile(markerPath(homeDir), `${new Date().toISOString()}\n`, "utf8");
     logger("Migration complete. Welcome to Remnic.");

package/src/model-registry.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+
+import { ModelRegistry } from "./model-registry.js";
+
+test("calculateContextSizes keeps output budget inside a small valid override", () => {
+  const dir = mkdtempSync(join(tmpdir(), "remnic-model-registry-"));
+  try {
+    const registry = new ModelRegistry(dir);
+    const sizes = registry.calculateContextSizes("local-model", 1024);
+
+    assert.equal(sizes.maxOutputTokens, 256);
+    assert.match(sizes.description, /1,024 context \(user override\)/);
+    assert.ok(sizes.maxInputChars > 0);
+    assert.ok(sizes.maxOutputTokens < 1024);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("calculateContextSizes ignores invalid or tiny override values before budgeting", () => {
+  const dir = mkdtempSync(join(tmpdir(), "remnic-model-registry-"));
+  try {
+    const registry = new ModelRegistry(dir);
+    for (const override of [0, 128, 256, Number.NaN, Number.POSITIVE_INFINITY]) {
+      const sizes = registry.calculateContextSizes("local-model", override);
+
+      assert.match(sizes.description, /32,768 context \(default\)/);
+      assert.ok(sizes.maxInputChars > 0);
+      assert.ok(sizes.maxOutputTokens < 32768);
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});

package/src/model-registry.ts

@@ -235,13 +235,20 @@ export class ModelRegistry {
     const caps = this.getCapabilities(modelId);
 
     // Use override if provided (e.g., user knows their LLM server limits), otherwise use detected caps
-    const effectiveContextWindow = maxContextOverride ?? caps.contextWindow;
+    const sanitizedOverride =
+      typeof maxContextOverride === "number" &&
+      Number.isFinite(maxContextOverride) &&
+      Number.isInteger(maxContextOverride) &&
+      maxContextOverride >= 1024
+        ? maxContextOverride
+        : undefined;
+    const effectiveContextWindow = sanitizedOverride ?? Math.max(1024, Math.floor(caps.contextWindow));
 
     // Guardrails: never allow output budget to exceed the model/server context window.
     // If we do, input budget goes negative and we end up generating huge, invalid prompts.
     const overheadTokens = Math.min(1000, Math.floor(effectiveContextWindow / 10)); // <=10% overhead, max 1k
     const minInputTokens = Math.min(512, Math.floor(effectiveContextWindow / 4)); // keep some room even on small contexts
-    const minOutputTokens = 256;
+    const minOutputTokens = Math.min(256, Math.max(1, effectiveContextWindow - overheadTokens - minInputTokens));
 
     // Base output budget: typical output, but scaled down for small contexts.
     let outputTokens = caps.typicalOutputTokens;
@@ -255,10 +262,8 @@ export class ModelRegistry {
     outputTokens = Math.min(outputTokens, Math.floor(effectiveContextWindow / 4));
 
     // Clamp output so we always have positive input headroom.
-    outputTokens = Math.max(
-      minOutputTokens,
-      Math.min(outputTokens, effectiveContextWindow - overheadTokens - minInputTokens),
-    );
+    const maxOutputTokens = Math.max(1, effectiveContextWindow - overheadTokens - minInputTokens);
+    outputTokens = Math.min(maxOutputTokens, Math.max(minOutputTokens, outputTokens));
 
     const availableForInput = Math.max(
       0,
@@ -268,7 +273,7 @@ export class ModelRegistry {
     // Convert to characters (rough estimate: 1 token ≈ 4 chars)
     const maxInputChars = Math.max(0, Math.floor(availableForInput * 3.5)); // Conservative: 3.5 chars/token
 
-    const source = maxContextOverride ? "user override" : caps.source;
+    const source = sanitizedOverride ? "user override" : caps.source;
     return {
       maxInputChars,
       maxOutputTokens: outputTokens,

package/src/namespaces/identity.test.ts

@@ -0,0 +1,66 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import { namespaceCollectionName } from "./search.js";
+import { NamespaceStorageRouter } from "./storage.js";
+import type { PluginConfig } from "../types.js";
+
+test("namespace collection names preserve case-variant namespace identity", () => {
+  const upper = namespaceCollectionName("remnic", "ProjectA");
+  const lower = namespaceCollectionName("remnic", "projecta");
+
+  assert.notEqual(upper, lower);
+  assert.match(upper, /^remnic--ns-[0-9a-f]+$/);
+  assert.match(lower, /^remnic--ns-[0-9a-f]+$/);
+});
+
+test("namespace storage paths preserve case-variant namespace identity", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-ns-"));
+  try {
+    const config = {
+      memoryDir,
+      namespacesEnabled: true,
+      defaultNamespace: "default",
+      entitySchemas: {},
+      inlineSourceAttributionFormat: undefined,
+    } as unknown as PluginConfig;
+    const router = new NamespaceStorageRouter(config);
+
+    const upper = await router.storageFor("ProjectA");
+    const lower = await router.storageFor("projecta");
+
+    assert.notEqual(upper.dir, lower.dir);
+    assert.ok(upper.dir.startsWith(path.join(memoryDir, "namespaces")));
+    assert.ok(lower.dir.startsWith(path.join(memoryDir, "namespaces")));
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("namespace storage prefers tokenized roots that contain migrated data", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-ns-"));
+  try {
+    const config = {
+      memoryDir,
+      namespacesEnabled: true,
+      defaultNamespace: "default",
+      entitySchemas: {},
+      inlineSourceAttributionFormat: undefined,
+    } as unknown as PluginConfig;
+    await mkdir(path.join(memoryDir, "namespaces", "team-beta"), { recursive: true });
+    const router = new NamespaceStorageRouter(config);
+    const beforeMigration = await router.storageFor("team-beta");
+    assert.equal(beforeMigration.dir, path.join(memoryDir, "namespaces", "team-beta"));
+
+    await mkdir(path.join(memoryDir, "namespaces", "ns-7465616d2d62657461", "preferences"), {
+      recursive: true,
+    });
+    const afterMigration = await router.storageFor("team-beta");
+    assert.equal(afterMigration.dir, path.join(memoryDir, "namespaces", "ns-7465616d2d62657461"));
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/namespaces/identity.ts

@@ -0,0 +1,23 @@
+export function normalizeNamespaceIdentity(namespace: string): string {
+  return namespace.trim();
+}
+
+export function namespaceIdentityToken(namespace: string): string {
+  const normalized = normalizeNamespaceIdentity(namespace);
+  const bytes = new TextEncoder().encode(normalized);
+  const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+  return `ns-${hex || "default"}`;
+}
+
+export function namespaceIdentityFromToken(token: string): string | null {
+  if (!token.startsWith("ns-")) return null;
+  const hex = token.slice(3);
+  if (hex === "default") return "";
+  if (hex.length === 0 || hex.length % 2 !== 0 || !/^[0-9a-f]+$/i.test(hex)) {
+    return null;
+  }
+  const decoded = Buffer.from(hex, "hex").toString("utf8");
+  return namespaceIdentityToken(decoded).toLowerCase() === token.toLowerCase()
+    ? decoded
+    : null;
+}

package/src/namespaces/migrate.test.ts

@@ -0,0 +1,62 @@
+import assert from "node:assert/strict";
+import { mkdir, mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import type { PluginConfig } from "../types.js";
+import { namespaceIdentityToken } from "./identity.js";
+import { listNamespaces } from "./migrate.js";
+
+test("listNamespaces decodes tokenized namespace directories", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-ns-migrate-"));
+  try {
+    const namespace = "team-beta";
+    await mkdir(path.join(memoryDir, "namespaces", namespaceIdentityToken(namespace), "facts"), {
+      recursive: true,
+    });
+    const namespaces = await listNamespaces({
+      config: {
+        memoryDir,
+        namespacesEnabled: true,
+        defaultNamespace: "default",
+        sharedNamespace: "shared",
+        namespacePolicies: [],
+        qmdCollection: "remnic",
+        entitySchemas: {},
+        inlineSourceAttributionFormat: undefined,
+      } as unknown as PluginConfig,
+    });
+
+    assert.ok(namespaces.some((entry) => entry.namespace === namespace && entry.hasMemoryData));
+    assert.ok(!namespaces.some((entry) => entry.namespace === namespaceIdentityToken(namespace)));
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});
+
+test("listNamespaces preserves configured raw namespace names that look tokenized", async () => {
+  const memoryDir = await mkdtemp(path.join(os.tmpdir(), "remnic-ns-migrate-"));
+  try {
+    const namespace = namespaceIdentityToken("team-beta");
+    await mkdir(path.join(memoryDir, "namespaces", namespace, "facts"), {
+      recursive: true,
+    });
+    const namespaces = await listNamespaces({
+      config: {
+        memoryDir,
+        namespacesEnabled: true,
+        defaultNamespace: "default",
+        sharedNamespace: "shared",
+        namespacePolicies: [{ name: namespace, readPrincipals: ["*"], writePrincipals: ["*"] }],
+        qmdCollection: "remnic",
+        entitySchemas: {},
+        inlineSourceAttributionFormat: undefined,
+      } as unknown as PluginConfig,
+    });
+
+    assert.ok(namespaces.some((entry) => entry.namespace === namespace && entry.hasMemoryData));
+    assert.ok(!namespaces.some((entry) => entry.namespace === "team-beta"));
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});

package/src/namespaces/migrate.ts

@@ -1,25 +1,20 @@
 import path from "node:path";
-import { access, mkdir, readdir, rename } from "node:fs/promises";
+import { access, lstat, mkdir, readdir, realpath, rename, rmdir } from "node:fs/promises";
 import type { PluginConfig } from "../types.js";
 import { NamespaceStorageRouter } from "./storage.js";
 import { namespaceCollectionName } from "./search.js";
 import { isSafeRouteNamespace } from "../routing/engine.js";
+import { namespaceIdentityFromToken, namespaceIdentityToken } from "./identity.js";
+import { ALL_CATEGORY_DIRS } from "../utils/category-dir.js";
 
 const LEGACY_NAMESPACE_CHILDREN = [
-  "facts",
-  "corrections",
+  ...ALL_CATEGORY_DIRS,
   "entities",
-  "questions",
   "artifacts",
   "identity",
   "state",
   "config",
   "summaries",
-  "procedures",
-  // Issue #564 PR 3: reasoning_trace memories live in their own subtree.
-  // Must be included here so namespace migration moves existing traces
-  // into the target namespace root alongside other memory data.
-  "reasoning-traces",
   "profile.md",
 ] as const;
 
@@ -75,13 +70,18 @@ async function discoverConfiguredNamespaces(
     config.sharedNamespace,
     ...config.namespacePolicies.map((policy) => policy.name),
   ]);
+  const configuredNamespaces = new Set(discovered);
 
   const namespacesDir = path.join(config.memoryDir, "namespaces");
   try {
     const entries = await readdir(namespacesDir, { withFileTypes: true });
     for (const entry of entries) {
-      if (entry.isDirectory() && isSafeRouteNamespace(entry.name)) {
-        discovered.add(entry.name);
+      if (!entry.isDirectory()) continue;
+      const namespace = configuredNamespaces.has(entry.name)
+        ? entry.name
+        : namespaceIdentityFromToken(entry.name) ?? entry.name;
+      if (isSafeRouteNamespace(namespace)) {
+        discovered.add(namespace);
       }
     }
   } catch {
@@ -144,6 +144,7 @@ export async function runNamespaceMigration(options: {
   config: PluginConfig;
   to: string;
   dryRun?: boolean;
+  renameFn?: typeof rename;
 }): Promise<NamespaceMigrationReport> {
   if (!options.config.namespacesEnabled) {
     throw new Error("Namespaces are disabled.");
@@ -154,8 +155,13 @@ export async function runNamespaceMigration(options: {
     throw new Error(`Invalid namespace: ${options.to}`);
   }
 
-  const targetRoot = path.join(options.config.memoryDir, "namespaces", targetNamespace);
+  const targetRoot = path.join(
+    options.config.memoryDir,
+    "namespaces",
+    namespaceIdentityToken(targetNamespace),
+  );
   const moved: NamespaceMigrationMove[] = [];
+  const renamePath = options.renameFn ?? rename;
 
   for (const child of LEGACY_NAMESPACE_CHILDREN) {
     const from = path.join(options.config.memoryDir, child);
@@ -164,13 +170,45 @@ export async function runNamespaceMigration(options: {
     if (await exists(to)) {
       throw new Error(`Target already contains ${child}: ${to}`);
     }
+    const sourceStat = await lstat(from);
+    if (sourceStat.isSymbolicLink()) {
+      throw new Error(`Refusing to migrate symlinked legacy path: ${from}`);
+    }
     moved.push({ from, to });
   }
 
   if (!options.dryRun && moved.length > 0) {
+    await assertSafeNamespaceTarget(options.config.memoryDir, targetRoot);
     await mkdir(targetRoot, { recursive: true });
-    for (const move of moved) {
-      await rename(move.from, move.to);
+    await assertSafeNamespaceTarget(options.config.memoryDir, targetRoot);
+    const completed: NamespaceMigrationMove[] = [];
+    try {
+      for (const move of moved) {
+        await renamePath(move.from, move.to);
+        completed.push(move);
+      }
+    } catch (cause) {
+      const rollbackErrors: string[] = [];
+      for (const move of completed.reverse()) {
+        try {
+          if (!(await exists(move.from)) && (await exists(move.to))) {
+            await rename(move.to, move.from);
+          }
+        } catch (rollbackCause) {
+          rollbackErrors.push(rollbackCause instanceof Error ? rollbackCause.message : String(rollbackCause));
+        }
+      }
+      try {
+        await rmdir(targetRoot);
+      } catch {
+        // Target may predate migration or still contain unrelated files.
+      }
+      const message = cause instanceof Error ? cause.message : String(cause);
+      throw new Error(
+        `Namespace migration failed and was rolled back: ${message}` +
+          (rollbackErrors.length > 0 ? `; rollback errors: ${rollbackErrors.join("; ")}` : ""),
+        { cause },
+      );
     }
   }
 
@@ -185,3 +223,33 @@ export async function runNamespaceMigration(options: {
     }),
   };
 }
+
+async function assertSafeNamespaceTarget(memoryDir: string, targetRoot: string): Promise<void> {
+  const memoryReal = await realpath(memoryDir);
+  const namespacesDir = path.join(memoryDir, "namespaces");
+  if (await exists(namespacesDir)) {
+    const namespacesStat = await lstat(namespacesDir);
+    if (namespacesStat.isSymbolicLink()) {
+      throw new Error(`Refusing to migrate through symlinked namespaces directory: ${namespacesDir}`);
+    }
+    const namespacesReal = await realpath(namespacesDir);
+    if (!isPathInside(memoryReal, namespacesReal)) {
+      throw new Error(`Refusing to migrate through namespaces directory outside memoryDir: ${namespacesDir}`);
+    }
+  }
+  if (await exists(targetRoot)) {
+    const targetStat = await lstat(targetRoot);
+    if (targetStat.isSymbolicLink()) {
+      throw new Error(`Refusing to migrate into symlinked namespace root: ${targetRoot}`);
+    }
+    const targetReal = await realpath(targetRoot);
+    if (!isPathInside(memoryReal, targetReal)) {
+      throw new Error(`Refusing to migrate into namespace root outside memoryDir: ${targetRoot}`);
+    }
+  }
+}
+
+function isPathInside(root: string, child: string): boolean {
+  const relative = path.relative(root, child);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}