zen-fs-config 0.5.31 → 0.5.33

package/dist/index.d.mts

@@ -4,6 +4,65 @@ import * as node_fs from 'node:fs';
 import * as node_path from 'node:path';
 import { SyncMapStore, SyncMapTransaction } from '@zenfs/core';
 
+/**
+ * zen-fs-config — mtime sidecar cleanup
+ *
+ * Backends that cannot store a precise mtime natively (RemoteStorage, Gitee,
+ * …) persist it in a `.mtime` sidecar next to each file
+ * (`data.json` → `.data.json.mtime`). A sidecar is backend-internal metadata:
+ * it belongs to the backend that produced it and must never be handed out by
+ * `readdir()`/`createSnapshot()`.
+ *
+ * Older builds did leak them, and once a sidecar lands in the local primary
+ * (IndexedDB on browser, Folder on Node) it stays there forever — zen-fs-sync
+ * deliberately skips `.mtime` paths on both sides, so nothing ever removes
+ * them, and every walk logs:
+ *
+ *   [zen-fs-sync] mtime sidecar leaked from backend "local-idb" …
+ *
+ * This module walks the local primary and deletes those leaked files. It never
+ * touches replica (remote) backends: their sidecars are live metadata, and
+ * deleting them would cost network calls and lose mtime precision.
+ */
+/** Minimal async FS surface needed for the purge. */
+interface PurgeableFS {
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<{
+        mode?: number;
+    }>;
+    unlink(path: string): Promise<void>;
+}
+interface PurgeMtimeOptions {
+    /** Root to scan. Default: `/` (the whole local primary). */
+    root?: string;
+    /** Report what would be deleted without unlinking anything. */
+    dryRun?: boolean;
+}
+interface MtimePurgeResult {
+    /** Files visited during the walk (sidecars included). */
+    scanned: number;
+    /** Sidecars deleted — or, in dryRun, that would be deleted. */
+    removed: string[];
+    /** Sidecars that could not be deleted (unlink failed). */
+    failed: string[];
+}
+/**
+ * True when a file name is an mtime sidecar.
+ *
+ * Uses the same rule as zen-fs-sync's walker (`path.endsWith('.mtime')`), so
+ * the pathological nested form (`.foo.mtime.mtime`) is covered too.
+ */
+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 as `<name>.mtime` files.
+ * Unreadable entries are skipped; failures on individual files are collected
+ * in `failed` instead of aborting the walk.
+ */
+declare function purgeMtimeSidecars(fs: PurgeableFS, options?: PurgeMtimeOptions): Promise<MtimePurgeResult>;
+
 /** A single backend in the topology. */
 interface BackendDescriptor {
     /** Unique identifier within this config repo (e.g., "local-idb"). */
@@ -159,6 +218,29 @@ interface ConfigRepoOptions {
      * Default: 1800000 (30 minutes).
      */
     syncPollIntervalMs?: number;
+    /**
+     * Delete leaked `.mtime` sidecars from the local primary on startup.
+     *
+     * Backends that keep a precise mtime out-of-band (RemoteStorage, Gitee…)
+     * write a `.mtime` file next to each data file. Older builds copied those
+     * backend-internal files into the local primary, where sync ignores them —
+     * so they linger forever and warn on every walk.
+     *
+     * 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';
@@ -340,6 +422,17 @@ interface IConfigRepo {
      * Called automatically by createConfigRepo() after setupSync().
      */
     syncMetaToReplicas(): Promise<void>;
+    /**
+     * Delete leaked `.mtime` sidecars from the local primary backend.
+     *
+     * Runs automatically on `createConfigRepo()` unless
+     * `options.purgeMtimeSidecars === false`. Call it manually to clean a
+     * long-lived store, or with `{ dryRun: true }` to only list them.
+     */
+    purgeMtimeSidecars(options?: {
+        root?: string;
+        dryRun?: boolean;
+    }): Promise<MtimePurgeResult>;
     /**
      * Create a data-sync group for this app.
      * Each backend can optionally reference a config-sync backend's account
@@ -504,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
  *
@@ -593,6 +751,31 @@ declare class ConfigRepo implements IConfigRepo {
     private safeExists;
     /** Public wrapper for processTombstones — used by createConfigRepo. */
     processTombstonesPublic(): Promise<void>;
+    /**
+     * Delete leaked `.mtime` sidecar files from the local primary backend
+     * (IndexedDB on browser, Folder on Node).
+     *
+     * Sidecars are produced by backends that keep a precise mtime out-of-band
+     * (RemoteStorage, Gitee…). Once one is copied into the local primary it is
+     * never removed: zen-fs-sync skips `.mtime` paths on both sides, so it is
+     * invisible to sync, and every walk warns about the leak.
+     *
+     * Only the local primary is scanned — replica sidecars are live metadata of
+     * the backend that owns them and must be left alone.
+     *
+     * @param options.root Scan only this subtree (default `/`).
+     * @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
@@ -779,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.
@@ -826,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 SyncGroupType, type TombstoneMeta, type VersionMeta, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, 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

@@ -4,6 +4,65 @@ import * as node_fs from 'node:fs';
 import * as node_path from 'node:path';
 import { SyncMapStore, SyncMapTransaction } from '@zenfs/core';
 
+/**
+ * zen-fs-config — mtime sidecar cleanup
+ *
+ * Backends that cannot store a precise mtime natively (RemoteStorage, Gitee,
+ * …) persist it in a `.mtime` sidecar next to each file
+ * (`data.json` → `.data.json.mtime`). A sidecar is backend-internal metadata:
+ * it belongs to the backend that produced it and must never be handed out by
+ * `readdir()`/`createSnapshot()`.
+ *
+ * Older builds did leak them, and once a sidecar lands in the local primary
+ * (IndexedDB on browser, Folder on Node) it stays there forever — zen-fs-sync
+ * deliberately skips `.mtime` paths on both sides, so nothing ever removes
+ * them, and every walk logs:
+ *
+ *   [zen-fs-sync] mtime sidecar leaked from backend "local-idb" …
+ *
+ * This module walks the local primary and deletes those leaked files. It never
+ * touches replica (remote) backends: their sidecars are live metadata, and
+ * deleting them would cost network calls and lose mtime precision.
+ */
+/** Minimal async FS surface needed for the purge. */
+interface PurgeableFS {
+    readdir(path: string): Promise<string[]>;
+    stat(path: string): Promise<{
+        mode?: number;
+    }>;
+    unlink(path: string): Promise<void>;
+}
+interface PurgeMtimeOptions {
+    /** Root to scan. Default: `/` (the whole local primary). */
+    root?: string;
+    /** Report what would be deleted without unlinking anything. */
+    dryRun?: boolean;
+}
+interface MtimePurgeResult {
+    /** Files visited during the walk (sidecars included). */
+    scanned: number;
+    /** Sidecars deleted — or, in dryRun, that would be deleted. */
+    removed: string[];
+    /** Sidecars that could not be deleted (unlink failed). */
+    failed: string[];
+}
+/**
+ * True when a file name is an mtime sidecar.
+ *
+ * Uses the same rule as zen-fs-sync's walker (`path.endsWith('.mtime')`), so
+ * the pathological nested form (`.foo.mtime.mtime`) is covered too.
+ */
+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 as `<name>.mtime` files.
+ * Unreadable entries are skipped; failures on individual files are collected
+ * in `failed` instead of aborting the walk.
+ */
+declare function purgeMtimeSidecars(fs: PurgeableFS, options?: PurgeMtimeOptions): Promise<MtimePurgeResult>;
+
 /** A single backend in the topology. */
 interface BackendDescriptor {
     /** Unique identifier within this config repo (e.g., "local-idb"). */
@@ -159,6 +218,29 @@ interface ConfigRepoOptions {
      * Default: 1800000 (30 minutes).
      */
     syncPollIntervalMs?: number;
+    /**
+     * Delete leaked `.mtime` sidecars from the local primary on startup.
+     *
+     * Backends that keep a precise mtime out-of-band (RemoteStorage, Gitee…)
+     * write a `.mtime` file next to each data file. Older builds copied those
+     * backend-internal files into the local primary, where sync ignores them —
+     * so they linger forever and warn on every walk.
+     *
+     * 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';
@@ -340,6 +422,17 @@ interface IConfigRepo {
      * Called automatically by createConfigRepo() after setupSync().
      */
     syncMetaToReplicas(): Promise<void>;
+    /**
+     * Delete leaked `.mtime` sidecars from the local primary backend.
+     *
+     * Runs automatically on `createConfigRepo()` unless
+     * `options.purgeMtimeSidecars === false`. Call it manually to clean a
+     * long-lived store, or with `{ dryRun: true }` to only list them.
+     */
+    purgeMtimeSidecars(options?: {
+        root?: string;
+        dryRun?: boolean;
+    }): Promise<MtimePurgeResult>;
     /**
      * Create a data-sync group for this app.
      * Each backend can optionally reference a config-sync backend's account
@@ -504,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
  *
@@ -593,6 +751,31 @@ declare class ConfigRepo implements IConfigRepo {
     private safeExists;
     /** Public wrapper for processTombstones — used by createConfigRepo. */
     processTombstonesPublic(): Promise<void>;
+    /**
+     * Delete leaked `.mtime` sidecar files from the local primary backend
+     * (IndexedDB on browser, Folder on Node).
+     *
+     * Sidecars are produced by backends that keep a precise mtime out-of-band
+     * (RemoteStorage, Gitee…). Once one is copied into the local primary it is
+     * never removed: zen-fs-sync skips `.mtime` paths on both sides, so it is
+     * invisible to sync, and every walk warns about the leak.
+     *
+     * Only the local primary is scanned — replica sidecars are live metadata of
+     * the backend that owns them and must be left alone.
+     *
+     * @param options.root Scan only this subtree (default `/`).
+     * @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
@@ -779,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.
@@ -826,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 SyncGroupType, type TombstoneMeta, type VersionMeta, configKeyToFilePath, connect, createBackend, createConfigRepo, createSerializerChain, getAccountFields, getBackendMetadata, getExtension, hasBackend, incrementVersion, isBrowserEnv, listBackendMetadata, listBackends, localPrimaryType, mergeAccountFields, 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 };