zen-fs-config 0.5.32 → 0.5.33

package/dist/index.d.mts

@@ -57,7 +57,7 @@ declare function isMtimeSidecar(fileName: string): boolean;
  * Delete every `.mtime` sidecar stored in a local primary backend.
  *
  * Walks the whole tree from `options.root` — including dotfiles and `/.meta/`,
- * because sidecars live next to their data file and are themselves dotfiles.
+ * because sidecars live next to their data file as `<name>.mtime` files.
  * Unreadable entries are skipped; failures on individual files are collected
  * in `failed` instead of aborting the walk.
  */
@@ -229,6 +229,18 @@ interface ConfigRepoOptions {
      * Default: `true`. Pass `false` to skip the (local-only) startup sweep.
      */
     purgeMtimeSidecars?: boolean;
+    /**
+     * Migrate legacy `.x.version` sidecars to the new `<name>.version` naming on
+     * startup (rename locally, delete the remote residual).
+     *
+     * Older builds stored version sidecars as hidden dotfiles (`.db.json.version`).
+     * They are now `<name>.version`. This one-time sweep renames existing legacy
+     * sidecars (preserving version history) and removes the old copy from every
+     * replica so sync does not pull it back.
+     *
+     * Default: `true`. Pass `false` to skip the startup sweep.
+     */
+    migrateVersionSidecars?: boolean;
 }
 /** Type of sync group. */
 type SyncGroupType = 'config-sync' | 'data-sync';
@@ -585,6 +597,71 @@ declare function getAccountFields(type: string): string[];
 declare function mergeAccountFields(targetType: string, sourceOptions: Record<string, unknown>, targetOptions: Record<string, unknown>): Record<string, unknown>;
 declare function wrapZenFSFileSystem(config: any): Promise<BackendInstance>;
 
+/**
+ * zen-fs-config — Legacy Version Sidecar Migration
+ *
+ * Version sidecars used to be stored as hidden dotfiles:
+ *
+ *   config file:  /app-a/db.json
+ *   version file: /app-a/.db.json.version        (OLD — starts with `.`)
+ *
+ * They are now stored as `<name>.version` (no leading dot):
+ *
+ *   version file: /app-a/db.json.version         (NEW)
+ *
+ * This module migrates existing legacy sidecars to the new naming at startup,
+ * preserving version history (the file content is byte-identical after rename).
+ *
+ * Ambiguity safety: a legacy path `.x.version` could in theory belong to either
+ * a dotfile config `.x` (whose version is unchanged by the rename) or a
+ * non-dot config `x` (old naming). We resolve it by probing the directory:
+ *   - `.x` exists  → it's the dotfile config's version → NEW path == legacy → skip
+ *   - `x`  exists  → rename legacy `.x.version` → `x.version`
+ *   - neither      → orphan (config gone) → delete
+ *
+ * We also delete the remote residual legacy path from every replica so the
+ * sync engine does not pull the old sidecar back (zen-fs-sync syncs `.version`
+ * files on both ends).
+ */
+/** Minimal async FS surface needed to read/rename/delete on the local primary. */
+interface MigrateLocalFS {
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<{
+        mode?: number;
+    }>;
+    readFile(path: string, encoding?: string): Promise<Uint8Array | string>;
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+    unlink(path: string): Promise<void>;
+}
+/** Minimal async FS surface needed to delete remote residual legacy sidecars. */
+interface MigrateReplicaFS {
+    unlink(path: string): Promise<void>;
+}
+interface VersionMigrationOptions {
+    /** Root to scan. Default: `/` (the whole local primary). */
+    root?: string;
+    /** Report what would change without touching anything. */
+    dryRun?: boolean;
+    /** Replica backends whose legacy sidecars should be deleted. */
+    replicas?: MigrateReplicaFS[];
+}
+interface VersionMigrationResult {
+    /** Local legacy sidecars renamed to the new naming. */
+    renamed: string[];
+    /** Local orphan legacy sidecars deleted (no owning config). */
+    deleted: string[];
+    /** Remote residual legacy sidecars deleted (best-effort). */
+    remoteDeleted: string[];
+    /** Paths that failed to migrate. */
+    failed: string[];
+}
+/**
+ * Walk `fs` from `options.root` and migrate every legacy `.x.version` /
+ * `.x.version.mtime` sidecar to the new `<name>.version` / `<name>.version.mtime`
+ * naming. Best-effort: failures are collected in `failed`, never thrown.
+ */
+declare function migrateVersionSidecars(fs: MigrateLocalFS, options?: VersionMigrationOptions): Promise<VersionMigrationResult>;
+
 /**
  * zen-fs-config — ConfigRepo Implementation
  *
@@ -690,6 +767,15 @@ declare class ConfigRepo implements IConfigRepo {
      * @param options.dryRun List the sidecars without deleting them.
      */
     purgeMtimeSidecars(options?: PurgeMtimeOptions): Promise<MtimePurgeResult>;
+    /**
+     * Migrate legacy `.x.version` sidecars (old dotfile naming) to the new
+     * `<name>.version` naming. Renames local sidecars (preserving content/history)
+     * and deletes the residual legacy copy from every replica backend so sync
+     * does not pull it back. Best-effort: failures are logged, never thrown.
+     *
+     * Runs once at startup (see createConfigRepo). Safe to call again.
+     */
+    migrateLegacyVersionSidecars(): Promise<VersionMigrationResult>;
     /**
      * Perform a full sync + dedup cycle without the watch snapshot cache.
      * Used by createConfigRepo to pull remote-only files (like duplicate
@@ -876,24 +962,35 @@ declare function connect(appId: string, options?: ConnectOptions): Promise<Conne
 /**
  * zen-fs-config — Sidecar Version File Management
  *
- * Each config file has a companion .version file for version-based change
- * detection and conflict resolution.
+ * Each config file has a companion `.version` sidecar file for version-based
+ * change detection and conflict resolution. The sidecar is named `<name>.version`
+ * (NOT `.name.version`) so it is not a hidden dotfile.
  *
  * Config file:  /app-a/db.json
- * Version file: /app-a/.db.json.version
+ * Version file: /app-a/db.json.version
  */
 
 /**
  * Compute the sidecar version file path from a config file path.
  *
- * /app-a/db.json        → /app-a/.db.json.version
- * /shared/flags.json    → /shared/.flags.json.version
- * /nodes/s1/env.json    → /nodes/s1/.env.json.version
+ * /app-a/db.json        → /app-a/db.json.version
+ * /shared/flags.json    → /shared/flags.json.version
+ * /nodes/s1/env.json    → /nodes/s1/env.json.version
  *
  * Returns null for files that are already version sidecars (.version files),
- * to prevent creating version-of-version files (e.g. ..db.json.version.version).
+ * to prevent creating version-of-version files (e.g. db.json.version.version).
  */
 declare function versionPathFor(configFilePath: string): string | null;
