zen-fs-config 0.3.24 → 0.3.27

package/dist/index.d.mts

@@ -29,6 +29,17 @@ interface VersionMeta {
     /** Timestamp when the version was created. */
     timestamp: number;
 }
+/** Content of a tombstone file in `.meta/.deleted/`. */
+interface TombstoneMeta {
+    /** The deleted file path. */
+    path: string;
+    /** Timestamp of deletion. */
+    deletedAt: number;
+    /** Backend ID that initiated the deletion. */
+    deletedBy: string;
+    /** Backend IDs that have confirmed the deletion (synced). */
+    confirmedBy: string[];
+}
 /** Content of a conflict archive file in `.meta/.conflicts/`. */
 interface ConflictArchive {
     /** The config file path that conflicted. */
@@ -146,6 +157,12 @@ interface IConfigRepo {
     getBackends(): Promise<BackendsMeta | null>;
     /** Write .meta/backends.json. */
     updateBackends(meta: BackendsMeta): Promise<void>;
+    /**
+     * Delete a file and record a tombstone for cross-backend sync.
+     * The tombstone ensures the deletion propagates to all backends
+     * instead of being treated as a "missing file" that gets re-created.
+     */
+    deleteFile(path: string): Promise<void>;
     /**
      * Sync .meta/ files (backends.json) to all replica backends.
      * Called automatically by createConfigRepo() after setupSync().
@@ -191,21 +208,54 @@ declare function configKeyToFilePath(configPath: string): string;
 declare function getExtension(path: string): string;
 
 /**
- * zen-fs-config — ConfigRepo Implementation
+ * zen-fs-config — Backend Registry
  *
- * Core implementation of IConfigRepo and the createConfigRepo factory.
+ * A pluggable registry that maps backend type names to factory functions.
+ *
+ * Core principle: zen-fs-config does NOT hardcode every ZenFS backend.
+ * Instead, it provides:
+ *   1. A simple registry API (registerBackend, createBackend, etc.)
+ *   2. One built-in backend (InMemory) — zero extra dependencies
+ *   3. A wrapZenFSFileSystem() helper to adapt any ZenFS FileSystem
+ *      implementation into the BackendInstance interface
+ *
+ * Applications (like zen-fs-config-admin) register whatever backends
+ * they need at startup.  Adding a new backend never requires changing
+ * zen-fs-config itself.
  */
 
-interface MinimalAsyncFS {
+type BackendFactory = (options: Record<string, unknown>) => Promise<BackendInstance>;
+/**
+ * The minimal interface a backend instance must satisfy.
+ * Matches zen-fs-cache's CacheableFileSystem requirements.
+ */
+interface BackendInstance {
     readFile(path: string, ...args: any[]): Promise<any>;
-    writeFile(path: string, data: any, options?: any): Promise<void>;
+    writeFile(path: string, data: string | Uint8Array | ArrayBuffer, options?: any): Promise<void>;
     readdir(path: string): Promise<string[]>;
-    stat(path: string): Promise<any>;
+    stat(path: string, ...args: any[]): Promise<any>;
     exists(path: string): Promise<boolean>;
     mkdir(path: string, options?: any): Promise<any>;
     unlink(path: string): Promise<void>;
-    rmdir?(path: string): Promise<void>;
+    rmdir(path: string): Promise<void>;
     rename?(oldPath: string, newPath: string): Promise<void>;
+    readFileMeta?(path: string, opts?: any): Promise<any>;
+    getRevision?(path: string): Promise<string | number | undefined>;
+}
+declare function registerBackend(type: string, factory: BackendFactory): void;
+declare function unregisterBackend(type: string): boolean;
+declare function createBackend(descriptor: Pick<BackendDescriptor, 'type' | 'options'>): Promise<BackendInstance>;
+declare function hasBackend(type: string): boolean;
+declare function listBackends(): string[];
+declare function wrapZenFSFileSystem(config: any): Promise<BackendInstance>;
+
+/**
+ * zen-fs-config — ConfigRepo Implementation
+ *
+ * Core implementation of IConfigRepo and the createConfigRepo factory.
+ */
+
+interface MinimalAsyncFS extends BackendInstance {
 }
 declare class ConfigRepo implements IConfigRepo {
     readonly appId: string;
@@ -222,7 +272,8 @@ declare class ConfigRepo implements IConfigRepo {
     private onConflictCallback?;
     private disposed;
     private configCache;
-    constructor(appId: string, nodeId: string, cachedFS: MinimalAsyncFS, serializer: PathAwareSerializer, onConflict?: (conflict: ConflictInfo) => Promise<unknown | null>);
+    private readonly primaryBackendId;
+    constructor(appId: string, nodeId: string, primaryBackendId: string, cachedFS: MinimalAsyncFS, serializer: PathAwareSerializer, onConflict?: (conflict: ConflictInfo) => Promise<unknown | null>);
     /** Full path to this node's directory on the primary backend. */
     get nodePath(): string;
     load(rawConfig?: string): Promise<void>;
@@ -235,6 +286,28 @@ declare class ConfigRepo implements IConfigRepo {
     }): Promise<SyncResult>;
     peekNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
     flush(): Promise<SyncResult[]>;
+    /**
+     * Delete a file and write a tombstone so the deletion propagates
+     * to all backends instead of being treated as "missing file → re-create".
+     */
+    deleteFile(path: string): Promise<void>;
+    /**
+     * Read all tombstones from the primary backend.
+     */
+    private readTombstones;
+    /**
+     * Before sync: for each tombstone, delete the actual file on all replicas.
+     * This prevents bi-directional sync from copying the file back.
+     */
+    private processTombstones;
+    /**
+     * After sync: mark each tombstone as confirmed by all replica backends.
+     */
+    private updateTombstoneConfirmations;
+    /**
+     * GC: remove tombstones where all backends in backends.json have confirmed.
+     */
+    private gcTombstones;
     /**
      * Sync .meta/ files (backends.json) to all replica backends.
      *
@@ -264,48 +337,6 @@ declare class ConfigRepo implements IConfigRepo {
 }
 declare function createConfigRepo(appId: string, options: ConfigRepoOptions): Promise<IConfigRepo>;
 
-/**
- * zen-fs-config — Backend Registry
- *
- * A pluggable registry that maps backend type names to factory functions.
- *
- * Core principle: zen-fs-config does NOT hardcode every ZenFS backend.
- * Instead, it provides:
- *   1. A simple registry API (registerBackend, createBackend, etc.)
- *   2. One built-in backend (InMemory) — zero extra dependencies
- *   3. A wrapZenFSFileSystem() helper to adapt any ZenFS FileSystem
- *      implementation into the BackendInstance interface
- *
- * Applications (like zen-fs-config-admin) register whatever backends
- * they need at startup.  Adding a new backend never requires changing
- * zen-fs-config itself.
- */
-
-type BackendFactory = (options: Record<string, unknown>) => Promise<BackendInstance>;
-/**
- * The minimal interface a backend instance must satisfy.
- * Matches zen-fs-cache's CacheableFileSystem requirements.
- */
-interface BackendInstance {
-    readFile(path: string, ...args: any[]): Promise<any>;
-    writeFile(path: string, data: string | Uint8Array | ArrayBuffer, options?: any): Promise<void>;
-    readdir(path: string): Promise<string[]>;
-    stat(path: string, ...args: any[]): Promise<any>;
-    exists(path: string): Promise<boolean>;
-    mkdir(path: string, options?: any): Promise<any>;
-    unlink(path: string): Promise<void>;
-    rmdir(path: string): Promise<void>;
-    rename?(oldPath: string, newPath: string): Promise<void>;
-    readFileMeta?(path: string, opts?: any): Promise<any>;
-    getRevision?(path: string): Promise<string | number | undefined>;
-}
-declare function registerBackend(type: string, factory: BackendFactory): void;
-declare function unregisterBackend(type: string): boolean;
-declare function createBackend(descriptor: Pick<BackendDescriptor, 'type' | 'options'>): Promise<BackendInstance>;
-declare function hasBackend(type: string): boolean;
-declare function listBackends(): string[];
-declare function wrapZenFSFileSystem(config: any): Promise<BackendInstance>;
-
 /**
  * zen-fs-config — Sidecar Version File Management
  *
@@ -348,4 +379,4 @@ declare function incrementVersion(fs: SyncableFS, configFilePath: string, newCon
  */
 declare function verifyOrRepairVersion(fs: SyncableFS, configFilePath: string, author: string): Promise<VersionMeta | null>;
 
-export { type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type IConfigRepo, type VersionMeta, configKeyToFilePath, createBackend, createConfigRepo, createSerializerChain, getExtension, hasBackend, incrementVersion, listBackends, readVersion, registerBackend, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };
+export { type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type IConfigRepo, type TombstoneMeta, type VersionMeta, configKeyToFilePath, createBackend, createConfigRepo, createSerializerChain, getExtension, hasBackend, incrementVersion, listBackends, readVersion, registerBackend, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };

package/dist/index.d.ts

@@ -29,6 +29,17 @@ interface VersionMeta {
     /** Timestamp when the version was created. */
     timestamp: number;
 }
+/** Content of a tombstone file in `.meta/.deleted/`. */
+interface TombstoneMeta {
+    /** The deleted file path. */
+    path: string;
+    /** Timestamp of deletion. */
+    deletedAt: number;
+    /** Backend ID that initiated the deletion. */
+    deletedBy: string;
+    /** Backend IDs that have confirmed the deletion (synced). */
+    confirmedBy: string[];
+}
 /** Content of a conflict archive file in `.meta/.conflicts/`. */
 interface ConflictArchive {
     /** The config file path that conflicted. */
@@ -146,6 +157,12 @@ interface IConfigRepo {
     getBackends(): Promise<BackendsMeta | null>;
     /** Write .meta/backends.json. */
     updateBackends(meta: BackendsMeta): Promise<void>;
+    /**
+     * Delete a file and record a tombstone for cross-backend sync.
+     * The tombstone ensures the deletion propagates to all backends
+     * instead of being treated as a "missing file" that gets re-created.
+     */
+    deleteFile(path: string): Promise<void>;
     /**
      * Sync .meta/ files (backends.json) to all replica backends.
      * Called automatically by createConfigRepo() after setupSync().
@@ -191,21 +208,54 @@ declare function configKeyToFilePath(configPath: string): string;
 declare function getExtension(path: string): string;
 
 /**
- * zen-fs-config — ConfigRepo Implementation
+ * zen-fs-config — Backend Registry
  *
- * Core implementation of IConfigRepo and the createConfigRepo factory.
+ * A pluggable registry that maps backend type names to factory functions.
+ *
+ * Core principle: zen-fs-config does NOT hardcode every ZenFS backend.
+ * Instead, it provides:
+ *   1. A simple registry API (registerBackend, createBackend, etc.)
+ *   2. One built-in backend (InMemory) — zero extra dependencies
+ *   3. A wrapZenFSFileSystem() helper to adapt any ZenFS FileSystem
+ *      implementation into the BackendInstance interface
+ *
+ * Applications (like zen-fs-config-admin) register whatever backends
+ * they need at startup.  Adding a new backend never requires changing
+ * zen-fs-config itself.
  */
 
-interface MinimalAsyncFS {
+type BackendFactory = (options: Record<string, unknown>) => Promise<BackendInstance>;
+/**
+ * The minimal interface a backend instance must satisfy.
+ * Matches zen-fs-cache's CacheableFileSystem requirements.
+ */
+interface BackendInstance {
     readFile(path: string, ...args: any[]): Promise<any>;
-    writeFile(path: string, data: any, options?: any): Promise<void>;
+    writeFile(path: string, data: string | Uint8Array | ArrayBuffer, options?: any): Promise<void>;
     readdir(path: string): Promise<string[]>;
-    stat(path: string): Promise<any>;
+    stat(path: string, ...args: any[]): Promise<any>;
     exists(path: string): Promise<boolean>;
     mkdir(path: string, options?: any): Promise<any>;
     unlink(path: string): Promise<void>;
-    rmdir?(path: string): Promise<void>;
+    rmdir(path: string): Promise<void>;
     rename?(oldPath: string, newPath: string): Promise<void>;
+    readFileMeta?(path: string, opts?: any): Promise<any>;
+    getRevision?(path: string): Promise<string | number | undefined>;
+}
+declare function registerBackend(type: string, factory: BackendFactory): void;
+declare function unregisterBackend(type: string): boolean;
+declare function createBackend(descriptor: Pick<BackendDescriptor, 'type' | 'options'>): Promise<BackendInstance>;
+declare function hasBackend(type: string): boolean;
+declare function listBackends(): string[];
+declare function wrapZenFSFileSystem(config: any): Promise<BackendInstance>;
+
+/**
+ * zen-fs-config — ConfigRepo Implementation
+ *
+ * Core implementation of IConfigRepo and the createConfigRepo factory.
+ */
+
+interface MinimalAsyncFS extends BackendInstance {
 }
 declare class ConfigRepo implements IConfigRepo {
     readonly appId: string;
@@ -222,7 +272,8 @@ declare class ConfigRepo implements IConfigRepo {
     private onConflictCallback?;
     private disposed;
     private configCache;
-    constructor(appId: string, nodeId: string, cachedFS: MinimalAsyncFS, serializer: PathAwareSerializer, onConflict?: (conflict: ConflictInfo) => Promise<unknown | null>);
+    private readonly primaryBackendId;
+    constructor(appId: string, nodeId: string, primaryBackendId: string, cachedFS: MinimalAsyncFS, serializer: PathAwareSerializer, onConflict?: (conflict: ConflictInfo) => Promise<unknown | null>);
     /** Full path to this node's directory on the primary backend. */
     get nodePath(): string;
     load(rawConfig?: string): Promise<void>;
@@ -235,6 +286,28 @@ declare class ConfigRepo implements IConfigRepo {
     }): Promise<SyncResult>;
     peekNodeConfig<T = unknown>(nodeId: string, path: string): Promise<T>;
     flush(): Promise<SyncResult[]>;
+    /**
+     * Delete a file and write a tombstone so the deletion propagates
+     * to all backends instead of being treated as "missing file → re-create".
+     */
+    deleteFile(path: string): Promise<void>;
+    /**
+     * Read all tombstones from the primary backend.
+     */
+    private readTombstones;
+    /**
+     * Before sync: for each tombstone, delete the actual file on all replicas.
+     * This prevents bi-directional sync from copying the file back.
+     */
+    private processTombstones;
+    /**
+     * After sync: mark each tombstone as confirmed by all replica backends.
+     */
+    private updateTombstoneConfirmations;
+    /**
+     * GC: remove tombstones where all backends in backends.json have confirmed.
+     */
+    private gcTombstones;
     /**
      * Sync .meta/ files (backends.json) to all replica backends.
      *
@@ -264,48 +337,6 @@ declare class ConfigRepo implements IConfigRepo {
 }
 declare function createConfigRepo(appId: string, options: ConfigRepoOptions): Promise<IConfigRepo>;
 
-/**
- * zen-fs-config — Backend Registry
- *
- * A pluggable registry that maps backend type names to factory functions.
- *
- * Core principle: zen-fs-config does NOT hardcode every ZenFS backend.
- * Instead, it provides:
- *   1. A simple registry API (registerBackend, createBackend, etc.)
- *   2. One built-in backend (InMemory) — zero extra dependencies
- *   3. A wrapZenFSFileSystem() helper to adapt any ZenFS FileSystem
- *      implementation into the BackendInstance interface
- *
- * Applications (like zen-fs-config-admin) register whatever backends
- * they need at startup.  Adding a new backend never requires changing
- * zen-fs-config itself.
- */
-
-type BackendFactory = (options: Record<string, unknown>) => Promise<BackendInstance>;
-/**
- * The minimal interface a backend instance must satisfy.
- * Matches zen-fs-cache's CacheableFileSystem requirements.
- */
-interface BackendInstance {
-    readFile(path: string, ...args: any[]): Promise<any>;
-    writeFile(path: string, data: string | Uint8Array | ArrayBuffer, options?: any): Promise<void>;
-    readdir(path: string): Promise<string[]>;
-    stat(path: string, ...args: any[]): Promise<any>;
-    exists(path: string): Promise<boolean>;
-    mkdir(path: string, options?: any): Promise<any>;
-    unlink(path: string): Promise<void>;
-    rmdir(path: string): Promise<void>;
-    rename?(oldPath: string, newPath: string): Promise<void>;
-    readFileMeta?(path: string, opts?: any): Promise<any>;
-    getRevision?(path: string): Promise<string | number | undefined>;
-}
-declare function registerBackend(type: string, factory: BackendFactory): void;
-declare function unregisterBackend(type: string): boolean;
-declare function createBackend(descriptor: Pick<BackendDescriptor, 'type' | 'options'>): Promise<BackendInstance>;
-declare function hasBackend(type: string): boolean;
-declare function listBackends(): string[];
-declare function wrapZenFSFileSystem(config: any): Promise<BackendInstance>;
-
 /**
  * zen-fs-config — Sidecar Version File Management
  *
@@ -348,4 +379,4 @@ declare function incrementVersion(fs: SyncableFS, configFilePath: string, newCon
  */
 declare function verifyOrRepairVersion(fs: SyncableFS, configFilePath: string, author: string): Promise<VersionMeta | null>;
 
-export { type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type IConfigRepo, type VersionMeta, configKeyToFilePath, createBackend, createConfigRepo, createSerializerChain, getExtension, hasBackend, incrementVersion, listBackends, readVersion, registerBackend, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };
+export { type BackendDescriptor, type BackendFactory, type BackendInstance, type BackendsMeta, type CacheOptions, ConfigRepo, type ConfigRepoOptions, type ConfigSerializer, type ConflictArchive, type ConflictInfo, type IConfigRepo, type TombstoneMeta, type VersionMeta, configKeyToFilePath, createBackend, createConfigRepo, createSerializerChain, getExtension, hasBackend, incrementVersion, listBackends, readVersion, registerBackend, sha256, unregisterBackend, verifyOrRepairVersion, versionPathFor, wrapZenFSFileSystem, writeVersion };

package/dist/index.js

@@ -225,8 +225,8 @@ async function ensureParentDir(absolutePath) {
 }
 
 // src/adapters.ts
-function backendToSyncableFS(backend) {
-  return {
+function backendToSyncableFS(backend, name) {
+  const syncable = {
     async readdir(path) {
       return backend.readdir(path);
     },
@@ -252,8 +252,7 @@ function backendToSyncableFS(backend) {
     async stat(path) {
       const s = await backend.stat(path);
       return {
-        isFile: typeof s.isFile === "function" ? () => s.isFile() : () => !!(s.mode && !(s.mode & 16384)),
-        isDirectory: typeof s.isDirectory === "function" ? () => s.isDirectory() : () => !!(s.mode && s.mode & 16384),
+        mode: typeof s.mode === "number" ? s.mode : void 0,
         size: s.size ?? 0,
         mtimeMs: typeof s.mtimeMs === "number" ? s.mtimeMs : s.mtime ? new Date(s.mtime).getTime() : 0
       };
@@ -265,47 +264,14 @@ function backendToSyncableFS(backend) {
       return backend.exists(path);
     }
   };
-}
-function cachedFSToSyncableFS(cached) {
-  return {
-    async readdir(path) {
-      return cached.readdir(path);
-    },
-    async readFile(path, encoding) {
-      const data = await cached.readFile(path);
-      if (encoding) {
-        if (typeof data === "string") return data;
-        return new TextDecoder().decode(
-          data instanceof ArrayBuffer ? new Uint8Array(data) : data
-        );
-      }
-      if (typeof data === "string") return Buffer.from(data);
-      if (data instanceof ArrayBuffer) return Buffer.from(new Uint8Array(data));
-      return Buffer.from(data);
-    },
-    async writeFile(path, data) {
-      return cached.writeFile(path, data);
-    },
-    async unlink(path) {
-      return cached.unlink(path);
-    },
-    async stat(path) {
-      const s = await cached.stat(path);
-      const isDir = typeof s.isDirectory === "function" ? s.isDirectory() : typeof s.isDirectory === "boolean" ? s.isDirectory : s.mode !== void 0 && (s.mode & 61440) === 16384;
-      return {
-        isFile: () => !isDir,
-        isDirectory: () => isDir,
-        size: s.size,
-        mtimeMs: s.mtimeMs ?? s.mtime
-      };
-    },
-    async mkdir(path, options) {
-      return cached.mkdir(path, options);
-    },
-    async exists(path) {
-      return cached.exists(path);
-    }
-  };
+  if (name) {
+    syncable.backendName = name;
+  } else if (backend.backendName) {
+    syncable.backendName = backend.backendName;
+  } else {
+    syncable.backendName = backend.constructor.name || "Backend";
+  }
+  return syncable;
 }
 
 // src/backend-registry.ts
@@ -365,12 +331,10 @@ async function wrapZenFSFileSystem(config) {
     },
     async stat(path, ..._args) {
       const st = await isolatedFS.stat(path);
-      const isDir = typeof st.isDirectory === "function" ? st.isDirectory() : st.mode !== void 0 && (st.mode & 61440) === 16384;
       return {
-        isFile: () => !isDir,
-        isDirectory: () => isDir,
+        mode: typeof st.mode === "number" ? st.mode : void 0,
         size: st.size,
-        mtime: st.mtimeMs ?? st.mtime
+        mtimeMs: st.mtimeMs ?? st.mtime ?? 0
       };
     },
     async exists(path) {
@@ -485,8 +449,12 @@ async function verifyOrRepairVersion(fs, configFilePath, author) {
 var META_DIR = "/.meta";
 var BACKENDS_FILE = `${META_DIR}/backends.json`;
 var CONFLICTS_DIR = `${META_DIR}/.conflicts`;
+var DELETIONS_DIR = `${META_DIR}/.deleted`;
 var NODES_DIR = "/nodes";
 var NODE_ID_FILE = `${NODES_DIR}/.node-id`;
+function tombstoneFileName(filePath) {
+  return filePath.replace(/^\//, "").replace(/\//g, "__").replace(/\./g, "++") + ".json";
+}
 var ConfigRepo = class {
   appId;
   nodeId;
@@ -502,15 +470,17 @@ var ConfigRepo = class {
   onConflictCallback;
   disposed = false;
   configCache = /* @__PURE__ */ new Map();
-  constructor(appId, nodeId, cachedFS, serializer, onConflict) {
+  primaryBackendId;
+  constructor(appId, nodeId, primaryBackendId, cachedFS, serializer, onConflict) {
     this.appId = appId;
     this.nodeId = nodeId;
+    this.primaryBackendId = primaryBackendId;
     this.cachedFS = cachedFS;
     this.serializer = serializer;
     this.syncEngine = new import_zen_fs_sync.ZenFSSync();
     this.replicaBackends = /* @__PURE__ */ new Map();
     this.onConflictCallback = onConflict;
-    this.fullFS = cachedFSToSyncableFS(cachedFS);
+    this.fullFS = backendToSyncableFS(cachedFS, primaryBackendId);
     this.fs = createChrootFS(cachedFS, `/${appId}`);
     this.rootFS = createChrootFS(cachedFS, "/");
   }
@@ -654,9 +624,141 @@ var ConfigRepo = class {
   // -----------------------------------------------------------------------
   async flush() {
     this.assertNotDisposed();
+    await this.processTombstones();
     const resultsMap = await this.syncEngine.syncAll();
+    await this.updateTombstoneConfirmations();
+    await this.gcTombstones();
     return Array.from(resultsMap.values());
   }
+  // -----------------------------------------------------------------------
+  // Tombstone (Deletion Tracking)
+  // -----------------------------------------------------------------------
+  /**
+   * Delete a file and write a tombstone so the deletion propagates
+   * to all backends instead of being treated as "missing file → re-create".
+   */
+  async deleteFile(path) {
+    this.assertNotDisposed();
+    const normalizedPath = path.startsWith("/") ? path : "/" + path;
+    const tombstonePath = `${DELETIONS_DIR}/${tombstoneFileName(normalizedPath)}`;
+    const tombstone = {
+      path: normalizedPath,
+      deletedAt: Date.now(),
+      deletedBy: this.primaryBackendId,
+      confirmedBy: [this.primaryBackendId]
+    };
+    await this.ensureDir(tombstonePath);
+    await this.cachedFS.writeFile(
+      tombstonePath,
+      new TextEncoder().encode(JSON.stringify(tombstone, null, 2))
+    );
+    try {
+      await this.cachedFS.unlink(normalizedPath);
+    } catch {
+    }
+    const versionPath = versionPathFor(normalizedPath);
+    try {
+      await this.cachedFS.unlink(versionPath);
+    } catch {
+    }
+    console.log(`[ConfigRepo] deleteFile: ${normalizedPath} (tombstone at ${tombstonePath})`);
+  }
+  /**
+   * Read all tombstones from the primary backend.
+   */
+  async readTombstones() {
+    try {
+      const entries = await this.cachedFS.readdir(DELETIONS_DIR);
+      const tombstones = [];
+      for (const entry of entries) {
+        if (!entry.endsWith(".json")) continue;
+        try {
+          const raw = await this.cachedFS.readFile(`${DELETIONS_DIR}/${entry}`);
+          const data = JSON.parse(new TextDecoder().decode(toUint8Array(raw)));
+          tombstones.push(data);
+        } catch {
+        }
+      }
+      return tombstones;
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Before sync: for each tombstone, delete the actual file on all replicas.
+   * This prevents bi-directional sync from copying the file back.
+   */
+  async processTombstones() {
+    const tombstones = await this.readTombstones();
+    if (tombstones.length === 0) return;
+    console.log(`[ConfigRepo] processTombstones: ${tombstones.length} tombstone(s)`);
+    for (const tombstone of tombstones) {
+      try {
+        await this.cachedFS.unlink(tombstone.path);
+      } catch {
+      }
+      try {
+        await this.cachedFS.unlink(versionPathFor(tombstone.path));
+      } catch {
+      }
+      for (const [replicaId, replica] of this.replicaBackends) {
+        try {
+          await replica.instance.unlink(tombstone.path);
+        } catch {
+        }
+        try {
+          await replica.instance.unlink(versionPathFor(tombstone.path));
+        } catch {
+        }
+        console.log(`[ConfigRepo] tombstone ${tombstone.path}: deleted on ${replicaId}`);
+      }
+    }
+  }
+  /**
+   * After sync: mark each tombstone as confirmed by all replica backends.
+   */
+  async updateTombstoneConfirmations() {
+    const tombstones = await this.readTombstones();
+    if (tombstones.length === 0) return;
+    const backendsMeta = await this.getBackends();
+    const allBackendIds = backendsMeta?.backends.map((b) => b.id) ?? [this.primaryBackendId];
+    for (const tombstone of tombstones) {
+      const tombstonePath = `${DELETIONS_DIR}/${tombstoneFileName(tombstone.path)}`;
+      for (const replicaId of this.replicaBackends.keys()) {
+        if (!tombstone.confirmedBy.includes(replicaId)) {
+          tombstone.confirmedBy.push(replicaId);
+        }
+      }
+      try {
+        await this.cachedFS.writeFile(
+          tombstonePath,
+          new TextEncoder().encode(JSON.stringify(tombstone, null, 2))
+        );
+      } catch {
+      }
+    }
+    console.log(`[ConfigRepo] updateTombstoneConfirmations: ${tombstones.length} tombstone(s) updated`);
+  }
+  /**
+   * GC: remove tombstones where all backends in backends.json have confirmed.
+   */
+  async gcTombstones() {
+    const tombstones = await this.readTombstones();
+    if (tombstones.length === 0) return;
+    const backendsMeta = await this.getBackends();
+    const allBackendIds = backendsMeta?.backends.map((b) => b.id) ?? [this.primaryBackendId];
+    for (const tombstone of tombstones) {
+      const allConfirmed = allBackendIds.every((id) => tombstone.confirmedBy.includes(id));
+      if (allConfirmed) {
+        const tombstonePath = `${DELETIONS_DIR}/${tombstoneFileName(tombstone.path)}`;
+        try {
+          await this.cachedFS.unlink(tombstonePath);
+          console.log(`[ConfigRepo] gcTombstones: removed ${tombstonePath} (all ${allBackendIds.length} backends confirmed)`);
+        } catch {
+        }
+      }
+    }
+  }
   /**
    * Sync .meta/ files (backends.json) to all replica backends.
    *
@@ -769,7 +871,7 @@ var ConfigRepo = class {
       console.log(`[ConfigRepo] Creating replica backend: id=${desc.id}, type=${desc.type}`);
       try {
         const instance = await createBackend(desc);
-        const syncable = backendToSyncableFS(instance);
+        const syncable = backendToSyncableFS(instance, `${desc.type}(${desc.id})`);
         this.replicaBackends.set(desc.id, { instance, syncable });
         console.log(`[ConfigRepo] Replica ${desc.id} created successfully`);
       } catch (err) {
@@ -986,21 +1088,7 @@ async function createConfigRepo(appId, options) {
     type: options.backendInfo.type,
     options: options.backendInfo.options
   });
-  const zenCache = await import("zen-fs-cache");
-  let cacheStore;
-  const storeType = options.cache?.storeType ?? "MemoryCacheStore";
-  if (storeType === "IdbCacheStore") {
-    cacheStore = new zenCache.IdbCacheStore(options.cache?.storePrefix);
-  } else {
-    cacheStore = new zenCache.MemoryCacheStore();
-  }
-  const cachedFS = new zenCache.CachedFileSystem(
-    primaryInstance,
-    cacheStore,
-    {
-      ttlMs: options.cache?.ttlMs ?? 0
-    }
-  );
+  const cachedFS = primaryInstance;
   try {
     const metaExists = await primaryInstance.exists(META_DIR);
     console.log(`[createConfigRepo] /.meta/ exists: ${metaExists}`);
@@ -1015,6 +1103,7 @@ async function createConfigRepo(appId, options) {
   const tempRepo = new ConfigRepo(
     appId,
     "",
+    options.primaryBackendId,
     cachedFS,
     createSerializerChain(),
     void 0
@@ -1071,6 +1160,7 @@ async function createConfigRepo(appId, options) {
   const repo = new ConfigRepo(
     appId,
     nodeId,
+    options.primaryBackendId,
     cachedFS,
     serializer,
     options.onConflict

package/dist/index.mjs

@@ -176,8 +176,8 @@ async function ensureParentDir(absolutePath) {
 }
 
 // src/adapters.ts
-function backendToSyncableFS(backend) {
-  return {
+function backendToSyncableFS(backend, name) {
+  const syncable = {
     async readdir(path) {
       return backend.readdir(path);
     },
@@ -203,8 +203,7 @@ function backendToSyncableFS(backend) {
     async stat(path) {
       const s = await backend.stat(path);
       return {
-        isFile: typeof s.isFile === "function" ? () => s.isFile() : () => !!(s.mode && !(s.mode & 16384)),
-        isDirectory: typeof s.isDirectory === "function" ? () => s.isDirectory() : () => !!(s.mode && s.mode & 16384),
+        mode: typeof s.mode === "number" ? s.mode : void 0,
         size: s.size ?? 0,
         mtimeMs: typeof s.mtimeMs === "number" ? s.mtimeMs : s.mtime ? new Date(s.mtime).getTime() : 0
       };
@@ -216,47 +215,14 @@ function backendToSyncableFS(backend) {
       return backend.exists(path);
     }
   };
-}
-function cachedFSToSyncableFS(cached) {
-  return {
-    async readdir(path) {
-      return cached.readdir(path);
-    },
-    async readFile(path, encoding) {
-      const data = await cached.readFile(path);
-      if (encoding) {
-        if (typeof data === "string") return data;
-        return new TextDecoder().decode(
-          data instanceof ArrayBuffer ? new Uint8Array(data) : data
-        );
-      }
-      if (typeof data === "string") return Buffer.from(data);
-      if (data instanceof ArrayBuffer) return Buffer.from(new Uint8Array(data));
-      return Buffer.from(data);
-    },
-    async writeFile(path, data) {
-      return cached.writeFile(path, data);
-    },
-    async unlink(path) {
-      return cached.unlink(path);
-    },
-    async stat(path) {
-      const s = await cached.stat(path);
-      const isDir = typeof s.isDirectory === "function" ? s.isDirectory() : typeof s.isDirectory === "boolean" ? s.isDirectory : s.mode !== void 0 && (s.mode & 61440) === 16384;
-      return {
-        isFile: () => !isDir,
-        isDirectory: () => isDir,
-        size: s.size,
-        mtimeMs: s.mtimeMs ?? s.mtime
-      };
-    },
-    async mkdir(path, options) {
-      return cached.mkdir(path, options);
-    },
-    async exists(path) {
-      return cached.exists(path);
-    }
-  };
+  if (name) {
+    syncable.backendName = name;
+  } else if (backend.backendName) {
+    syncable.backendName = backend.backendName;
+  } else {
+    syncable.backendName = backend.constructor.name || "Backend";
+  }
+  return syncable;
 }
 
 // src/backend-registry.ts
@@ -316,12 +282,10 @@ async function wrapZenFSFileSystem(config) {
     },
     async stat(path, ..._args) {
       const st = await isolatedFS.stat(path);
-      const isDir = typeof st.isDirectory === "function" ? st.isDirectory() : st.mode !== void 0 && (st.mode & 61440) === 16384;
       return {
-        isFile: () => !isDir,
-        isDirectory: () => isDir,
+        mode: typeof st.mode === "number" ? st.mode : void 0,
         size: st.size,
-        mtime: st.mtimeMs ?? st.mtime
+        mtimeMs: st.mtimeMs ?? st.mtime ?? 0
       };
     },
     async exists(path) {
@@ -436,8 +400,12 @@ async function verifyOrRepairVersion(fs, configFilePath, author) {
 var META_DIR = "/.meta";
 var BACKENDS_FILE = `${META_DIR}/backends.json`;
 var CONFLICTS_DIR = `${META_DIR}/.conflicts`;
+var DELETIONS_DIR = `${META_DIR}/.deleted`;
 var NODES_DIR = "/nodes";
 var NODE_ID_FILE = `${NODES_DIR}/.node-id`;
+function tombstoneFileName(filePath) {
+  return filePath.replace(/^\//, "").replace(/\//g, "__").replace(/\./g, "++") + ".json";
+}
 var ConfigRepo = class {
   appId;
   nodeId;
@@ -453,15 +421,17 @@ var ConfigRepo = class {
   onConflictCallback;
   disposed = false;
   configCache = /* @__PURE__ */ new Map();
-  constructor(appId, nodeId, cachedFS, serializer, onConflict) {
+  primaryBackendId;
+  constructor(appId, nodeId, primaryBackendId, cachedFS, serializer, onConflict) {
     this.appId = appId;
     this.nodeId = nodeId;
+    this.primaryBackendId = primaryBackendId;
     this.cachedFS = cachedFS;
     this.serializer = serializer;
     this.syncEngine = new ZenFSSync();
     this.replicaBackends = /* @__PURE__ */ new Map();
     this.onConflictCallback = onConflict;
-    this.fullFS = cachedFSToSyncableFS(cachedFS);
+    this.fullFS = backendToSyncableFS(cachedFS, primaryBackendId);
     this.fs = createChrootFS(cachedFS, `/${appId}`);
     this.rootFS = createChrootFS(cachedFS, "/");
   }
@@ -605,9 +575,141 @@ var ConfigRepo = class {
   // -----------------------------------------------------------------------
   async flush() {
     this.assertNotDisposed();
+    await this.processTombstones();
     const resultsMap = await this.syncEngine.syncAll();
+    await this.updateTombstoneConfirmations();
+    await this.gcTombstones();
     return Array.from(resultsMap.values());
   }
+  // -----------------------------------------------------------------------
+  // Tombstone (Deletion Tracking)
+  // -----------------------------------------------------------------------
+  /**
+   * Delete a file and write a tombstone so the deletion propagates
+   * to all backends instead of being treated as "missing file → re-create".
+   */
+  async deleteFile(path) {
+    this.assertNotDisposed();
+    const normalizedPath = path.startsWith("/") ? path : "/" + path;
+    const tombstonePath = `${DELETIONS_DIR}/${tombstoneFileName(normalizedPath)}`;
+    const tombstone = {
+      path: normalizedPath,
+      deletedAt: Date.now(),
+      deletedBy: this.primaryBackendId,
+      confirmedBy: [this.primaryBackendId]
+    };
+    await this.ensureDir(tombstonePath);
+    await this.cachedFS.writeFile(
+      tombstonePath,
+      new TextEncoder().encode(JSON.stringify(tombstone, null, 2))
+    );
+    try {
+      await this.cachedFS.unlink(normalizedPath);
+    } catch {
+    }
+    const versionPath = versionPathFor(normalizedPath);
+    try {
+      await this.cachedFS.unlink(versionPath);
+    } catch {
+    }
+    console.log(`[ConfigRepo] deleteFile: ${normalizedPath} (tombstone at ${tombstonePath})`);
+  }
+  /**
+   * Read all tombstones from the primary backend.
+   */
+  async readTombstones() {
+    try {
+      const entries = await this.cachedFS.readdir(DELETIONS_DIR);
+      const tombstones = [];
+      for (const entry of entries) {
+        if (!entry.endsWith(".json")) continue;
+        try {
+          const raw = await this.cachedFS.readFile(`${DELETIONS_DIR}/${entry}`);
+          const data = JSON.parse(new TextDecoder().decode(toUint8Array(raw)));
+          tombstones.push(data);
+        } catch {
+        }
+      }
+      return tombstones;
+    } catch {
+      return [];
+    }
+  }
+  /**
+   * Before sync: for each tombstone, delete the actual file on all replicas.
+   * This prevents bi-directional sync from copying the file back.
+   */
+  async processTombstones() {
+    const tombstones = await this.readTombstones();
+    if (tombstones.length === 0) return;
+    console.log(`[ConfigRepo] processTombstones: ${tombstones.length} tombstone(s)`);
+    for (const tombstone of tombstones) {
+      try {
+        await this.cachedFS.unlink(tombstone.path);
+      } catch {
+      }
+      try {
+        await this.cachedFS.unlink(versionPathFor(tombstone.path));
+      } catch {
+      }
+      for (const [replicaId, replica] of this.replicaBackends) {
+        try {
+          await replica.instance.unlink(tombstone.path);
+        } catch {
+        }
+        try {
+          await replica.instance.unlink(versionPathFor(tombstone.path));
+        } catch {
+        }
+        console.log(`[ConfigRepo] tombstone ${tombstone.path}: deleted on ${replicaId}`);
+      }
+    }
+  }
+  /**
+   * After sync: mark each tombstone as confirmed by all replica backends.
+   */
+  async updateTombstoneConfirmations() {
+    const tombstones = await this.readTombstones();
+    if (tombstones.length === 0) return;
+    const backendsMeta = await this.getBackends();
+    const allBackendIds = backendsMeta?.backends.map((b) => b.id) ?? [this.primaryBackendId];
+    for (const tombstone of tombstones) {
+      const tombstonePath = `${DELETIONS_DIR}/${tombstoneFileName(tombstone.path)}`;
+      for (const replicaId of this.replicaBackends.keys()) {
+        if (!tombstone.confirmedBy.includes(replicaId)) {
+          tombstone.confirmedBy.push(replicaId);
+        }
+      }
+      try {
+        await this.cachedFS.writeFile(
+          tombstonePath,
+          new TextEncoder().encode(JSON.stringify(tombstone, null, 2))
+        );
+      } catch {
+      }
+    }
+    console.log(`[ConfigRepo] updateTombstoneConfirmations: ${tombstones.length} tombstone(s) updated`);
+  }
+  /**
+   * GC: remove tombstones where all backends in backends.json have confirmed.
+   */
+  async gcTombstones() {
+    const tombstones = await this.readTombstones();
+    if (tombstones.length === 0) return;
+    const backendsMeta = await this.getBackends();
+    const allBackendIds = backendsMeta?.backends.map((b) => b.id) ?? [this.primaryBackendId];
+    for (const tombstone of tombstones) {
+      const allConfirmed = allBackendIds.every((id) => tombstone.confirmedBy.includes(id));
+      if (allConfirmed) {
+        const tombstonePath = `${DELETIONS_DIR}/${tombstoneFileName(tombstone.path)}`;
+        try {
+          await this.cachedFS.unlink(tombstonePath);
+          console.log(`[ConfigRepo] gcTombstones: removed ${tombstonePath} (all ${allBackendIds.length} backends confirmed)`);
+        } catch {
+        }
+      }
+    }
+  }
   /**
    * Sync .meta/ files (backends.json) to all replica backends.
    *
@@ -720,7 +822,7 @@ var ConfigRepo = class {
       console.log(`[ConfigRepo] Creating replica backend: id=${desc.id}, type=${desc.type}`);
       try {
         const instance = await createBackend(desc);
-        const syncable = backendToSyncableFS(instance);
+        const syncable = backendToSyncableFS(instance, `${desc.type}(${desc.id})`);
         this.replicaBackends.set(desc.id, { instance, syncable });
         console.log(`[ConfigRepo] Replica ${desc.id} created successfully`);
       } catch (err) {
@@ -937,21 +1039,7 @@ async function createConfigRepo(appId, options) {
     type: options.backendInfo.type,
     options: options.backendInfo.options
   });
-  const zenCache = await import("zen-fs-cache");
-  let cacheStore;
-  const storeType = options.cache?.storeType ?? "MemoryCacheStore";
-  if (storeType === "IdbCacheStore") {
-    cacheStore = new zenCache.IdbCacheStore(options.cache?.storePrefix);
-  } else {
-    cacheStore = new zenCache.MemoryCacheStore();
-  }
-  const cachedFS = new zenCache.CachedFileSystem(
-    primaryInstance,
-    cacheStore,
-    {
-      ttlMs: options.cache?.ttlMs ?? 0
-    }
-  );
+  const cachedFS = primaryInstance;
   try {
     const metaExists = await primaryInstance.exists(META_DIR);
     console.log(`[createConfigRepo] /.meta/ exists: ${metaExists}`);
@@ -966,6 +1054,7 @@ async function createConfigRepo(appId, options) {
   const tempRepo = new ConfigRepo(
     appId,
     "",
+    options.primaryBackendId,
     cachedFS,
     createSerializerChain(),
     void 0
@@ -1022,6 +1111,7 @@ async function createConfigRepo(appId, options) {
   const repo = new ConfigRepo(
     appId,
     nodeId,
+    options.primaryBackendId,
     cachedFS,
     serializer,
     options.onConflict

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zen-fs-config",
-  "version": "0.3.24",
+  "version": "0.3.27",
   "description": "Distributed config management library built on ZenFS, zen-fs-cache, and zen-fs-sync",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -49,7 +49,6 @@
     "typescript": "^5.9.3",
     "vitest": "^1.6.1",
     "zen-fs-cache": "^1.0.1",
-    "zen-fs-sync": "^0.1.0"
-  },
-  "dependencies": {}
+    "zen-fs-sync": "^0.2.2"
+  }
 }