@vrtmrz/livesync-commonlib 0.1.11 → 0.1.13

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/serviceFeatures/offlineScanner.d.ts

@@ -1,4 +1,4 @@
-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";
@@ -15,13 +15,121 @@ export declare const FilePairProcessResults: {
     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.
@@ -53,11 +161,10 @@ 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<FilePairProcessResult>;
 export declare function updateToStorage(host: NecessaryServices<"vault" | "path", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, w: MetaEntry): Promise<FilePairProcessResult>;
@@ -122,6 +229,14 @@ export declare function resolveFilePairAction(state: FilePairState, options: Ful
  */
 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

package/dist/serviceFeatures/offlineScanner.js

@@ -13,11 +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;
@@ -27,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,
@@ -147,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++;
@@ -156,20 +453,44 @@ 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)) {
@@ -407,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;
@@ -485,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) {
@@ -567,15 +908,24 @@ export {
   ExtraOnRemote,
   FilePairProcessResults,
   FullScanModes,
+  MetadataDocumentIdentityStatuses,
+  MetadataDocumentNamespaces,
+  MetadataDocumentRepairResults,
+  OfflineScanUnresolvedReasons,
   canProceedScan,
+  clearOfflineScannerLastSeen,
   collectDatabaseFiles,
   collectDeletedFiles,
   collectFilesOnStorage,
   convertCase,
   getFilePairState,
+  getMetadataDocumentNamespace,
   getPathFromEntry,
+  inspectMetadataDocumentIdentities,
+  inspectMetadataDocumentIdentity,
   normaliseFullScanOptions,
   performFullScan,
+  repairMetadataDocumentIdentity,
   resolveFilePairAction,
   syncFileBetweenDBandStorage,
   syncStorageAndDatabase,