+/**
+ * Compute the *legacy* (pre-dotfile-removal) version sidecar path for a config
+ * file. Returns the old `.${name}.version` form for non-dot configs, or `null`
+ * for dotfile configs (whose version path is unchanged) and for version files
+ * themselves.
+ *
+ * Used as a read fallback so existing history in `.db.json.version` is still
+ * found after the naming scheme changed to `db.json.version`.
+ */
+declare function legacyVersionPathFor(configFilePath: string): string | null;
 /**
  * Compute SHA-256 hash of a Uint8Array.
  * Returns "sha256:" prefix + hex digest.
@@ -923,4 +1020,4 @@ declare function incrementVersion(fs: SyncableFS, configFilePath: string, newCon
  */
 declare function verifyOrRepairVersion(fs: SyncableFS, configFilePath: string, author: string): Promise<VersionMeta | null>;
 
-export { type AppDataBackendDescriptor, type AppDataGroup, type AppDataGroupDescriptor, type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendMetadata, type BackendParamDef, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type ConnectOptions, type ConnectResult, FolderStore, type IConfigRepo, LOCAL_IDB_BACKEND_ID, type MtimePurgeResult, type PurgeMtimeOptions, type PurgeableFS, type SyncGroupType, type TombstoneMeta, type VersionMeta, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, isMtimeSidecar, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, purgeMtimeSidecars, readVersion, registerBackend, registerFolderBackend, resolveLocalPrimary, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };
+export { type AppDataBackendDescriptor, type AppDataGroup, type AppDataGroupDescriptor, type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendMetadata, type BackendParamDef, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type ConnectOptions, type ConnectResult, FolderStore, type IConfigRepo, LOCAL_IDB_BACKEND_ID, type MigrateLocalFS, type MigrateReplicaFS, type MtimePurgeResult, type PurgeMtimeOptions, type PurgeableFS, type SyncGroupType, type TombstoneMeta, type VersionMeta, type VersionMigrationOptions, type VersionMigrationResult, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, isMtimeSidecar, legacyVersionPathFor, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, migrateVersionSidecars, purgeMtimeSidecars, readVersion, registerBackend, registerFolderBackend, resolveLocalPrimary, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };

package/dist/index.d.ts

@@ -57,7 +57,7 @@ declare function isMtimeSidecar(fileName: string): boolean;
  * Delete every `.mtime` sidecar stored in a local primary backend.
  *
  * Walks the whole tree from `options.root` — including dotfiles and `/.meta/`,
- * because sidecars live next to their data file and are themselves dotfiles.
+ * because sidecars live next to their data file as `<name>.mtime` files.
  * Unreadable entries are skipped; failures on individual files are collected
  * in `failed` instead of aborting the walk.
  */
@@ -229,6 +229,18 @@ interface ConfigRepoOptions {
      * Default: `true`. Pass `false` to skip the (local-only) startup sweep.
      */
     purgeMtimeSidecars?: boolean;
+    /**
+     * Migrate legacy `.x.version` sidecars to the new `<name>.version` naming on
+     * startup (rename locally, delete the remote residual).
+     *
+     * Older builds stored version sidecars as hidden dotfiles (`.db.json.version`).
+     * They are now `<name>.version`. This one-time sweep renames existing legacy
+     * sidecars (preserving version history) and removes the old copy from every
+     * replica so sync does not pull it back.
+     *
+     * Default: `true`. Pass `false` to skip the startup sweep.
+     */
+    migrateVersionSidecars?: boolean;
 }
 /** Type of sync group. */
 type SyncGroupType = 'config-sync' | 'data-sync';
@@ -585,6 +597,71 @@ declare function getAccountFields(type: string): string[];
 declare function mergeAccountFields(targetType: string, sourceOptions: Record<string, unknown>, targetOptions: Record<string, unknown>): Record<string, unknown>;
 declare function wrapZenFSFileSystem(config: any): Promise<BackendInstance>;
 
+/**
+ * zen-fs-config — Legacy Version Sidecar Migration
+ *
+ * Version sidecars used to be stored as hidden dotfiles:
+ *
+ *   config file:  /app-a/db.json
+ *   version file: /app-a/.db.json.version        (OLD — starts with `.`)
+ *
+ * They are now stored as `<name>.version` (no leading dot):
+ *
+ *   version file: /app-a/db.json.version         (NEW)
+ *
+ * This module migrates existing legacy sidecars to the new naming at startup,
+ * preserving version history (the file content is byte-identical after rename).
+ *
+ * Ambiguity safety: a legacy path `.x.version` could in theory belong to either
+ * a dotfile config `.x` (whose version is unchanged by the rename) or a
+ * non-dot config `x` (old naming). We resolve it by probing the directory:
+ *   - `.x` exists  → it's the dotfile config's version → NEW path == legacy → skip
+ *   - `x`  exists  → rename legacy `.x.version` → `x.version`
+ *   - neither      → orphan (config gone) → delete
+ *
+ * We also delete the remote residual legacy path from every replica so the
+ * sync engine does not pull the old sidecar back (zen-fs-sync syncs `.version`
+ * files on both ends).
+ */
+/** Minimal async FS surface needed to read/rename/delete on the local primary. */
+interface MigrateLocalFS {
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<{
+        mode?: number;
+    }>;
+    readFile(path: string, encoding?: string): Promise<Uint8Array | string>;
+    writeFile(path: string, data: Uint8Array): Promise<void>;
+    unlink(path: string): Promise<void>;
+}
+/** Minimal async FS surface needed to delete remote residual legacy sidecars. */
+interface MigrateReplicaFS {
+    unlink(path: string): Promise<void>;
+}
+interface VersionMigrationOptions {
+    /** Root to scan. Default: `/` (the whole local primary). */
+    root?: string;
+    /** Report what would change without touching anything. */
+    dryRun?: boolean;
+    /** Replica backends whose legacy sidecars should be deleted. */
+    replicas?: MigrateReplicaFS[];
+}
+interface VersionMigrationResult {
+    /** Local legacy sidecars renamed to the new naming. */
+    renamed: string[];
+    /** Local orphan legacy sidecars deleted (no owning config). */
+    deleted: string[];
+    /** Remote residual legacy sidecars deleted (best-effort). */
+    remoteDeleted: string[];
+    /** Paths that failed to migrate. */
+    failed: string[];
+}
+/**
+ * Walk `fs` from `options.root` and migrate every legacy `.x.version` /
+ * `.x.version.mtime` sidecar to the new `<name>.version` / `<name>.version.mtime`
+ * naming. Best-effort: failures are collected in `failed`, never thrown.
+ */
+declare function migrateVersionSidecars(fs: MigrateLocalFS, options?: VersionMigrationOptions): Promise<VersionMigrationResult>;
+
 /**
  * zen-fs-config — ConfigRepo Implementation
  *
@@ -690,6 +767,15 @@ declare class ConfigRepo implements IConfigRepo {
      * @param options.dryRun List the sidecars without deleting them.
      */
     purgeMtimeSidecars(options?: PurgeMtimeOptions): Promise<MtimePurgeResult>;
