@vrtmrz/livesync-commonlib 0.1.10 → 0.1.12

package/dist/pouchdb/StreamingFetch.js

@@ -128,15 +128,19 @@ function generatePouchDBBatchWriter(downloadToDB, decryptFunction, onCheckpoint)
   return {
     async write(doc, sequence) {
       let decryptedDoc;
-      try {
-        decryptedDoc = await decryptFunction(doc);
-      } catch (error) {
-        throw new StreamingFetchFailure(
-          "decryption",
-          `Fast Fetch could not decrypt a document: ${errorMessage(error)}`,
-          false,
-          { cause: error }
-        );
+      if (doc._deleted) {
+        decryptedDoc = doc;
+      } else {
+        try {
+          decryptedDoc = await decryptFunction(doc);
+        } catch (error) {
+          throw new StreamingFetchFailure(
+            "decryption",
+            `Fast Fetch could not decrypt a document: ${errorMessage(error)}`,
+            false,
+            { cause: error }
+          );
+        }
       }
       let serialisedDoc;
       try {

package/dist/replication/couchdb/LiveSyncReplicator.d.ts

@@ -32,6 +32,7 @@ export declare class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicato
     updateMaxTransferredSeqOnChunks(localDB: PouchDB.Database, remoteID: number, seqStatusMap: Record<number, boolean>): Promise<ReturnType<typeof this.getEmptyMaxEntry>>;
     sendChunks(setting: RemoteDBSettings, remoteDB: PouchDB.Database<EntryDoc> | undefined, showResult: boolean, fromSeq?: number | string): Promise<boolean>;
     openOneShotReplication(setting: RemoteDBSettings, showResult: boolean, retrying: boolean, syncMode: "sync" | "pullOnly" | "pushOnly", ignoreCleanLock?: boolean): Promise<boolean>;
+    private closeRemoteDatabase;
     replicateAllToServer(setting: RemoteDBSettings, showingNotice?: boolean): Promise<boolean>;
     replicateAllFromServer(setting: RemoteDBSettings, showingNotice?: boolean): Promise<boolean>;
     checkReplicationConnectivity(setting: RemoteDBSettings, keepAlive: boolean, skipCheck: boolean, showResult: boolean, ignoreCleanLock?: boolean): Promise<false | {

package/dist/replication/couchdb/LiveSyncReplicator.js

@@ -540,80 +540,94 @@ ${sendingDocs}/(${sentDocsCount} done)`,
         );
         return false;
       }
-      this.maxPullSeq = Number(`${ret.info.update_seq}`.split("-")[0]);
-      this.maxPushSeq = Number(`${(await localDB.info()).update_seq}`.split("-")[0]);
-      if (showResult) {
-        Logger(this.translate("liveSyncReplicator.checkingLastSyncPoint"), LOG_LEVEL_NOTICE, "sync");
-      }
       const { db, syncOptionBase } = ret;
-      this.syncStatus = "STARTED";
-      this.updateInfo();
-      const docArrivedOnStart = this.docArrived;
-      const docSentOnStart = this.docSent;
-      if (!retrying) {
-        this.originalSetting = setting;
-      }
-      this.terminateSync();
-      const syncHandler = syncMode == "sync" ? localDB.sync(db, { ...syncOptionBase }) : syncMode == "pullOnly" ? localDB.replicate.from(db, {
-        ...syncOptionBase,
-        ...setting.readChunksOnline ? selectorOnDemandPull : {}
-      }) : syncMode == "pushOnly" ? localDB.replicate.to(db, { ...syncOptionBase }) : void 0;
-      const syncResult = await this.processSync(
-        syncHandler,
-        showResult,
-        docSentOnStart,
-        docArrivedOnStart,
-        syncMode,
-        retrying,
-        false
-      );
-      if (syncResult == "DONE") {
-        return true;
-      }
-      if (syncResult == "CANCELLED") {
-        return false;
-      }
-      if (syncResult == "FAILED") {
-        return false;
-      }
-      if (syncResult == "NEED_RESURRECT") {
+      try {
+        this.maxPullSeq = Number(`${ret.info.update_seq}`.split("-")[0]);
+        this.maxPushSeq = Number(`${(await localDB.info()).update_seq}`.split("-")[0]);
+        if (showResult) {
+          Logger(this.translate("liveSyncReplicator.checkingLastSyncPoint"), LOG_LEVEL_NOTICE, "sync");
+        }
+        this.syncStatus = "STARTED";
+        this.updateInfo();
+        const docArrivedOnStart = this.docArrived;
+        const docSentOnStart = this.docSent;
+        if (!retrying) {
+          this.originalSetting = setting;
+        }
         this.terminateSync();
-        return async () => await this.openOneShotReplication(
-          this.originalSetting,
+        const syncHandler = syncMode == "sync" ? localDB.sync(db, { ...syncOptionBase }) : syncMode == "pullOnly" ? localDB.replicate.from(db, {
+          ...syncOptionBase,
+          ...setting.readChunksOnline ? selectorOnDemandPull : {}
+        }) : syncMode == "pushOnly" ? localDB.replicate.to(db, { ...syncOptionBase }) : void 0;
+        const syncResult = await this.processSync(
+          syncHandler,
           showResult,
-          false,
+          docSentOnStart,
+          docArrivedOnStart,
           syncMode,
-          ignoreCleanLock
+          retrying,
+          false
         );
-      }
-      if (syncResult == "NEED_RETRY") {
-        const tempSetting = JSON.parse(JSON.stringify(setting));
-        tempSetting.batch_size = Math.ceil(tempSetting.batch_size / 2) + 2;
-        tempSetting.batches_limit = Math.ceil(tempSetting.batches_limit / 2) + 2;
-        if (tempSetting.batch_size <= 5 && tempSetting.batches_limit <= 5) {
-          Logger(
-            this.translate("liveSyncReplicator.cantReplicateLowerValue"),
-            showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO
-          );
+        if (syncResult == "DONE") {
+          return true;
+        }
+        if (syncResult == "CANCELLED") {
           return false;
-        } else {
-          Logger(
-            this.translate("liveSyncReplicator.retryLowerBatchSize", {
-              batch_size: tempSetting.batch_size.toString(),
-              batches_limit: tempSetting.batches_limit.toString()
-            }),
-            showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO
+        }
+        if (syncResult == "FAILED") {
+          return false;
+        }
+        if (syncResult == "NEED_RESURRECT") {
+          this.terminateSync();
+          return async () => await this.openOneShotReplication(
+            this.originalSetting,
+            showResult,
+            false,
+            syncMode,
+            ignoreCleanLock
           );
-          return async () => await this.openOneShotReplication(tempSetting, showResult, true, syncMode, ignoreCleanLock);
         }
+        if (syncResult == "NEED_RETRY") {
+          const tempSetting = JSON.parse(JSON.stringify(setting));
+          tempSetting.batch_size = Math.ceil(tempSetting.batch_size / 2) + 2;
+          tempSetting.batches_limit = Math.ceil(tempSetting.batches_limit / 2) + 2;
+          if (tempSetting.batch_size <= 5 && tempSetting.batches_limit <= 5) {
+            Logger(
+              this.translate("liveSyncReplicator.cantReplicateLowerValue"),
+              showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO
+            );
+            return false;
+          } else {
+            Logger(
+              this.translate("liveSyncReplicator.retryLowerBatchSize", {
+                batch_size: tempSetting.batch_size.toString(),
+                batches_limit: tempSetting.batches_limit.toString()
+              }),
+              showResult ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO
+            );
+            return async () => await this.openOneShotReplication(tempSetting, showResult, true, syncMode, ignoreCleanLock);
+          }
+        }
+        return false;
+      } finally {
+        await this.closeRemoteDatabase(db);
       }
-      return false;
     });
     if (typeof next === "boolean") {
       return next;
     }
     return await next();
   }
+  // One-shot attempts own their temporary remote handle. Continuous replication
+  // keeps its handle until the replication controller terminates it.
+  async closeRemoteDatabase(db) {
+    try {
+      await db.close();
+    } catch (ex) {
+      Logger("Failed to close remote database.", LOG_LEVEL_INFO, "sync");
+      Logger(ex, LOG_LEVEL_VERBOSE, "sync");
+    }
+  }
   replicateAllToServer(setting, showingNotice) {
     return this.openOneShotReplication(setting, showingNotice ?? false, false, "pushOnly");
   }
@@ -638,72 +652,87 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       );
       return false;
     }
-    if (!skipCheck) {
-      if (!await checkRemoteVersion(dbRet.db, this.migrate.bind(this), VER)) {
-        Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
-        return false;
-      }
-      this.remoteCleaned = false;
-      this.remoteLocked = false;
-      this.remoteLockedAndDeviceNotAccepted = false;
-      this.tweakSettingsMismatched = false;
-      this.preferredTweakValue = void 0;
-      const progress = `${dbRet.info.update_seq}`;
-      const info = {
-        app_version: this.env.services.API.getAppVersion(),
-        plugin_version: this.env.services.API.getPluginVersion(),
-        vault_name: this.env.services.vault.vaultName(),
-        device_name: this.env.services.vault.getVaultName(),
-        progress
-      };
-      const ensure = await ensureDatabaseIsCompatible(dbRet.db, setting, this.nodeid, currentVersionRange, info);
-      if (ensure == "INCOMPATIBLE") {
-        Logger(
-          "The remote database has no compatibility with the running version. Please upgrade the plugin.",
-          LOG_LEVEL_NOTICE
-        );
-        return false;
-      } else if (ensure == "NODE_LOCKED") {
-        Logger(
-          "The remote database has been rebuilt or corrupted since we have synchronized last time. Fetch rebuilt DB, explicit unlocking or chunk clean-up is required.",
-          LOG_LEVEL_NOTICE
+    let ownershipTransferred = false;
+    try {
+      if (!skipCheck) {
+        if (!await checkRemoteVersion(dbRet.db, this.migrate.bind(this), VER)) {
+          Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
+          return false;
+        }
+        this.remoteCleaned = false;
+        this.remoteLocked = false;
+        this.remoteLockedAndDeviceNotAccepted = false;
+        this.tweakSettingsMismatched = false;
+        this.preferredTweakValue = void 0;
+        const progress = `${dbRet.info.update_seq}`;
+        const info = {
+          app_version: this.env.services.API.getAppVersion(),
+          plugin_version: this.env.services.API.getPluginVersion(),
+          vault_name: this.env.services.vault.vaultName(),
+          device_name: this.env.services.vault.getVaultName(),
+          progress
+        };
+        const ensure = await ensureDatabaseIsCompatible(
+          dbRet.db,
+          setting,
+          this.nodeid,
+          currentVersionRange,
+          info
         );
-        this.remoteLockedAndDeviceNotAccepted = true;
-        this.remoteLocked = true;
-        return false;
-      } else if (ensure == "LOCKED") {
-        this.remoteLocked = true;
-      } else if (ensure == "NODE_CLEANED") {
-        if (ignoreCleanLock) {
-          this.remoteLocked = true;
-        } else {
+        if (ensure == "INCOMPATIBLE") {
+          Logger(
+            "The remote database has no compatibility with the running version. Please upgrade the plugin.",
+            LOG_LEVEL_NOTICE
+          );
+          return false;
+        } else if (ensure == "NODE_LOCKED") {
           Logger(
-            "The remote database has been cleaned up. Fetch rebuilt DB, explicit unlocking or chunk clean-up is required.",
+            "The remote database has been rebuilt or corrupted since we have synchronized last time. Fetch rebuilt DB, explicit unlocking or chunk clean-up is required.",
             LOG_LEVEL_NOTICE
           );
           this.remoteLockedAndDeviceNotAccepted = true;
           this.remoteLocked = true;
-          this.remoteCleaned = true;
+          return false;
+        } else if (ensure == "LOCKED") {
+          this.remoteLocked = true;
+        } else if (ensure == "NODE_CLEANED") {
+          if (ignoreCleanLock) {
+            this.remoteLocked = true;
+          } else {
+            Logger(
+              "The remote database has been cleaned up. Fetch rebuilt DB, explicit unlocking or chunk clean-up is required.",
+              LOG_LEVEL_NOTICE
+            );
+            this.remoteLockedAndDeviceNotAccepted = true;
+            this.remoteLocked = true;
+            this.remoteCleaned = true;
+            return false;
+          }
+        } else if (ensure == "OK") {
+        } else if (ensure[0] == "MISMATCHED") {
+          Logger(this.translate("liveSyncReplicator.mismatchedTweakDetected"), LOG_LEVEL_NOTICE);
+          this.tweakSettingsMismatched = true;
+          this.preferredTweakValue = ensure[1];
           return false;
         }
-      } else if (ensure == "OK") {
-      } else if (ensure[0] == "MISMATCHED") {
-        Logger(this.translate("liveSyncReplicator.mismatchedTweakDetected"), LOG_LEVEL_NOTICE);
-        this.tweakSettingsMismatched = true;
-        this.preferredTweakValue = ensure[1];
-        return false;
+      }
+      const syncOptionBase = {
+        batches_limit: setting.batches_limit,
+        batch_size: setting.batch_size
+      };
+      syncOptionBase.push = {};
+      if (setting.readChunksOnline) {
+        syncOptionBase.pull = { ...selectorOnDemandPull };
+      }
+      const syncOption = keepAlive ? { live: true, retry: true, heartbeat: setting.useTimeouts ? false : 3e4, ...syncOptionBase } : { ...syncOptionBase };
+      const connection = { db: dbRet.db, info: dbRet.info, syncOptionBase, syncOption };
+      ownershipTransferred = true;
+      return connection;
+    } finally {
+      if (!ownershipTransferred) {
+        await this.closeRemoteDatabase(dbRet.db);
       }
     }
-    const syncOptionBase = {
-      batches_limit: setting.batches_limit,
-      batch_size: setting.batch_size
-    };
-    syncOptionBase.push = {};
-    if (setting.readChunksOnline) {
-      syncOptionBase.pull = { ...selectorOnDemandPull };
-    }
-    const syncOption = keepAlive ? { live: true, retry: true, heartbeat: setting.useTimeouts ? false : 3e4, ...syncOptionBase } : { ...syncOptionBase };
-    return { db: dbRet.db, info: dbRet.info, syncOptionBase, syncOption };
   }
   async openContinuousReplication(setting, showResult, retrying) {
     const next = await shareRunningResult("continuousReplication", async () => {

package/dist/serviceFeatures/offlineScanner.d.ts

@@ -1,14 +1,135 @@
-import { type FilePathWithPrefix, type FilePathWithPrefixLC, type MetaEntry, type UXFileInfoStub, type ObsidianLiveSyncSettings, type LOG_LEVEL } from "../common/types.js";
+import { type DocumentID, type FilePathWithPrefix, type FilePathWithPrefixLC, type MetaEntry, type UXFileInfoStub, type ObsidianLiveSyncSettings, type LOG_LEVEL } from "../common/types.js";
 import { type LogFunction } from "../services/lib/logUtils.js";
 import type { NecessaryServices } from "../interfaces/ServiceModule.js";
 import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
+/**
+ * Outcome of processing one storage/database pair during an offline scan.
+ *
+ * A skipped pair is intentionally left unchanged by scanner policy. It is not
+ * a scan failure, but it must not receive success side effects which would
+ * claim that database content was reflected to storage.
+ */
+export declare const FilePairProcessResults: {
+    readonly COMPLETED: "completed";
+    readonly SKIPPED: "skipped";
+    readonly FAILED: "failed";
+};
+export type FilePairProcessResult = (typeof FilePairProcessResults)[keyof typeof FilePairProcessResults];
+export declare const MetadataDocumentNamespaces: {
+    readonly NORMAL: "normal";
+    readonly INTERNAL: "internal";
+    readonly CUSTOMISATION: "customisation";
+    readonly PLUGIN_STORAGE: "plugin-storage";
+};
+export type MetadataDocumentNamespace = (typeof MetadataDocumentNamespaces)[keyof typeof MetadataDocumentNamespaces];
+export declare const MetadataDocumentIdentityStatuses: {
+    readonly CONSISTENT: "consistent";
+    readonly EXCLUDED: "excluded";
+    readonly UNRESOLVED: "unresolved";
+};
+export declare const OfflineScanUnresolvedReasons: {
+    readonly DOCUMENT_ID_MISMATCH: "document-id-mismatch";
+    readonly NAMESPACE_MISMATCH: "namespace-mismatch";
+};
+export interface OfflineScanUnresolvedDiagnostic {
+    reason: (typeof OfflineScanUnresolvedReasons)[keyof typeof OfflineScanUnresolvedReasons];
+    actualDocumentId: DocumentID;
+    declaredPath: FilePathWithPrefix;
+    expectedDocumentId?: DocumentID;
+    actualNamespace: MetadataDocumentNamespace;
+    declaredPathNamespace: MetadataDocumentNamespace;
+}
+export type MetadataDocumentIdentityInspection = {
+    status: typeof MetadataDocumentIdentityStatuses.CONSISTENT;
+    actualDocumentId: DocumentID;
+    declaredPath: FilePathWithPrefix;
+    expectedDocumentId: DocumentID;
+} | {
+    status: typeof MetadataDocumentIdentityStatuses.EXCLUDED;
+    actualDocumentId: DocumentID;
+    declaredPath: FilePathWithPrefix;
+    namespace: Exclude<MetadataDocumentNamespace, "normal">;
+} | {
+    status: typeof MetadataDocumentIdentityStatuses.UNRESOLVED;
+    diagnostic: OfflineScanUnresolvedDiagnostic;
+};
+export interface MetadataDocumentIdentityIssue {
+    inspection: Extract<MetadataDocumentIdentityInspection, {
+        status: typeof MetadataDocumentIdentityStatuses.UNRESOLVED;
+    }>;
+    sourceRevision: string | null;
+    logicallyDeleted: boolean;
+    conflictRevisions: string[];
+    repairAvailable: boolean;
+    targetAlreadyPresent: boolean;
+    ordinaryPathAvailable: boolean;
+}
+export declare const MetadataDocumentRepairResults: {
+    readonly COMPLETED: "completed";
+    readonly STALE: "stale";
+    readonly BLOCKED: "blocked";
+    readonly FAILED: "failed";
+};
+export interface MetadataDocumentRepairRequest {
+    actualDocumentId: DocumentID;
+    expectedDocumentId: DocumentID;
+    sourceRevision: string;
+}
+export type MetadataDocumentRepairResult = {
+    status: (typeof MetadataDocumentRepairResults)[keyof typeof MetadataDocumentRepairResults];
+    actualDocumentId: DocumentID;
+    expectedDocumentId: DocumentID;
+    sourceRevision: string;
+    targetCreated: boolean;
+    message?: string;
+};
+/**
+ * Classify the logical Metadata namespace before platform path filtering.
+ *
+ * Internal, customisation, and plug-in storage entries are owned by their
+ * dedicated synchronisation paths. The ordinary file scanner handles only the
+ * normal namespace.
+ */
+export declare function getMetadataDocumentNamespace(value: string): MetadataDocumentNamespace;
+/**
+ * Inspect whether a Metadata document identifier still represents its
+ * declared path under the active path settings.
+ *
+ * This check deliberately runs before any scanner action. A mismatch can be
+ * caused by an old path-obfuscation key, a case-sensitivity change, or a
+ * historical rename. Selecting a repair without additional evidence would be
+ * destructive, so callers must leave an unresolved document unchanged. A
+ * separate consistent document for the same logical path may still proceed
+ * through ordinary path-based handling.
+ */
+export declare function inspectMetadataDocumentIdentity(host: NecessaryServices<"path", never>, doc: MetaEntry): Promise<MetadataDocumentIdentityInspection>;
+/**
+ * Enumerate Metadata from its actual local document IDs and report only the
+ * entries which ordinary path-based inspection cannot address.
+ *
+ * Path-addressed file inspection cannot discover a document whose stored path
+ * derives a different ID. The report therefore provides the evidence needed
+ * by an existing host-owned repair inspector without adding a batch-repair
+ * policy to the scanner.
+ */
+export declare function inspectMetadataDocumentIdentities(host: NecessaryServices<"path" | "database" | "setting" | "vault", never>): Promise<MetadataDocumentIdentityIssue[]>;
+/**
+ * Repair one previously inspected normal-file Metadata identity.
+ *
+ * The request identifies the exact source revision which the operator
+ * approved. Every precondition is inspected again under the same ordered
+ * document locks as file-event handling. The target is created and verified
+ * before the source receives a hard tombstone. If interruption leaves that
+ * exact target in place, the same single-entry action can safely be repeated.
+ */
+export declare function repairMetadataDocumentIdentity(host: NecessaryServices<"path" | "database" | "setting" | "vault" | "keyValueDB", never>, request: MetadataDocumentRepairRequest): Promise<MetadataDocumentRepairResult>;
 /**
  * Collect deleted files that have expired according to retention policy.
  * @param host Services container
  * @param log Logging function
  * @returns Array of expired deletion history
  */
-export declare function collectDeletedFiles(host: NecessaryServices<"setting" | "database", never>, log: LogFunction): Promise<void>;
+export declare function collectDeletedFiles(host: NecessaryServices<"setting" | "database" | "path", never>, log: LogFunction): Promise<void>;
 /**
  * Get the file path from a meta entry.
  * This is a helper function to extract path from various document types.
@@ -23,7 +144,7 @@ export declare function getPathFromEntry(host: NecessaryServices<"path", never>,
  * @param file Storage file information
  * @param doc Database entry
  */
-export declare function syncFileBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, doc: MetaEntry): Promise<void>;
+export declare function syncFileBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, doc: MetaEntry): Promise<FilePairProcessResult>;
 export declare function canProceedScan(host: NecessaryServices<"keyValueDB" | "setting", never>, errorManager: UnresolvedErrorManager, log: LogFunction, showingNotice?: boolean, ignoreSuspending?: boolean): boolean;
 /**
  * Convert file path to lower case if the settings indicate that filename case should be handled insensitively.
@@ -40,15 +161,14 @@ export declare function collectFilesOnStorage(host: NecessaryServices<"vault", "
     storageFileNameCI2CS: Record<FilePathWithPrefixLC, FilePathWithPrefix>;
 }>;
 export declare function collectDatabaseFiles(host: NecessaryServices<"database" | "vault" | "path", never>, settings: ObsidianLiveSyncSettings, log: LogFunction, showingNotice: boolean): Promise<{
-    databaseFileNameMap: {
-        [k: string]: MetaEntry;
-    };
+    databaseFileNameMap: Record<FilePathWithPrefix, MetaEntry>;
     databaseFileNames: FilePathWithPrefix[];
-    databaseFileNameCI2CS: Record<FilePathWithPrefix, FilePathWithPrefixLC>;
+    databaseFileNameCI2CS: Record<FilePathWithPrefixLC, FilePathWithPrefix>;
+    quarantinedFileNamesLC: Set<FilePathWithPrefixLC>;
 }>;
-export declare function updateToDatabase(host: NecessaryServices<"vault", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, file: UXFileInfoStub): Promise<void>;
-export declare function updateToStorage(host: NecessaryServices<"vault" | "path", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, w: MetaEntry): Promise<void>;
-export declare function syncStorageAndDatabase(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, logLevel: LOG_LEVEL, doc: MetaEntry): Promise<void>;
+export declare function updateToDatabase(host: NecessaryServices<"vault", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, file: UXFileInfoStub): Promise<FilePairProcessResult>;
+export declare function updateToStorage(host: NecessaryServices<"vault" | "path", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, w: MetaEntry): Promise<FilePairProcessResult>;
+export declare function syncStorageAndDatabase(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, logLevel: LOG_LEVEL, doc: MetaEntry): Promise<FilePairProcessResult>;
 export declare const FullScanModes: {
     readonly DB_APPLY: "db-apply";
     readonly NEWER_WINS: "newer-wins";
@@ -105,9 +225,18 @@ export declare function resolveFilePairAction(state: FilePairState, options: Ful
  * @param log Logging function
  * @param errorManager Error manager
  * @param options Full scan options
+ * @returns True when every pair completed or was deliberately skipped; false when any pair failed
  */
 export declare function synchroniseAllFilesBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, options: FullScanOptions): Promise<boolean>;
 export declare function normaliseFullScanOptions(showingNoticeOrOptions: Partial<FullScanOptions> | boolean | undefined, ignoreSuspending?: boolean): FullScanOptions;
+/**
+ * Remove one path from the Offline Scanner's durable last-seen state.
+ *
+ * Identity repair calls this before publishing a correctly addressed target.
+ * Otherwise an old record of local presence could make the next NEWER_WINS
+ * scan interpret that database-only target as a later local deletion.
+ */
+export declare function clearOfflineScannerLastSeen(host: NecessaryServices<"setting" | "keyValueDB", never>, path: FilePathWithPrefix): Promise<void>;
 /**
  * Perform a full scan and synchronisation between database and storage.
  * @param host Services container
@@ -115,7 +244,7 @@ export declare function normaliseFullScanOptions(showingNoticeOrOptions: Partial
  * @param errorManager Error manager
  * @param showingNotice Whether to show notices during scanning
  * @param ignoreSuspending Whether to ignore suspension settings
- * @returns True if scan completed successfully
+ * @returns True when the scan was permitted and no selected pair failed
  */
 export declare function performFullScan(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, options?: Partial<FullScanOptions>): Promise<boolean>;
 export declare function performFullScan(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, showingNotice?: boolean, ignoreSuspending?: boolean): Promise<boolean>;

package/dist/serviceFeatures/offlineScanner.js

@@ -13,6 +13,296 @@ import { createInstanceLogFunction } from "../services/lib/logUtils.js";
 import { BASE_IS_NEW, EVEN, TARGET_IS_NEW } from "../common/models/shared.const.symbols.js";
 import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
 import { compatGlobal } from "../common/coreEnvFunctions.js";
+import { ICHeader, ICXHeader, PSCHeader } from "../common/models/fileaccess.const.js";
+import { serialized } from "octagonal-wheels/concurrency/lock";
+const FilePairProcessResults = {
+  COMPLETED: "completed",
+  SKIPPED: "skipped",
+  FAILED: "failed"
+};
+const MetadataDocumentNamespaces = {
+  NORMAL: "normal",
+  INTERNAL: "internal",
+  CUSTOMISATION: "customisation",
+  PLUGIN_STORAGE: "plugin-storage"
+};
+const MetadataDocumentIdentityStatuses = {
+  CONSISTENT: "consistent",
+  EXCLUDED: "excluded",
+  UNRESOLVED: "unresolved"
+};
+const OfflineScanUnresolvedReasons = {
+  DOCUMENT_ID_MISMATCH: "document-id-mismatch",
+  NAMESPACE_MISMATCH: "namespace-mismatch"
+};
+const MetadataDocumentRepairResults = {
+  COMPLETED: "completed",
+  STALE: "stale",
+  BLOCKED: "blocked",
+  FAILED: "failed"
+};
+function getMetadataDocumentNamespace(value) {
+  if (value.startsWith(ICXHeader)) return MetadataDocumentNamespaces.CUSTOMISATION;
+  if (value.startsWith(ICHeader)) return MetadataDocumentNamespaces.INTERNAL;
+  if (value.startsWith(PSCHeader)) return MetadataDocumentNamespaces.PLUGIN_STORAGE;
+  return MetadataDocumentNamespaces.NORMAL;
+}
+async function inspectMetadataDocumentIdentity(host, doc) {
+  const actualDocumentId = doc._id;
+  const declaredPath = getPathFromEntry(host, doc);
+  const actualNamespace = getMetadataDocumentNamespace(actualDocumentId);
+  const declaredPathNamespace = getMetadataDocumentNamespace(declaredPath);
+  if (actualNamespace !== MetadataDocumentNamespaces.NORMAL || declaredPathNamespace !== MetadataDocumentNamespaces.NORMAL) {
+    if (actualNamespace === declaredPathNamespace) {
+      return {
+        status: MetadataDocumentIdentityStatuses.EXCLUDED,
+        actualDocumentId,
+        declaredPath,
+        namespace: actualNamespace
+      };
+    }
+    return {
+      status: MetadataDocumentIdentityStatuses.UNRESOLVED,
+      diagnostic: {
+        reason: OfflineScanUnresolvedReasons.NAMESPACE_MISMATCH,
+        actualDocumentId,
+        declaredPath,
+        actualNamespace,
+        declaredPathNamespace
+      }
+    };
+  }
+  const expectedDocumentId = await host.services.path.path2id(declaredPath);
+  if (actualDocumentId !== expectedDocumentId) {
+    return {
+      status: MetadataDocumentIdentityStatuses.UNRESOLVED,
+      diagnostic: {
+        reason: OfflineScanUnresolvedReasons.DOCUMENT_ID_MISMATCH,
+        actualDocumentId,
+        declaredPath,
+        expectedDocumentId,
+        actualNamespace,
+        declaredPathNamespace
+      }
+    };
+  }
+  return {
+    status: MetadataDocumentIdentityStatuses.CONSISTENT,
+    actualDocumentId,
+    declaredPath,
+    expectedDocumentId
+  };
+}
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value === null || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).filter(([, item]) => item !== void 0).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => [key, stableValue(item)])
+  );
+}
+function logicalMetadataPayload(doc) {
+  return stableValue({
+    path: doc.path,
+    ctime: doc.ctime,
+    mtime: doc.mtime,
+    size: doc.size,
+    type: doc.type,
+    children: [...doc.children],
+    eden: doc.eden ?? {},
+    deleted: Boolean(doc.deleted || doc._deleted)
+  });
+}
+function isExactMetadataCopy(source, target) {
+  return JSON.stringify(logicalMetadataPayload(source)) === JSON.stringify(logicalMetadataPayload(target));
+}
+async function inspectMetadataDocumentIdentities(host) {
+  const observations = [];
+  for await (const doc of host.services.database.localDatabase.findAllNormalDocs({ conflicts: true }) || []) {
+    if (!isMetaEntry(doc)) continue;
+    const inspection = await inspectMetadataDocumentIdentity(host, doc);
+    observations.push({ doc, inspection });
+  }
+  const expectedTargetIds = unique(
+    observations.flatMap(({ inspection }) => {
+      if (inspection.status !== MetadataDocumentIdentityStatuses.UNRESOLVED) return [];
+      const { diagnostic } = inspection;
+      if (diagnostic.reason !== OfflineScanUnresolvedReasons.DOCUMENT_ID_MISMATCH || diagnostic.expectedDocumentId === void 0) {
+        return [];
+      }
+      return [diagnostic.expectedDocumentId];
+    })
+  );
+  const targetRows = /* @__PURE__ */ new Map();
+  if (expectedTargetIds.length > 0) {
+    const result = await host.services.database.localDatabase.allDocsRaw({
+      keys: expectedTargetIds,
+      include_docs: true,
+      conflicts: true
+    });
+    for (const row of result.rows) targetRows.set(row.key, row);
+  }
+  const settings = host.services.setting.currentSettings();
+  const observationsByDocumentId = new Map(observations.map((observation) => [observation.doc._id, observation]));
+  const pathClaims = /* @__PURE__ */ new Map();
+  const targetClaims = /* @__PURE__ */ new Map();
+  for (const { doc, inspection } of observations) {
+    const declaredPath = inspection.status === MetadataDocumentIdentityStatuses.UNRESOLVED ? inspection.diagnostic.declaredPath : inspection.declaredPath;
+    const declaredNamespace = getMetadataDocumentNamespace(declaredPath);
+    if (declaredNamespace === MetadataDocumentNamespaces.NORMAL) {
+      const key = convertCase(settings, declaredPath);
+      const claims = pathClaims.get(key) ?? /* @__PURE__ */ new Set();
+      claims.add(doc._id);
+      pathClaims.set(key, claims);
+    }
+    if (inspection.status === MetadataDocumentIdentityStatuses.UNRESOLVED && inspection.diagnostic.reason === OfflineScanUnresolvedReasons.DOCUMENT_ID_MISMATCH && inspection.diagnostic.expectedDocumentId !== void 0) {
+      const claims = targetClaims.get(inspection.diagnostic.expectedDocumentId) ?? /* @__PURE__ */ new Set();
+      claims.add(doc._id);
+      targetClaims.set(inspection.diagnostic.expectedDocumentId, claims);
+    }
+  }
+  const entries = [];
+  for (const { doc, inspection } of observations) {
+    if (inspection.status !== MetadataDocumentIdentityStatuses.UNRESOLVED) continue;
+    const { diagnostic } = inspection;
+    let repairAvailable = false;
+    let targetAlreadyPresent = false;
+    let ordinaryPathAvailable = false;
+    if (diagnostic.reason === OfflineScanUnresolvedReasons.DOCUMENT_ID_MISMATCH && diagnostic.expectedDocumentId !== void 0) {
+      const expectedDocumentId = diagnostic.expectedDocumentId;
+      const normalisedPath = convertCase(settings, diagnostic.declaredPath);
+      const targetObservation = observationsByDocumentId.get(expectedDocumentId);
+      const targetPath = targetObservation?.inspection.status === MetadataDocumentIdentityStatuses.CONSISTENT ? targetObservation.inspection.declaredPath : void 0;
+      ordinaryPathAvailable = targetPath !== void 0 && convertCase(settings, targetPath) === normalisedPath && host.services.vault.isValidPath(targetPath) && !shouldBeIgnored(targetPath) && await host.services.vault.isTargetFile(targetPath);
+      const row = targetRows.get(expectedDocumentId);
+      const target = row?.doc;
+      const targetMetadata = target && isMetaEntry(target) ? target : void 0;
+      targetAlreadyPresent = Boolean(targetMetadata && isExactMetadataCopy(doc, targetMetadata));
+      const targetIsAvailable = !row || row.error === "not_found" || targetAlreadyPresent && !row?.value?.deleted && !targetMetadata?._deleted && !targetMetadata?.deleted && (targetMetadata?._conflicts?.length ?? 0) === 0;
+      const samePathClaims = pathClaims.get(normalisedPath) ?? /* @__PURE__ */ new Set();
+      const permittedExactPair = targetAlreadyPresent && samePathClaims.size === 2 && samePathClaims.has(doc._id) && samePathClaims.has(expectedDocumentId);
+      const pathIsUnambiguous = samePathClaims.size === 1 || permittedExactPair;
+      const targetIsUnambiguous = (targetClaims.get(expectedDocumentId)?.size ?? 0) === 1;
+      repairAvailable = Boolean(doc._rev) && !doc.deleted && !doc._deleted && (doc._conflicts?.length ?? 0) === 0 && host.services.vault.isValidPath(diagnostic.declaredPath) && await host.services.vault.isTargetFile(diagnostic.declaredPath) && pathIsUnambiguous && targetIsUnambiguous && targetIsAvailable;
+    }
+    entries.push({
+      inspection,
+      sourceRevision: doc._rev ?? null,
+      logicallyDeleted: Boolean(doc.deleted || doc._deleted),
+      conflictRevisions: [...doc._conflicts ?? []],
+      repairAvailable,
+      targetAlreadyPresent,
+      ordinaryPathAvailable
+    });
+  }
+  return entries;
+}
+function cloneEden(eden) {
+  return Object.fromEntries(
+    Object.entries(eden ?? {}).map(([id, chunk]) => [id, { data: chunk.data, epoch: chunk.epoch }])
+  );
+}
+function createReaddressedMetadata(source, expectedDocumentId) {
+  return {
+    _id: expectedDocumentId,
+    path: source.path,
+    ctime: source.ctime,
+    mtime: source.mtime,
+    size: source.size,
+    type: source.type,
+    children: [...source.children],
+    eden: cloneEden(source.eden),
+    ...source.deleted === void 0 ? {} : { deleted: source.deleted }
+  };
+}
+async function serializedByMetadataDocumentIds(documentIds, callback) {
+  const lockKeys = [...new Set(documentIds)].sort().map((documentId) => `processFileEvent-${documentId}`);
+  const acquire = async (index) => {
+    const key = lockKeys[index];
+    if (key === void 0) return await callback();
+    return await serialized(key, () => acquire(index + 1));
+  };
+  return await acquire(0);
+}
+function findRepairEntry(entries, actualDocumentId) {
+  return entries.find(
+    ({ inspection }) => inspection.diagnostic.actualDocumentId === actualDocumentId
+  );
+}
+async function repairMetadataDocumentIdentity(host, request) {
+  const baseResult = {
+    actualDocumentId: request.actualDocumentId,
+    expectedDocumentId: request.expectedDocumentId,
+    sourceRevision: request.sourceRevision,
+    targetCreated: false
+  };
+  return await serializedByMetadataDocumentIds(
+    [request.actualDocumentId, request.expectedDocumentId],
+    async () => {
+      let targetCreated = false;
+      try {
+        const entries = await inspectMetadataDocumentIdentities(host);
+        const entry = findRepairEntry(entries, request.actualDocumentId);
+        if (!entry || entry.sourceRevision !== request.sourceRevision || entry.inspection.diagnostic.reason !== OfflineScanUnresolvedReasons.DOCUMENT_ID_MISMATCH || entry.inspection.diagnostic.expectedDocumentId !== request.expectedDocumentId) {
+          return {
+            ...baseResult,
+            status: MetadataDocumentRepairResults.STALE,
+            message: "The inspected source revision or expected document ID has changed."
+          };
+        }
+        if (!entry.repairAvailable) {
+          return {
+            ...baseResult,
+            status: MetadataDocumentRepairResults.BLOCKED,
+            message: "The source no longer satisfies the repair preconditions."
+          };
+        }
+        const source = await host.services.database.localDatabase.getRaw(request.actualDocumentId, {
+          rev: request.sourceRevision,
+          conflicts: true
+        });
+        if (!isMetaEntry(source) || source._rev !== request.sourceRevision) {
+          return {
+            ...baseResult,
+            status: MetadataDocumentRepairResults.STALE,
+            message: "The source revision changed during repair validation."
+          };
+        }
+        await clearOfflineScannerLastSeen(host, entry.inspection.diagnostic.declaredPath);
+        if (!entry.targetAlreadyPresent) {
+          await host.services.database.localDatabase.putRaw(
+            createReaddressedMetadata(source, request.expectedDocumentId)
+          );
+          targetCreated = true;
+        }
+        const target = await host.services.database.localDatabase.getRaw(
+          request.expectedDocumentId,
+          { conflicts: true }
+        );
+        if (!isMetaEntry(target) || target.deleted || target._deleted || (target._conflicts?.length ?? 0) > 0 || !isExactMetadataCopy(source, target)) {
+          return {
+            ...baseResult,
+            targetCreated,
+            status: MetadataDocumentRepairResults.FAILED,
+            message: "The repair target could not be verified as an exact local copy."
+          };
+        }
+        await host.services.database.localDatabase.removeRaw(request.actualDocumentId, request.sourceRevision);
+        return {
+          ...baseResult,
+          targetCreated,
+          status: MetadataDocumentRepairResults.COMPLETED
+        };
+      } catch (error) {
+        return {
+          ...baseResult,
+          targetCreated,
+          status: MetadataDocumentRepairResults.FAILED,
+          message: error instanceof Error ? error.message : `${error}`
+        };
+      }
+    }
+  );
+}
 async function collectDeletedFiles(host, log) {
   const limitDays = host.services.setting.currentSettings().automaticallyDeleteMetadataOfDeletedFiles;
   if (limitDays <= 0) return;
@@ -22,6 +312,16 @@ async function collectDeletedFiles(host, log) {
   for await (const doc of host.services.database.localDatabase.findAllDocs({ conflicts: true })) {
     if (isAnyNote(doc)) {
       if (doc.deleted && doc.mtime - limit < 0) {
+        if (isMetaEntry(doc)) {
+          const identity = await inspectMetadataDocumentIdentity(host, doc);
+          if (identity.status === MetadataDocumentIdentityStatuses.UNRESOLVED) {
+            log(
+              `Expired deletion history has an unresolved Metadata identity and will be left unchanged: ${identity.diagnostic.declaredPath} (${identity.diagnostic.reason})`,
+              LOG_LEVEL_INFO
+            );
+            continue;
+          }
+        }
         notes.push({
           path: doc.path,
           mtime: doc.mtime,
@@ -59,13 +359,14 @@ async function syncFileBetweenDBandStorage(host, log, file, doc) {
       if (!host.services.vault.isFileSizeTooLarge(file.stat.size)) {
         log("STORAGE -> DB :" + file.path);
         await host.serviceModules.fileHandler.storeFileToDB(file);
+        return FilePairProcessResults.COMPLETED;
       } else {
         log(
           `STORAGE -> DB : ${file.path} has been skipped due to file size exceeding the limit`,
           LOG_LEVEL_NOTICE
         );
+        return FilePairProcessResults.SKIPPED;
       }
-      break;
     case TARGET_IS_NEW:
       if (!host.services.vault.isFileSizeTooLarge(doc.size)) {
         log("STORAGE <- DB :" + docPath);
@@ -74,21 +375,24 @@ async function syncFileBetweenDBandStorage(host, log, file, doc) {
             file: file.path,
             automated: true
           });
+          return FilePairProcessResults.COMPLETED;
         } else {
           log(`STORAGE <- DB : Cloud not read ${file.path}, possibly deleted`, LOG_LEVEL_NOTICE);
+          return FilePairProcessResults.FAILED;
         }
       } else {
         log(
           `STORAGE <- DB : ${file.path} has been skipped due to file size exceeding the limit`,
           LOG_LEVEL_NOTICE
         );
+        return FilePairProcessResults.SKIPPED;
       }
-      break;
     case EVEN:
       log("STORAGE == DB :" + file.path, LOG_LEVEL_DEBUG);
-      break;
+      return FilePairProcessResults.COMPLETED;
     default:
       log("STORAGE ?? DB :" + file.path + " Something got weird");
+      return FilePairProcessResults.FAILED;
   }
 }
 function canProceedScan(host, errorManager, log, showingNotice = false, ignoreSuspending = false) {
@@ -138,6 +442,8 @@ async function collectFilesOnStorage(host, settings, log) {
 async function collectDatabaseFiles(host, settings, log, showingNotice) {
   log("Collecting local files on the DB", LOG_LEVEL_VERBOSE);
   const _DBEntries = [];
+  const unresolvedFileNamesLC = /* @__PURE__ */ new Set();
+  const resolvableFileNamesLC = /* @__PURE__ */ new Set();
   let count = 0;
   for await (const doc of host.services.database.localDatabase.findAllNormalDocs({ conflicts: true }) || []) {
     count++;
@@ -147,28 +453,54 @@ async function collectDatabaseFiles(host, settings, log, showingNotice) {
         showingNotice ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO,
         "syncAll"
       );
-    const path = getPathFromEntry(host, doc);
+    if (!isMetaEntry(doc)) {
+      const documentId = doc._id ?? "unknown";
+      log(`Invalid Metadata entry: ${documentId}`, LOG_LEVEL_INFO);
+      continue;
+    }
+    const identity = await inspectMetadataDocumentIdentity(host, doc);
+    if (identity.status === MetadataDocumentIdentityStatuses.EXCLUDED) {
+      continue;
+    }
+    if (identity.status === MetadataDocumentIdentityStatuses.UNRESOLVED) {
+      const { diagnostic } = identity;
+      const unresolvedKey = convertCase(settings, stripAllPrefixes(diagnostic.declaredPath));
+      unresolvedFileNamesLC.add(unresolvedKey);
+      log(
+        `Metadata identity is unresolved and will be left unchanged: ${diagnostic.declaredPath} (${diagnostic.reason})`,
+        LOG_LEVEL_INFO
+      );
+      continue;
+    }
+    const path = identity.declaredPath;
     if (host.services.vault.isValidPath(path) && !shouldBeIgnored(path) && await host.services.vault.isTargetFile(path)) {
-      if (!isMetaEntry(doc)) {
-        log(`Invalid entry: ${path}`, LOG_LEVEL_INFO);
-        continue;
-      }
       _DBEntries.push(doc);
+      resolvableFileNamesLC.add(convertCase(settings, stripAllPrefixes(path)));
     }
   }
   const databaseFileNameMap = Object.fromEntries(_DBEntries.map((e) => [getPathFromEntry(host, e), e]));
   const databaseFileNames = Object.keys(databaseFileNameMap);
   const databaseFileNameCapsPair = databaseFileNames.map((e) => [e, convertCase(settings, e)]);
   const databaseFileNameCI2CS = Object.fromEntries(databaseFileNameCapsPair.map((e) => [e[1], e[0]]));
-  return { databaseFileNameMap, databaseFileNames, databaseFileNameCI2CS };
+  const quarantinedFileNamesLC = new Set(
+    [...unresolvedFileNamesLC].filter((path) => !resolvableFileNamesLC.has(path))
+  );
+  return {
+    databaseFileNameMap,
+    databaseFileNames,
+    databaseFileNameCI2CS,
+    quarantinedFileNamesLC
+  };
 }
 async function updateToDatabase(host, log, logLevel, file) {
   if (!host.services.vault.isFileSizeTooLarge(file.stat.size)) {
     const path = file.path;
     await host.serviceModules.fileHandler.storeFileToDB(file);
     host.services.context.events.emitEvent("event-file-changed", { file: path, automated: true });
+    return FilePairProcessResults.COMPLETED;
   } else {
     log(`UPDATE DATABASE: ${file.path} has been skipped due to file size exceeding the limit`, logLevel);
+    return FilePairProcessResults.SKIPPED;
   }
 }
 async function updateToStorage(host, log, logLevel, w) {
@@ -177,35 +509,41 @@ async function updateToStorage(host, log, logLevel, w) {
     if (!host.services.vault.isFileSizeTooLarge(w.size)) {
       if ((w._conflicts?.length ?? 0) > 0) {
         log(`UPDATE STORAGE: ${path} has conflicts. skipped (x)`, LOG_LEVEL_INFO);
-        return;
+        return FilePairProcessResults.SKIPPED;
       }
-      await host.serviceModules.fileHandler.dbToStorage(path, null, true);
+      const reflected = await host.serviceModules.fileHandler.dbToStorage(path, null, true);
+      if (!reflected) return FilePairProcessResults.FAILED;
       host.services.context.events.emitEvent("event-file-changed", {
         file: path,
         automated: true
       });
       log(`Check or pull from db:${path} OK`);
+      return FilePairProcessResults.COMPLETED;
     } else {
       log(`UPDATE STORAGE: ${path} has been skipped due to file size exceeding the limit`, logLevel);
+      return FilePairProcessResults.SKIPPED;
     }
   } else if (w) {
     log(`Deletion history skipped: ${path}`, LOG_LEVEL_VERBOSE);
+    return FilePairProcessResults.SKIPPED;
   } else {
     log(`entry not found: ${path}`);
+    return FilePairProcessResults.FAILED;
   }
 }
 async function syncStorageAndDatabase(host, log, file, logLevel, doc) {
   if ((doc._conflicts?.length ?? 0) > 0) {
     log(`SYNC DATABASE AND STORAGE: ${file.path} has conflicts. skipped`, LOG_LEVEL_INFO);
-    return;
+    return FilePairProcessResults.SKIPPED;
   }
   if (!host.services.vault.isFileSizeTooLarge(file.stat.size) && !host.services.vault.isFileSizeTooLarge(doc.size)) {
-    await syncFileBetweenDBandStorage(host, log, file, doc);
+    return await syncFileBetweenDBandStorage(host, log, file, doc);
   } else {
     log(
       `SYNC DATABASE AND STORAGE: ${getPathFromEntry(host, doc)} has been skipped due to file size exceeding the limit`,
       logLevel
     );
+    return FilePairProcessResults.SKIPPED;
   }
 }
 const FullScanModes = {
@@ -308,7 +646,7 @@ async function processFilePair(host, log, pair, options) {
   }
   if (doc && (doc._conflicts?.length ?? 0) > 0) {
     log(`SKIP ${options.mode}: ${path} has conflicts`, LOG_LEVEL_INFO);
-    return true;
+    return FilePairProcessResults.SKIPPED;
   }
   const state = getFilePairState(pair);
   let action = resolveFilePairAction(state, options);
@@ -328,32 +666,35 @@ async function processFilePair(host, log, pair, options) {
         if (!file) {
           throw new Error(`Missing storage file for ${path}`);
         }
-        await updateToDatabase(host, log, LOG_LEVEL_INFO, file);
-        return true;
+        return await updateToDatabase(host, log, LOG_LEVEL_INFO, file);
       case "update-storage":
         if (!doc) {
           throw new Error(`Missing database entry for ${path}`);
         }
-        await updateToStorage(host, log, LOG_LEVEL_INFO, doc);
-        updateFileMTimeInMap(host, fileMapKey, doc.mtime);
-        return true;
+        const updateStorageResult = await updateToStorage(host, log, LOG_LEVEL_INFO, doc);
+        if (updateStorageResult === FilePairProcessResults.COMPLETED) {
+          updateFileMTimeInMap(host, fileMapKey, doc.mtime);
+        }
+        return updateStorageResult;
       case "sync-newer":
         if (!file || !doc) {
           throw new Error(`Cannot compare freshness for ${path}`);
         }
-        await syncStorageAndDatabase(host, log, file, LOG_LEVEL_INFO, doc);
-        updateFileMTimeInMap(host, fileMapKey, Math.max(file.stat.mtime, doc.mtime));
-        return true;
+        const syncResult = await syncStorageAndDatabase(host, log, file, LOG_LEVEL_INFO, doc);
+        if (syncResult === FilePairProcessResults.COMPLETED) {
+          updateFileMTimeInMap(host, fileMapKey, Math.max(file.stat.mtime, doc.mtime));
+        }
+        return syncResult;
       case "delete-local":
         if (!file) {
           log(`DELETE LOCAL: ${path} is already absent from storage`, LOG_LEVEL_VERBOSE);
-          return true;
+          return FilePairProcessResults.COMPLETED;
         }
         log(`DELETE LOCAL: ${file.path}`, LOG_LEVEL_INFO);
         await host.serviceModules.storageAccess.delete(file.path, true);
         fileMaps.delete(fileMapKey);
         saveFileStatus(host);
-        return true;
+        return FilePairProcessResults.COMPLETED;
       case "delete-db": {
         if (!doc) {
           throw new Error(`Missing database entry for ${path}`);
@@ -363,22 +704,23 @@ async function processFilePair(host, log, pair, options) {
         if (dbDeleted) {
           fileMaps.delete(fileMapKey);
           saveFileStatus(host);
+          return FilePairProcessResults.COMPLETED;
         } else {
           log(
             `DELETE DATABASE did not delete ${path}; keeping last-seen record to avoid resurrecting the file`,
             LOG_LEVEL_NOTICE
           );
+          return FilePairProcessResults.FAILED;
         }
-        return true;
       }
       case "skip":
         log(`SKIP ${options.mode}: ${path} (${state})`, LOG_LEVEL_VERBOSE);
-        return true;
+        return FilePairProcessResults.SKIPPED;
     }
   } catch (ex) {
     log(`Error processing ${path} with action ${action}`, LOG_LEVEL_NOTICE);
     log(ex, LOG_LEVEL_VERBOSE);
-    return false;
+    return FilePairProcessResults.FAILED;
   }
 }
 async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, options) {
@@ -386,17 +728,15 @@ async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, o
   const showingNotice = options.showingNotice ?? false;
   await loadFileStatus(host);
   const { storageFileNameMap, storageFileNameCI2CS } = await collectFilesOnStorage(host, settings, log);
-  const { databaseFileNameMap, databaseFileNameCI2CS } = await collectDatabaseFiles(
-    host,
-    settings,
-    log,
-    showingNotice
-  );
+  const { databaseFileNameMap, databaseFileNameCI2CS, quarantinedFileNamesLC } = await collectDatabaseFiles(host, settings, log, showingNotice);
   const pairs = [];
   for (const fileNameLC of unique([
     ...Object.keys(storageFileNameCI2CS),
     ...Object.keys(databaseFileNameCI2CS)
   ])) {
+    if (quarantinedFileNamesLC.has(fileNameLC)) {
+      continue;
+    }
     const fileName = fileNameLC in storageFileNameCI2CS ? storageFileNameCI2CS[fileNameLC] : void 0;
     const file = fileName ? storageFileNameMap[fileName] : void 0;
     const databaseName = fileNameLC in databaseFileNameCI2CS ? databaseFileNameCI2CS[fileNameLC] : void 0;
@@ -405,7 +745,9 @@ async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, o
     pairs.push(pair);
   }
   log(`Total files to synchronise: ${pairs.length}`, LOG_LEVEL_VERBOSE, "syncAll");
-  let successCount = 0;
+  let completedCount = 0;
+  let skippedCount = 0;
+  let failedCount = 0;
   let processedCount = 0;
   for await (const result of withConcurrency(
     pairs,
@@ -415,14 +757,22 @@ async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, o
       } catch (ex) {
         log(`Error while synchronising files`, LOG_LEVEL_NOTICE);
         log(ex, LOG_LEVEL_VERBOSE);
-        return false;
+        return FilePairProcessResults.FAILED;
       }
     },
     10
   )) {
     processedCount++;
-    if (result) {
-      successCount++;
+    switch (result) {
+      case FilePairProcessResults.COMPLETED:
+        completedCount++;
+        break;
+      case FilePairProcessResults.SKIPPED:
+        skippedCount++;
+        break;
+      case FilePairProcessResults.FAILED:
+        failedCount++;
+        break;
     }
     if (processedCount % 25 === 0) {
       log(
@@ -433,12 +783,12 @@ async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, o
     }
   }
   log(
-    `Synchronisation completed: ${successCount}/${processedCount} files processed successfully`,
+    `Synchronisation completed: ${processedCount} files processed (${completedCount} completed, ${skippedCount} skipped, ${failedCount} failed)`,
     showingNotice ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO,
     "syncAll"
   );
   saveFileStatus(host, true);
-  return successCount === processedCount;
+  return failedCount === 0;
 }
 function normaliseFullScanOptions(showingNoticeOrOptions, ignoreSuspending = false) {
   if (typeof showingNoticeOrOptions === "object") {
@@ -454,21 +804,43 @@ function normaliseFullScanOptions(showingNoticeOrOptions, ignoreSuspending = fal
   };
 }
 let fileMaps = /* @__PURE__ */ new Map();
+const FILE_STATUS_MAP_KEY = "fileStatusMap";
+const FILE_STATUS_MAP_LOCK = "offlineScanner-fileStatusMap";
 async function loadFileStatus(host) {
-  const kvDB = host.services.keyValueDB.kvDB;
-  if (!kvDB?.get) {
-    fileMaps = /* @__PURE__ */ new Map();
-    return;
-  }
-  const mapItems = await kvDB.get("fileStatusMap") || {};
-  fileMaps = new Map(Object.entries(mapItems));
+  await serialized(FILE_STATUS_MAP_LOCK, async () => {
+    const kvDB = host.services.keyValueDB.kvDB;
+    if (!kvDB?.get) {
+      fileMaps = /* @__PURE__ */ new Map();
+      return;
+    }
+    const mapItems = await kvDB.get(FILE_STATUS_MAP_KEY) || {};
+    fileMaps = new Map(Object.entries(mapItems));
+  });
 }
 async function _saveFileStatus(host) {
-  const kvDB = host.services.keyValueDB.kvDB;
-  if (!kvDB?.set) {
-    return;
-  }
-  await kvDB.set("fileStatusMap", Object.fromEntries(fileMaps));
+  await serialized(FILE_STATUS_MAP_LOCK, async () => {
+    const kvDB = host.services.keyValueDB.kvDB;
+    if (!kvDB?.set) {
+      return;
+    }
+    await kvDB.set(FILE_STATUS_MAP_KEY, Object.fromEntries(fileMaps));
+  });
+}
+async function clearOfflineScannerLastSeen(host, path) {
+  const key = convertCase(host.services.setting.currentSettings(), path);
+  if (saveFileStatusTimeout !== null) {
+    compatGlobal.clearTimeout(saveFileStatusTimeout);
+    saveFileStatusTimeout = null;
+  }
+  await serialized(FILE_STATUS_MAP_LOCK, async () => {
+    fileMaps.delete(key);
+    const kvDB = host.services.keyValueDB.kvDB;
+    if (!kvDB?.set) return;
+    const persisted = kvDB.get ? await kvDB.get(FILE_STATUS_MAP_KEY) || {} : Object.fromEntries(fileMaps);
+    const next = { ...persisted, ...Object.fromEntries(fileMaps) };
+    delete next[key];
+    await kvDB.set(FILE_STATUS_MAP_KEY, next);
+  });
 }
 let saveFileStatusTimeout = null;
 function saveFileStatus(host, immediate = false) {
@@ -513,7 +885,7 @@ async function performFullScan(host, log, errorManager, showingNoticeOrOptions =
   log("Initialize and checking database files");
   log("Checking deleted files");
   await collectDeletedFiles(host, log);
-  await synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, options);
+  const scanResult = await synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, options);
   log("Initialized, NOW TRACKING!");
   if (!isInitialized) {
     await host.services.keyValueDB.kvDB.set("initialized", true);
@@ -521,7 +893,7 @@ async function performFullScan(host, log, errorManager, showingNoticeOrOptions =
   if (showingNotice) {
     log("Initialize done!", LOG_LEVEL_NOTICE, "syncAll");
   }
-  return true;
+  return scanResult;
 }
 function useOfflineScanner(host) {
   const log = createInstanceLogFunction("SF:OfflineScanner", host.services.API);
@@ -534,16 +906,26 @@ function useOfflineScanner(host) {
 export {
   ExtraOnLocal,
   ExtraOnRemote,
+  FilePairProcessResults,
   FullScanModes,
+  MetadataDocumentIdentityStatuses,
+  MetadataDocumentNamespaces,
+  MetadataDocumentRepairResults,
+  OfflineScanUnresolvedReasons,
   canProceedScan,
+  clearOfflineScannerLastSeen,
   collectDatabaseFiles,
   collectDeletedFiles,
   collectFilesOnStorage,
   convertCase,
   getFilePairState,
+  getMetadataDocumentNamespace,
   getPathFromEntry,
+  inspectMetadataDocumentIdentities,
+  inspectMetadataDocumentIdentity,
   normaliseFullScanOptions,
   performFullScan,
+  repairMetadataDocumentIdentity,
   resolveFilePairAction,
   syncFileBetweenDBandStorage,
   syncStorageAndDatabase,

package/docs/development.md

@@ -57,7 +57,7 @@ The settings lifecycle has an additional focused unit table in `src/common/model
 
 The multiple-remote profile contract has focused unit coverage in `src/serviceFeatures/remoteConfig.unit.spec.ts`. Extend it whenever profile identity, generated display names, activation, P2P selection, URI serialisation, or legacy migration changes. New hosts should import the reviewed primitives through `/remote-configurations`; `compat/serviceFeatures/remoteConfig` remains the wider migration surface used by existing clients.
 
-The full offline scanner applies both the host's target-file policy and Commonlib's built-in `shouldBeIgnored` policy before constructing storage/database pairs. This keeps legacy LiveSync log files and flag files outside ordinary create, restore, and delete decisions even when a host accepts their file extension. Lower-level write guards remain a defence for direct calls; they are not the normal full-scan filter. Extend both storage-collection and database-collection tests whenever the built-in exclusions change.
+The full offline scanner applies both the host's target-file policy and Commonlib's built-in `shouldBeIgnored` policy before constructing storage/database pairs. This keeps legacy LiveSync log files and flag files outside ordinary create, restore, and delete decisions even when a host accepts their file extension. Lower-level write guards remain a defence for direct calls; they are not the normal full-scan filter. The complete pair-state decision matrix and database-to-storage reflection result contract are documented in [Full offline scan](offline-scanner.md). Extend that document, the Cartesian action test, and both collection-side tests whenever the policy changes.
 
 The revision-tree safety rules are documented in [Conflict resolution and file provenance](conflict-resolution.md). `ConflictManager.unit.spec.ts` owns common-ancestor and conservative merge behaviour, deterministic pair selection for multiple live leaves, and reconstruction from the committed tree between stages. `ServiceDatabaseFileAccessBase.unit.spec.ts` owns all-branch content discovery, short-circuiting history existence checks after an exact match, and exact-revision logical deletion. `ServiceFileHandlerBase.unit.spec.ts` owns the injected provenance policy for edit, deletion, and rename operations, together with user-selected reflection, child creation, strict matching, matching-provenance cleanup after exact branch deletion, and stale-revision refusal. `LiveSyncLocalDB.unit.spec.ts` owns chunk reachability across current winners, shared chunks, live conflicts, available merge ancestry, conflict resolution, and PouchDB replication of collection and recreation. Extend the relevant sides when changing conflict resolution, compaction handling, provenance, chunk collection, or database-to-storage overwrite protection.
 

package/docs/proven-in-use.md

@@ -22,6 +22,8 @@ Commonlib's injected CouchDB tests verify that a mixed remote chunk batch preser
 
 Commonlib's remote-preference result contract distinguishes available synchronisation settings, a remote which has not stored those settings yet, a failed read, and a remote type which does not support central preferences. Focused CouchDB and Object Storage tests cover absent milestone data separately from transport failures, while Self-hosted LiveSync owns the initialisation choices, cancellation policy, and user-facing explanation.
 
+Commonlib's full offline scanner distinguishes completed, deliberately skipped, and failed storage/database pairs. Before pair construction, it withholds Metadata whose actual document ID disagrees with its recorded path, without reflection, deletion, or last-seen side effects. A consistently addressed entry for the same logical path continues through the established path-based flow; only a path without such an entry also withholds storage processing. The read-only actual-ID Inspector and separately invoked one-entry repair retain ambiguous states for review, revalidate an exact source revision, verify a target-first copy, and preserve the source on failure. Self-hosted LiveSync keeps the existing Fast Setup aggregate policy and owns confirmation and presentation in its file/database repair interface.
+
 Most replication and storage services used by the plug-in still enter through explicit `compat/*` paths. Those imports prove that the published compatibility boundary supports the current migration; they are not examples of a finished high-level client API.
 
 The plug-in's manual onboarding and Remote Databases pane use the focused `/remote-configurations` entry to create opaque profile IDs, retain user-visible names, and select main and P2P remotes. Commonlib owns the in-memory profile result contract; Self-hosted LiveSync adds dialogue, Setup URI classification, Fetch or Rebuild scheduling, persistence, restart ordering, and real-Obsidian presentation checks.
@@ -38,6 +40,8 @@ The CLI filesystem composition receives a configured base directory and construc
 
 The maintained CLI checks include unit tests, Deno-driven CLI E2E, Compose-based compatibility runs, and the CLI-to-real-Obsidian synchronisation scenario in `test/e2e-obsidian/scripts/cli-to-obsidian-sync.ts`. The latter is the strongest current evidence that the CLI and plug-in compose compatible Commonlib behaviour across two hosts.
 
+The CLI mirror command returns Commonlib's full-scan aggregate, and daemon start-up stops when that aggregate reports an actual pair failure. Deliberately skipped pairs remain a successful scan result. Commonlib owns the pair classification and aggregate; the CLI owns its command and process policy.
+
 ## WebApp
 
 WebApp receives an already authorised `FileSystemDirectoryHandle` from its host and constructs `FileSystemAccessStorageAdapter` inside `src/apps/webapp/adapters/FSAPIFileSystemAdapter.ts`. The adapter does not call `showDirectoryPicker()`, choose a directory, or persist the handle. This is the maintained application example for the browser entry's root-ownership rule.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "license": "MIT",