+    /**
+     * Migrate legacy `.x.version` sidecars (old dotfile naming) to the new
+     * `<name>.version` naming. Renames local sidecars (preserving content/history)
+     * and deletes the residual legacy copy from every replica backend so sync
+     * does not pull it back. Best-effort: failures are logged, never thrown.
+     *
+     * Runs once at startup (see createConfigRepo). Safe to call again.
+     */
+    migrateLegacyVersionSidecars(): Promise<VersionMigrationResult>;
     /**
      * Perform a full sync + dedup cycle without the watch snapshot cache.
      * Used by createConfigRepo to pull remote-only files (like duplicate
@@ -876,24 +962,35 @@ declare function connect(appId: string, options?: ConnectOptions): Promise<Conne
 /**
  * zen-fs-config — Sidecar Version File Management
  *
- * Each config file has a companion .version file for version-based change
- * detection and conflict resolution.
+ * Each config file has a companion `.version` sidecar file for version-based
+ * change detection and conflict resolution. The sidecar is named `<name>.version`
+ * (NOT `.name.version`) so it is not a hidden dotfile.
  *
  * Config file:  /app-a/db.json
- * Version file: /app-a/.db.json.version
+ * Version file: /app-a/db.json.version
  */
 
 /**
  * Compute the sidecar version file path from a config file path.
  *
- * /app-a/db.json        → /app-a/.db.json.version
- * /shared/flags.json    → /shared/.flags.json.version
- * /nodes/s1/env.json    → /nodes/s1/.env.json.version
+ * /app-a/db.json        → /app-a/db.json.version
+ * /shared/flags.json    → /shared/flags.json.version
+ * /nodes/s1/env.json    → /nodes/s1/env.json.version
  *
  * Returns null for files that are already version sidecars (.version files),
- * to prevent creating version-of-version files (e.g. ..db.json.version.version).
+ * to prevent creating version-of-version files (e.g. db.json.version.version).
  */
 declare function versionPathFor(configFilePath: string): string | null;
+/**
+ * Compute the *legacy* (pre-dotfile-removal) version sidecar path for a config
+ * file. Returns the old `.${name}.version` form for non-dot configs, or `null`
+ * for dotfile configs (whose version path is unchanged) and for version files
+ * themselves.
+ *
+ * Used as a read fallback so existing history in `.db.json.version` is still
+ * found after the naming scheme changed to `db.json.version`.
+ */
+declare function legacyVersionPathFor(configFilePath: string): string | null;
 /**
  * Compute SHA-256 hash of a Uint8Array.
  * Returns "sha256:" prefix + hex digest.
@@ -923,4 +1020,4 @@ declare function incrementVersion(fs: SyncableFS, configFilePath: string, newCon
  */
 declare function verifyOrRepairVersion(fs: SyncableFS, configFilePath: string, author: string): Promise<VersionMeta | null>;
 
-export { type AppDataBackendDescriptor, type AppDataGroup, type AppDataGroupDescriptor, type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendMetadata, type BackendParamDef, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type ConnectOptions, type ConnectResult, FolderStore, type IConfigRepo, LOCAL_IDB_BACKEND_ID, type MtimePurgeResult, type PurgeMtimeOptions, type PurgeableFS, type SyncGroupType, type TombstoneMeta, type VersionMeta, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, isMtimeSidecar, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, purgeMtimeSidecars, readVersion, registerBackend, registerFolderBackend, resolveLocalPrimary, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };
+export { type AppDataBackendDescriptor, type AppDataGroup, type AppDataGroupDescriptor, type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendMetadata, type BackendParamDef, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type ConnectOptions, type ConnectResult, FolderStore, type IConfigRepo, LOCAL_IDB_BACKEND_ID, type MigrateLocalFS, type MigrateReplicaFS, type MtimePurgeResult, type PurgeMtimeOptions, type PurgeableFS, type SyncGroupType, type TombstoneMeta, type VersionMeta, type VersionMigrationOptions, type VersionMigrationResult, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, isMtimeSidecar, legacyVersionPathFor, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, migrateVersionSidecars, purgeMtimeSidecars, readVersion, registerBackend, registerFolderBackend, resolveLocalPrimary, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };

package/dist/index.js

@@ -419,10 +419,12 @@ __export(index_exports, {
   incrementVersion: () => incrementVersion,
   isBrowserEnv: () => isBrowserEnv,
   isMtimeSidecar: () => isMtimeSidecar,
+  legacyVersionPathFor: () => legacyVersionPathFor,
   listBackendMetadata: () => listBackendMetadata,
   listBackends: () => listBackends,
   localPrimaryType: () => localPrimaryType,
   mergeAccountFields: () => mergeAccountFields,
+  migrateVersionSidecars: () => migrateVersionSidecars,
   purgeMtimeSidecars: () => purgeMtimeSidecars,
   readVersion: () => readVersion,
   registerBackend: () => registerBackend,
@@ -828,9 +830,30 @@ function versionPathFor(configFilePath) {
   if (fileName.endsWith(".version")) {
     return null;
   }
-  const versionFileName = fileName.startsWith(".") ? `${fileName}.version` : `.${fileName}.version`;
+  const versionFileName = `${fileName}.version`;
   return dir ? `${dir}/${versionFileName}` : versionFileName;
 }
+function legacyVersionPathFor(configFilePath) {
+  const lastSlash = configFilePath.lastIndexOf("/");
+  const dir = lastSlash >= 0 ? configFilePath.slice(0, lastSlash) : "";
+  const fileName = lastSlash >= 0 ? configFilePath.slice(lastSlash + 1) : configFilePath;
+  if (fileName.endsWith(".version")) return null;
+  if (fileName.startsWith(".")) return null;
+  const legacyFileName = `.${fileName}.version`;
+  return dir ? `${dir}/${legacyFileName}` : legacyFileName;
+}
+async function readVersionForConfig(fs, configFilePath) {
+  const newPath = versionPathFor(configFilePath);
+  if (newPath) {
+    const v = await readVersion(fs, newPath);
+    if (v) return v;
+  }
+  const legacyPath = legacyVersionPathFor(configFilePath);
+  if (legacyPath) {
+    return readVersion(fs, legacyPath);
+  }
+  return null;
+}
 function sha256PureJS(data) {
   const K = new Uint32Array([
     1116352408,
@@ -994,7 +1017,7 @@ async function writeVersion(fs, versionFilePath, meta) {
 }
 async function incrementVersion(fs, configFilePath, newContent, author) {
   const vPath = versionPathFor(configFilePath);
-  const prev = vPath ? await readVersion(fs, vPath) : null;
+  const prev = vPath ? await readVersionForConfig(fs, configFilePath) : null;
   const hash = await sha256(newContent);
   if (prev && prev.hash === hash) {
     return prev;
@@ -1009,7 +1032,7 @@ async function incrementVersion(fs, configFilePath, newContent, author) {
 async function verifyOrRepairVersion(fs, configFilePath, author) {
   const vPath = versionPathFor(configFilePath);
   if (!vPath) return null;
-  const existing = await readVersion(fs, vPath);
+  const existing = await readVersionForConfig(fs, configFilePath);
   if (!existing) return null;
   try {
     const content = await fs.readFile(configFilePath);
@@ -1094,6 +1117,131 @@ async function purgeMtimeSidecars(fs, options = {}) {
   return result;
 }
 
+// src/version-migration.ts
+var S_IFDIR2 = 16384;
+function isDir(stat) {
+  return typeof stat.mode === "number" && (stat.mode & S_IFDIR2) === S_IFDIR2;
+}
+function joinPath2(dir, entry) {
+  if (dir === "/" || dir === "") return `/${entry}`;
+  return `${dir.replace(/\/+$/, "")}/${entry}`;
+}
+async function existsPath(fs, p) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function configNameFromLegacy(entry) {
+  const noMtime = entry.endsWith(".version.mtime") ? entry.slice(0, -".version.mtime".length) : entry.slice(0, -".version".length);
+  return noMtime.slice(1);
+}
+async function resolveTarget(fs, dir, entry) {
+  const configName = configNameFromLegacy(entry);
+  const configPath = joinPath2(dir, configName);
+  const dotConfigPath = joinPath2(dir, `.${configName}`);
+  if (await existsPath(fs, dotConfigPath)) {
+    return { action: "skip" };
+  }
+  if (await existsPath(fs, configPath)) {
+    return { action: "rename", newPath: versionPathFor(configPath) ?? `${configName}.version` };
+  }
+  return { action: "delete" };
+}
+async function migrateVersionSidecars(fs, options = {}) {
+  const root = options.root && options.root !== "" ? options.root : "/";
+  const dryRun = options.dryRun ?? false;
+  const replicas = options.replicas ?? [];
+  const result = {
+    renamed: [],
+    deleted: [],
+    remoteDeleted: [],
+    failed: []
+  };
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = joinPath2(dir, entry);
+      let stat;
+      try {
+        stat = await fs.stat(full);
+      } catch {
+        continue;
+      }
+      if (isDir(stat)) {
+        stack.push(full);
+        continue;
+      }
+      const isLegacyVersion = entry.startsWith(".") && (entry.endsWith(".version") || entry.endsWith(".version.mtime"));
+      if (!isLegacyVersion) continue;
+      const legacyVerPath = entry.endsWith(".version.mtime") ? full.slice(0, -".mtime".length) : full;
+      const target = await resolveTarget(fs, dir, entry);
+      if (target.action === "skip") continue;
+      const legacyMtimePath = `${legacyVerPath}.mtime`;
+      const newMtimePath = target.newPath ? `${target.newPath}.mtime` : null;
+      if (dryRun) {
+        if (target.action === "rename") result.renamed.push(full);
+        else result.deleted.push(full);
+        continue;
+      }
+      try {
+        if (target.action === "rename") {
+          if (await existsPath(fs, target.newPath)) {
+            await fs.unlink(legacyVerPath);
+            result.deleted.push(full);
+          } else {
+            const content = await fs.readFile(legacyVerPath);
+            const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content;
+            await fs.writeFile(target.newPath, bytes);
+            await fs.unlink(legacyVerPath);
+            result.renamed.push(full);
+          }
+          if (newMtimePath && await existsPath(fs, legacyMtimePath)) {
+            try {
+              const mc = await fs.readFile(legacyMtimePath);
+              const mb = typeof mc === "string" ? new TextEncoder().encode(mc) : mc;
+              await fs.writeFile(newMtimePath, mb);
+              await fs.unlink(legacyMtimePath);
+            } catch {
+            }
+          }
+        } else {
+          await fs.unlink(legacyVerPath);
+          result.deleted.push(full);
+          if (await existsPath(fs, legacyMtimePath)) {
+            try {
+              await fs.unlink(legacyMtimePath);
+            } catch {
+            }
+          }
+        }
+      } catch (e) {
+        result.failed.push(full);
+        continue;
+      }
+      for (const rep of replicas) {
+        for (const rp of [legacyVerPath, legacyMtimePath]) {
+          try {
+            await rep.unlink(rp);
+            result.remoteDeleted.push(rp);
+          } catch {
+          }
+        }
+      }
+    }
+  }
+  return result;
+}
+
 // src/config-repo.ts
 var log2 = (0, import_localstorage_logger2.createLogger)("zen-fs-config:config-repo");
 var META_DIR = "/.meta";
@@ -1576,6 +1724,42 @@ var ConfigRepo = class {
     }
     return result;
   }
+  /**
+   * Migrate legacy `.x.version` sidecars (old dotfile naming) to the new
+   * `<name>.version` naming. Renames local sidecars (preserving content/history)
+   * and deletes the residual legacy copy from every replica backend so sync
+   * does not pull it back. Best-effort: failures are logged, never thrown.
+   *
+   * Runs once at startup (see createConfigRepo). Safe to call again.
+   */
+  async migrateLegacyVersionSidecars() {
+    this.assertNotDisposed();
+    const replicas = [...this.replicaBackends.values()].map((r) => ({
+      unlink: (p) => r.syncable.unlink(p)
+    }));
+    const result = await migrateVersionSidecars(this.cachedFS, { replicas });
+    if (result.renamed.length > 0) {
+      log2.log(
+        `[ConfigRepo] migrated ${result.renamed.length} legacy version sidecar(s) to new naming`,
+        result.renamed
+      );
+    }
+    if (result.deleted.length > 0) {
+      log2.log(
+        `[ConfigRepo] removed ${result.deleted.length} orphaned legacy version sidecar(s)`,
+        result.deleted
+      );
+    }
+    if (result.remoteDeleted.length > 0) {
+      log2.log(
+        `[ConfigRepo] removed ${result.remoteDeleted.length} remote residual legacy version sidecar(s)`
+      );
+    }
+    if (result.failed.length > 0) {
+      log2.warn(`[ConfigRepo] failed to migrate ${result.failed.length} legacy version sidecar(s):`, result.failed);
+    }
+    return result;
+  }
   /**
    * Perform a full sync + dedup cycle without the watch snapshot cache.
    * Used by createConfigRepo to pull remote-only files (like duplicate
@@ -1981,7 +2165,9 @@ var ConfigRepo = class {
       try {
         const entries = await this.cachedFS.readdir(current);
         const statResults = await Promise.all(
-          entries.filter((entry) => !entry.startsWith(".")).map(async (entry) => {
+          entries.filter(
+            (entry) => !entry.startsWith(".") && !entry.endsWith(".version") && !entry.endsWith(".mtime")
+          ).map(async (entry) => {
             const fullPath = current === "/" ? `/${entry}` : `${current}/${entry}`;
             try {
               const stat = await this.cachedFS.stat(fullPath);
@@ -2747,6 +2933,16 @@ async function createConfigRepo(appId, options = {}) {
     cacheOptions
   );
   await repo.setupSync(allBackends, LOCAL_IDB_BACKEND_ID, options.syncPollIntervalMs);
+  if (options.migrateVersionSidecars !== false) {
+    try {
+      const mig = await repo.migrateLegacyVersionSidecars();
+      if (mig.renamed.length === 0 && mig.deleted.length === 0 && mig.remoteDeleted.length === 0) {
+        log2.log("[createConfigRepo] no legacy version sidecars to migrate");
+      }
+    } catch (err) {
+      log2.warn(`[createConfigRepo] version sidecar migration failed:`, err?.message ?? err);
+    }
+  }
   await repo.load();
   if (repo.replicaCount > 0) {
     log2.log("[createConfigRepo] Starting background initial sync + dedup...");
@@ -2882,10 +3078,12 @@ init_backend_registry();
   incrementVersion,
   isBrowserEnv,
   isMtimeSidecar,
+  legacyVersionPathFor,
   listBackendMetadata,
   listBackends,
   localPrimaryType,
   mergeAccountFields,
+  migrateVersionSidecars,
   purgeMtimeSidecars,
   readVersion,
   registerBackend,

package/dist/index.mjs

@@ -401,9 +401,30 @@ function versionPathFor(configFilePath) {
   if (fileName.endsWith(".version")) {
     return null;
   }
-  const versionFileName = fileName.startsWith(".") ? `${fileName}.version` : `.${fileName}.version`;
+  const versionFileName = `${fileName}.version`;
   return dir ? `${dir}/${versionFileName}` : versionFileName;
 }
+function legacyVersionPathFor(configFilePath) {
+  const lastSlash = configFilePath.lastIndexOf("/");
+  const dir = lastSlash >= 0 ? configFilePath.slice(0, lastSlash) : "";
+  const fileName = lastSlash >= 0 ? configFilePath.slice(lastSlash + 1) : configFilePath;
+  if (fileName.endsWith(".version")) return null;
+  if (fileName.startsWith(".")) return null;
+  const legacyFileName = `.${fileName}.version`;
+  return dir ? `${dir}/${legacyFileName}` : legacyFileName;
+}
+async function readVersionForConfig(fs, configFilePath) {
+  const newPath = versionPathFor(configFilePath);
+  if (newPath) {
+    const v = await readVersion(fs, newPath);
+    if (v) return v;
+  }
+  const legacyPath = legacyVersionPathFor(configFilePath);
+  if (legacyPath) {
+    return readVersion(fs, legacyPath);
+  }
+  return null;
+}
 function sha256PureJS(data) {
   const K = new Uint32Array([
     1116352408,
@@ -567,7 +588,7 @@ async function writeVersion(fs, versionFilePath, meta) {
 }
 async function incrementVersion(fs, configFilePath, newContent, author) {
   const vPath = versionPathFor(configFilePath);
-  const prev = vPath ? await readVersion(fs, vPath) : null;
+  const prev = vPath ? await readVersionForConfig(fs, configFilePath) : null;
   const hash = await sha256(newContent);
   if (prev && prev.hash === hash) {
     return prev;
@@ -582,7 +603,7 @@ async function incrementVersion(fs, configFilePath, newContent, author) {
 async function verifyOrRepairVersion(fs, configFilePath, author) {
   const vPath = versionPathFor(configFilePath);
   if (!vPath) return null;
-  const existing = await readVersion(fs, vPath);
+  const existing = await readVersionForConfig(fs, configFilePath);
   if (!existing) return null;
   try {
     const content = await fs.readFile(configFilePath);
@@ -667,6 +688,131 @@ async function purgeMtimeSidecars(fs, options = {}) {
   return result;
 }
 
+// src/version-migration.ts
+var S_IFDIR2 = 16384;
+function isDir(stat) {
+  return typeof stat.mode === "number" && (stat.mode & S_IFDIR2) === S_IFDIR2;
+}
+function joinPath2(dir, entry) {
+  if (dir === "/" || dir === "") return `/${entry}`;
+  return `${dir.replace(/\/+$/, "")}/${entry}`;
+}
+async function existsPath(fs, p) {
+  try {
+    await fs.stat(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function configNameFromLegacy(entry) {
+  const noMtime = entry.endsWith(".version.mtime") ? entry.slice(0, -".version.mtime".length) : entry.slice(0, -".version".length);
+  return noMtime.slice(1);
+}
+async function resolveTarget(fs, dir, entry) {
+  const configName = configNameFromLegacy(entry);
+  const configPath = joinPath2(dir, configName);
+  const dotConfigPath = joinPath2(dir, `.${configName}`);
+  if (await existsPath(fs, dotConfigPath)) {
+    return { action: "skip" };
+  }
+  if (await existsPath(fs, configPath)) {
+    return { action: "rename", newPath: versionPathFor(configPath) ?? `${configName}.version` };
+  }
+  return { action: "delete" };
+}
+async function migrateVersionSidecars(fs, options = {}) {
+  const root = options.root && options.root !== "" ? options.root : "/";
+  const dryRun = options.dryRun ?? false;
+  const replicas = options.replicas ?? [];
+  const result = {
+    renamed: [],
+    deleted: [],
+    remoteDeleted: [],
+    failed: []
+  };
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    let entries;
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const full = joinPath2(dir, entry);
+      let stat;
+      try {
+        stat = await fs.stat(full);
+      } catch {
+        continue;
+      }
+      if (isDir(stat)) {
+        stack.push(full);
+        continue;
+      }
+      const isLegacyVersion = entry.startsWith(".") && (entry.endsWith(".version") || entry.endsWith(".version.mtime"));
+      if (!isLegacyVersion) continue;
+      const legacyVerPath = entry.endsWith(".version.mtime") ? full.slice(0, -".mtime".length) : full;
+      const target = await resolveTarget(fs, dir, entry);
+      if (target.action === "skip") continue;
+      const legacyMtimePath = `${legacyVerPath}.mtime`;
+      const newMtimePath = target.newPath ? `${target.newPath}.mtime` : null;
+      if (dryRun) {
+        if (target.action === "rename") result.renamed.push(full);
+        else result.deleted.push(full);
+        continue;
+      }
+      try {
+        if (target.action === "rename") {
+          if (await existsPath(fs, target.newPath)) {
+            await fs.unlink(legacyVerPath);
+            result.deleted.push(full);
+          } else {
+            const content = await fs.readFile(legacyVerPath);
+            const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content;
+            await fs.writeFile(target.newPath, bytes);
+            await fs.unlink(legacyVerPath);
+            result.renamed.push(full);
+          }
+          if (newMtimePath && await existsPath(fs, legacyMtimePath)) {
+            try {
+              const mc = await fs.readFile(legacyMtimePath);
+              const mb = typeof mc === "string" ? new TextEncoder().encode(mc) : mc;
+              await fs.writeFile(newMtimePath, mb);
+              await fs.unlink(legacyMtimePath);
+            } catch {
+            }
+          }
+        } else {
+          await fs.unlink(legacyVerPath);
+          result.deleted.push(full);
+          if (await existsPath(fs, legacyMtimePath)) {
+            try {
+              await fs.unlink(legacyMtimePath);
+            } catch {
+            }
+          }
+        }
+      } catch (e) {
+        result.failed.push(full);
+        continue;
+      }
+      for (const rep of replicas) {
+        for (const rp of [legacyVerPath, legacyMtimePath]) {
+          try {
+            await rep.unlink(rp);
+            result.remoteDeleted.push(rp);
+          } catch {
+          }
+        }
+      }
+    }
+  }
+  return result;
+}
+
 // src/config-repo.ts
 var log2 = createLogger2("zen-fs-config:config-repo");
 var META_DIR = "/.meta";
@@ -1149,6 +1295,42 @@ var ConfigRepo = class {
     }
     return result;
   }
+  /**
+   * Migrate legacy `.x.version` sidecars (old dotfile naming) to the new
+   * `<name>.version` naming. Renames local sidecars (preserving content/history)
+   * and deletes the residual legacy copy from every replica backend so sync
+   * does not pull it back. Best-effort: failures are logged, never thrown.
+   *
+   * Runs once at startup (see createConfigRepo). Safe to call again.
+   */
+  async migrateLegacyVersionSidecars() {
+    this.assertNotDisposed();
+    const replicas = [...this.replicaBackends.values()].map((r) => ({
+      unlink: (p) => r.syncable.unlink(p)
+    }));
+    const result = await migrateVersionSidecars(this.cachedFS, { replicas });
+    if (result.renamed.length > 0) {
+      log2.log(
+        `[ConfigRepo] migrated ${result.renamed.length} legacy version sidecar(s) to new naming`,
+        result.renamed
+      );
+    }
+    if (result.deleted.length > 0) {
+      log2.log(
+        `[ConfigRepo] removed ${result.deleted.length} orphaned legacy version sidecar(s)`,
+        result.deleted
+      );
+    }
+    if (result.remoteDeleted.length > 0) {
+      log2.log(
+        `[ConfigRepo] removed ${result.remoteDeleted.length} remote residual legacy version sidecar(s)`
+      );
+    }
+    if (result.failed.length > 0) {
+      log2.warn(`[ConfigRepo] failed to migrate ${result.failed.length} legacy version sidecar(s):`, result.failed);
+    }
+    return result;
+  }
   /**
    * Perform a full sync + dedup cycle without the watch snapshot cache.
    * Used by createConfigRepo to pull remote-only files (like duplicate
@@ -1554,7 +1736,9 @@ var ConfigRepo = class {
       try {
         const entries = await this.cachedFS.readdir(current);
         const statResults = await Promise.all(
-          entries.filter((entry) => !entry.startsWith(".")).map(async (entry) => {
+          entries.filter(
+            (entry) => !entry.startsWith(".") && !entry.endsWith(".version") && !entry.endsWith(".mtime")
+          ).map(async (entry) => {
             const fullPath = current === "/" ? `/${entry}` : `${current}/${entry}`;
             try {
               const stat = await this.cachedFS.stat(fullPath);
@@ -2320,6 +2504,16 @@ async function createConfigRepo(appId, options = {}) {
     cacheOptions
   );
   await repo.setupSync(allBackends, LOCAL_IDB_BACKEND_ID, options.syncPollIntervalMs);
+  if (options.migrateVersionSidecars !== false) {
+    try {
+      const mig = await repo.migrateLegacyVersionSidecars();
+      if (mig.renamed.length === 0 && mig.deleted.length === 0 && mig.remoteDeleted.length === 0) {
+        log2.log("[createConfigRepo] no legacy version sidecars to migrate");
+      }
+    } catch (err) {
+      log2.warn(`[createConfigRepo] version sidecar migration failed:`, err?.message ?? err);
+    }
+  }
   await repo.load();
   if (repo.replicaCount > 0) {
     log2.log("[createConfigRepo] Starting background initial sync + dedup...");
@@ -2450,10 +2644,12 @@ export {
   incrementVersion,
   isBrowserEnv,
   isMtimeSidecar,
+  legacyVersionPathFor,
   listBackendMetadata,
   listBackends,
   localPrimaryType,
   mergeAccountFields,
+  migrateVersionSidecars,
   purgeMtimeSidecars,
   readVersion,
   registerBackend,

package/dist/zen-fs-config.js

@@ -5275,7 +5275,7 @@ var ZenFSConfig = (() => {
          * @param path The path to remove from the file system.
          * @param isDir Does the path belong to a directory, or a file?
          */
-        async remove(path, isDir) {
+        async remove(path, isDir2) {
           const env_25 = { stack: [], error: void 0, hasError: false };
           try {
             const tx = __addDisposableResource(env_25, this.transaction(), true);
@@ -5285,7 +5285,7 @@ var ZenFSConfig = (() => {
             const ino = listing[fileName];
             const inode = new Inode(await tx.get(ino) ?? _throw(withErrno("ENOENT")));
             delete listing[fileName];
-            if (!isDir && isDirectory2(inode))
+            if (!isDir2 && isDirectory2(inode))
               throw withErrno("EISDIR");
             await tx.set(parentNode.data, encodeDirListing(listing));
             if (inode.nlink > 1) {
@@ -5311,7 +5311,7 @@ var ZenFSConfig = (() => {
          * @param path The path to remove from the file system.
          * @param isDir Does the path belong to a directory, or a file?
          */
-        removeSync(path, isDir) {
+        removeSync(path, isDir2) {
           const env_26 = { stack: [], error: void 0, hasError: false };
           try {
             const tx = __addDisposableResource(env_26, this.transaction(), false);
@@ -5320,7 +5320,7 @@ var ZenFSConfig = (() => {
               throw withErrno("ENOENT");
             const inode = new Inode(tx.getSync(ino) ?? _throw(withErrno("ENOENT")));
             delete listing[fileName];
-            if (!isDir && isDirectory2(inode))
+            if (!isDir2 && isDirectory2(inode))
               throw withErrno("EISDIR");
             tx.setSync(parentNode.data, encodeDirListing(listing));
             if (inode.nlink > 1) {
@@ -19499,12 +19499,12 @@ var ZenFSConfig = (() => {
           const inode = this.index.get(path);
           if (!inode)
             throw withErrno("ENOENT");
-          const isDir = (inode.mode & S_IFMT) == S_IFDIR;
-          if (!isDir && !isUnlink)
+          const isDir2 = (inode.mode & S_IFMT) == S_IFDIR;
+          if (!isDir2 && !isUnlink)
             throw withErrno("ENOTDIR");
-          if (isDir && isUnlink)
+          if (isDir2 && isUnlink)
             throw withErrno("EISDIR");
-          if (!isDir)
+          if (!isDir2)
             this.index.delete(path);
         }
         async unlink(path) {
@@ -23805,17 +23805,17 @@ var ZenFSConfig = (() => {
           const inode = this.index.get(path);
           if (!inode)
             throw withErrno("ENOENT");
-          const isDir = (inode.mode & constants_exports.S_IFMT) == constants_exports.S_IFDIR;
+          const isDir2 = (inode.mode & constants_exports.S_IFMT) == constants_exports.S_IFDIR;
           let handle;
           try {
-            handle = await this.get(isDir ? "directory" : "file", path);
+            handle = await this.get(isDir2 ? "directory" : "file", path);
           } catch {
             const parent = await this.get("directory", dirname(path));
-            handle = await parent[isDir ? "getDirectoryHandle" : "getFileHandle"](basename(path), { create: true }).catch((ex) => _throw(convertException(ex, path)));
+            handle = await parent[isDir2 ? "getDirectoryHandle" : "getFileHandle"](basename(path), { create: true }).catch((ex) => _throw(convertException(ex, path)));
             if (!this.disableHandleCache)
               this._handles.set(path, handle);
           }
-          if (isDir)
+          if (isDir2)
             return;
           if (isKind(handle, "directory")) {
             log_exports.crit(withErrno("EIO", "Mismatch in entry kind on write"));
@@ -25112,10 +25112,12 @@ var ZenFSConfig = (() => {
     incrementVersion: () => incrementVersion,
     isBrowserEnv: () => isBrowserEnv,
     isMtimeSidecar: () => isMtimeSidecar,
+    legacyVersionPathFor: () => legacyVersionPathFor,
     listBackendMetadata: () => listBackendMetadata,
     listBackends: () => listBackends,
     localPrimaryType: () => localPrimaryType,
     mergeAccountFields: () => mergeAccountFields,
+    migrateVersionSidecars: () => migrateVersionSidecars,
     purgeMtimeSidecars: () => purgeMtimeSidecars,
     readVersion: () => readVersion,
     registerBackend: () => registerBackend,
@@ -26705,9 +26707,30 @@ var ZenFSConfig = (() => {
     if (fileName.endsWith(".version")) {
       return null;
     }
-    const versionFileName = fileName.startsWith(".") ? `${fileName}.version` : `.${fileName}.version`;
+    const versionFileName = `${fileName}.version`;
     return dir ? `${dir}/${versionFileName}` : versionFileName;
   }
+  function legacyVersionPathFor(configFilePath) {
+    const lastSlash = configFilePath.lastIndexOf("/");
+    const dir = lastSlash >= 0 ? configFilePath.slice(0, lastSlash) : "";
+    const fileName = lastSlash >= 0 ? configFilePath.slice(lastSlash + 1) : configFilePath;
+    if (fileName.endsWith(".version")) return null;
+    if (fileName.startsWith(".")) return null;
+    const legacyFileName = `.${fileName}.version`;
+    return dir ? `${dir}/${legacyFileName}` : legacyFileName;
+  }
+  async function readVersionForConfig(fs, configFilePath) {
+    const newPath = versionPathFor(configFilePath);
+    if (newPath) {
+      const v = await readVersion(fs, newPath);
+      if (v) return v;
+    }
+    const legacyPath = legacyVersionPathFor(configFilePath);
+    if (legacyPath) {
+      return readVersion(fs, legacyPath);
+    }
+    return null;
+  }
   function sha256PureJS(data) {
     const K = new Uint32Array([
       1116352408,
@@ -26871,7 +26894,7 @@ var ZenFSConfig = (() => {
   }
   async function incrementVersion(fs, configFilePath, newContent, author) {
     const vPath = versionPathFor(configFilePath);
-    const prev = vPath ? await readVersion(fs, vPath) : null;
+    const prev = vPath ? await readVersionForConfig(fs, configFilePath) : null;
     const hash = await sha256(newContent);
     if (prev && prev.hash === hash) {
       return prev;
@@ -26886,7 +26909,7 @@ var ZenFSConfig = (() => {
   async function verifyOrRepairVersion(fs, configFilePath, author) {
     const vPath = versionPathFor(configFilePath);
     if (!vPath) return null;
-    const existing = await readVersion(fs, vPath);
+    const existing = await readVersionForConfig(fs, configFilePath);
     if (!existing) return null;
     try {
       const content = await fs.readFile(configFilePath);
@@ -26971,6 +26994,131 @@ var ZenFSConfig = (() => {
     return result;
   }
 
+  // src/version-migration.ts
+  var S_IFDIR3 = 16384;
+  function isDir(stat5) {
+    return typeof stat5.mode === "number" && (stat5.mode & S_IFDIR3) === S_IFDIR3;
+  }
+  function joinPath2(dir, entry) {
+    if (dir === "/" || dir === "") return `/${entry}`;
+    return `${dir.replace(/\/+$/, "")}/${entry}`;
+  }
+  async function existsPath(fs, p) {
+    try {
+      await fs.stat(p);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  function configNameFromLegacy(entry) {
+    const noMtime = entry.endsWith(".version.mtime") ? entry.slice(0, -".version.mtime".length) : entry.slice(0, -".version".length);
+    return noMtime.slice(1);
+  }
+  async function resolveTarget(fs, dir, entry) {
+    const configName = configNameFromLegacy(entry);
+    const configPath = joinPath2(dir, configName);
+    const dotConfigPath = joinPath2(dir, `.${configName}`);
+    if (await existsPath(fs, dotConfigPath)) {
+      return { action: "skip" };
+    }
+    if (await existsPath(fs, configPath)) {
+      return { action: "rename", newPath: versionPathFor(configPath) ?? `${configName}.version` };
+    }
+    return { action: "delete" };
+  }
+  async function migrateVersionSidecars(fs, options = {}) {
+    const root = options.root && options.root !== "" ? options.root : "/";
+    const dryRun = options.dryRun ?? false;
+    const replicas = options.replicas ?? [];
+    const result = {
+      renamed: [],
+      deleted: [],
+      remoteDeleted: [],
+      failed: []
+    };
+    const stack = [root];
+    while (stack.length > 0) {
+      const dir = stack.pop();
+      let entries2;
+      try {
+        entries2 = await fs.readdir(dir);
+      } catch {
+        continue;
+      }
+      for (const entry of entries2) {
+        const full = joinPath2(dir, entry);
+        let stat5;
+        try {
+          stat5 = await fs.stat(full);
+        } catch {
+          continue;
+        }
+        if (isDir(stat5)) {
+          stack.push(full);
+          continue;
+        }
+        const isLegacyVersion = entry.startsWith(".") && (entry.endsWith(".version") || entry.endsWith(".version.mtime"));
+        if (!isLegacyVersion) continue;
+        const legacyVerPath = entry.endsWith(".version.mtime") ? full.slice(0, -".mtime".length) : full;
+        const target = await resolveTarget(fs, dir, entry);
+        if (target.action === "skip") continue;
+        const legacyMtimePath = `${legacyVerPath}.mtime`;
+        const newMtimePath = target.newPath ? `${target.newPath}.mtime` : null;
+        if (dryRun) {
+          if (target.action === "rename") result.renamed.push(full);
+          else result.deleted.push(full);
+          continue;
+        }
+        try {
+          if (target.action === "rename") {
+            if (await existsPath(fs, target.newPath)) {
+              await fs.unlink(legacyVerPath);
+              result.deleted.push(full);
+            } else {
+              const content = await fs.readFile(legacyVerPath);
+              const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content;
+              await fs.writeFile(target.newPath, bytes);
+              await fs.unlink(legacyVerPath);
+              result.renamed.push(full);
+            }
+            if (newMtimePath && await existsPath(fs, legacyMtimePath)) {
+              try {
+                const mc = await fs.readFile(legacyMtimePath);
+                const mb = typeof mc === "string" ? new TextEncoder().encode(mc) : mc;
+                await fs.writeFile(newMtimePath, mb);
+                await fs.unlink(legacyMtimePath);
+              } catch {
+              }
+            }
+          } else {
+            await fs.unlink(legacyVerPath);
+            result.deleted.push(full);
+            if (await existsPath(fs, legacyMtimePath)) {
+              try {
+                await fs.unlink(legacyMtimePath);
+              } catch {
+              }
+            }
+          }
+        } catch (e) {
+          result.failed.push(full);
+          continue;
+        }
+        for (const rep of replicas) {
+          for (const rp of [legacyVerPath, legacyMtimePath]) {
+            try {
+              await rep.unlink(rp);
+              result.remoteDeleted.push(rp);
+            } catch {
+            }
+          }
+        }
+      }
+    }
+    return result;
+  }
+
   // src/config-repo.ts
   var log6 = createLogger2("zen-fs-config:config-repo");
   var META_DIR = "/.meta";
@@ -27453,6 +27601,42 @@ var ZenFSConfig = (() => {
       }
       return result;
     }
+    /**
+     * Migrate legacy `.x.version` sidecars (old dotfile naming) to the new
+     * `<name>.version` naming. Renames local sidecars (preserving content/history)
+     * and deletes the residual legacy copy from every replica backend so sync
+     * does not pull it back. Best-effort: failures are logged, never thrown.
+     *
+     * Runs once at startup (see createConfigRepo). Safe to call again.
+     */
+    async migrateLegacyVersionSidecars() {
+      this.assertNotDisposed();
+      const replicas = [...this.replicaBackends.values()].map((r) => ({
+        unlink: (p) => r.syncable.unlink(p)
+      }));
+      const result = await migrateVersionSidecars(this.cachedFS, { replicas });
+      if (result.renamed.length > 0) {
+        log6.log(
+          `[ConfigRepo] migrated ${result.renamed.length} legacy version sidecar(s) to new naming`,
+          result.renamed
+        );
+      }
+      if (result.deleted.length > 0) {
+        log6.log(
+          `[ConfigRepo] removed ${result.deleted.length} orphaned legacy version sidecar(s)`,
+          result.deleted
+        );
+      }
+      if (result.remoteDeleted.length > 0) {
+        log6.log(
+          `[ConfigRepo] removed ${result.remoteDeleted.length} remote residual legacy version sidecar(s)`
+        );
+      }
+      if (result.failed.length > 0) {
+        log6.warn(`[ConfigRepo] failed to migrate ${result.failed.length} legacy version sidecar(s):`, result.failed);
+      }
+      return result;
+    }
     /**
      * Perform a full sync + dedup cycle without the watch snapshot cache.
      * Used by createConfigRepo to pull remote-only files (like duplicate
@@ -27858,7 +28042,9 @@ var ZenFSConfig = (() => {
         try {
           const entries2 = await this.cachedFS.readdir(current);
           const statResults = await Promise.all(
-            entries2.filter((entry) => !entry.startsWith(".")).map(async (entry) => {
+            entries2.filter(
+              (entry) => !entry.startsWith(".") && !entry.endsWith(".version") && !entry.endsWith(".mtime")
+            ).map(async (entry) => {
               const fullPath = current === "/" ? `/${entry}` : `${current}/${entry}`;
               try {
                 const stat5 = await this.cachedFS.stat(fullPath);
@@ -28624,6 +28810,16 @@ var ZenFSConfig = (() => {
       cacheOptions
     );
     await repo.setupSync(allBackends, LOCAL_IDB_BACKEND_ID, options.syncPollIntervalMs);
+    if (options.migrateVersionSidecars !== false) {
+      try {
+        const mig = await repo.migrateLegacyVersionSidecars();
+        if (mig.renamed.length === 0 && mig.deleted.length === 0 && mig.remoteDeleted.length === 0) {
+          log6.log("[createConfigRepo] no legacy version sidecars to migrate");
+        }
+      } catch (err2) {
+        log6.warn(`[createConfigRepo] version sidecar migration failed:`, err2?.message ?? err2);
+      }
+    }
     await repo.load();
     if (repo.replicaCount > 0) {
       log6.log("[createConfigRepo] Starting background initial sync + dedup...");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zen-fs-config",
-  "version": "0.5.32",
+  "version": "0.5.33",
   "description": "Distributed config management library built on ZenFS, zen-fs-cache, and zen-fs-sync",
   "main": "dist/index.js",
   "module": "dist/index.mjs",