@vrtmrz/livesync-commonlib 0.1.42 → 0.1.43

package/dist/diagnostics/usage.js

@@ -0,0 +1,241 @@
+function asRecord(value) {
+  return value;
+}
+function getRevisionNumber(revision) {
+  const generation = revision.split("-")[0];
+  return `${generation ? Number.parseInt(generation) : 0}`;
+}
+function getRevisionHash(revision) {
+  const hash = revision.split("-")[1];
+  if (hash === void 0) throw new Error("invalid revision");
+  return hash.substring(0, 6);
+}
+function getRevisionInfos(value) {
+  if (!Array.isArray(value)) return [];
+  return value;
+}
+function getChildren(value) {
+  const children = value ?? [];
+  if (!Array.isArray(children) || !children.every((child) => typeof child === "string")) {
+    throw new Error("invalid chunk references");
+  }
+  return new Set(children);
+}
+function getStringField(value) {
+  if (typeof value !== "string") throw new Error("invalid document field");
+  return value;
+}
+async function analyseDatabaseUsage(options) {
+  const { source, signal, onProgress } = options;
+  const errors = [];
+  const documentMap = /* @__PURE__ */ new Map();
+  const chunkMap = /* @__PURE__ */ new Map();
+  const progress = { idsProcessed: 0, revisionsProcessed: 0 };
+  let startUpdateSeq;
+  let endUpdateSeq;
+  let enumerationFailed = false;
+  const reportProgress = () => onProgress?.({ ...progress });
+  const isCancelled = () => signal?.aborted === true;
+  let cancelled = isCancelled();
+  if (!cancelled) {
+    try {
+      const info = await source.info();
+      startUpdateSeq = info.update_seq;
+      if (startUpdateSeq === void 0) errors.push({ code: "start_update_seq_unavailable" });
+    } catch {
+      errors.push({ code: "start_info_read_failed" });
+    }
+    if (isCancelled()) cancelled = true;
+  }
+  try {
+    if (!cancelled && !isCancelled()) {
+      for await (const id of source.enumerateIds()) {
+        if (isCancelled()) {
+          cancelled = true;
+          break;
+        }
+        let revisionInfos = [];
+        let revisionList;
+        let revisionListReadFailed = false;
+        try {
+          revisionList = await source.get(id, { revs: true, revs_info: true, conflicts: true });
+        } catch {
+          if (!isCancelled()) {
+            errors.push({ code: "revision_list_read_failed", id });
+            revisionListReadFailed = true;
+          }
+        }
+        if (isCancelled()) {
+          cancelled = true;
+          break;
+        }
+        if (revisionList) revisionInfos = getRevisionInfos(asRecord(revisionList)._revs_info);
+        else if (!revisionListReadFailed) {
+          errors.push({ code: "revision_list_read_failed", id });
+        }
+        progress.idsProcessed++;
+        reportProgress();
+        for (const revisionInfo of revisionInfos) {
+          if (isCancelled()) {
+            cancelled = true;
+            break;
+          }
+          if (revisionInfo.status !== "available") continue;
+          const revision = typeof revisionInfo.rev === "string" ? revisionInfo.rev : void 0;
+          if (revision === void 0) {
+            errors.push({ code: "revision_document_invalid", id });
+            continue;
+          }
+          progress.revisionsProcessed++;
+          let rawDocument;
+          try {
+            rawDocument = await source.get(id, { rev: revision });
+          } catch {
+            if (isCancelled()) {
+              cancelled = true;
+              reportProgress();
+              break;
+            }
+            errors.push({ code: "revision_read_failed", id, revision });
+            reportProgress();
+            continue;
+          }
+          if (isCancelled()) {
+            cancelled = true;
+            reportProgress();
+            break;
+          }
+          if (!rawDocument) {
+            errors.push({ code: "revision_not_found", id, revision });
+            reportProgress();
+            continue;
+          }
+          try {
+            const document = asRecord(rawDocument);
+            if ("children" in document) {
+              const documentId = getStringField(document._id);
+              const documentRevision = getStringField(document._rev);
+              const path = getStringField(document.path);
+              const chunks = getChildren(document.children);
+              const revisions = documentMap.get(documentId) ?? [];
+              revisions.push({
+                id: documentId,
+                revision: documentRevision,
+                path,
+                chunks,
+                uniqueChunks: /* @__PURE__ */ new Set(),
+                sharedChunks: /* @__PURE__ */ new Set()
+              });
+              documentMap.set(documentId, revisions);
+            } else if (document.type === "leaf") {
+              const chunkId = getStringField(document._id);
+              if (!chunkMap.has(chunkId) && !document._deleted) {
+                if (typeof document.data !== "string") throw new Error("invalid chunk data");
+                chunkMap.set(chunkId, { length: document.data.length, refCount: 0 });
+              }
+            }
+          } catch {
+            errors.push({ code: "revision_document_invalid", id, revision });
+          }
+          reportProgress();
+        }
+        if (isCancelled()) cancelled = true;
+        if (cancelled) break;
+      }
+    } else if (isCancelled()) {
+      cancelled = true;
+    }
+  } catch {
+    if (isCancelled()) cancelled = true;
+    else {
+      enumerationFailed = true;
+      errors.push({ code: "id_enumeration_failed" });
+    }
+  }
+  for (const revisions of documentMap.values()) {
+    for (const document of revisions) {
+      for (const chunkId of document.chunks) {
+        const chunk = chunkMap.get(chunkId);
+        if (!chunk) continue;
+        if (chunk.refCount === 0) document.uniqueChunks.add(chunkId);
+        else document.sharedChunks.add(chunkId);
+        chunk.refCount++;
+      }
+    }
+  }
+  const totalSize = (ids) => {
+    let size = 0;
+    for (const id of ids) size += chunkMap.get(id)?.length ?? 0;
+    return size;
+  };
+  const rows = [];
+  for (const revisions of documentMap.values()) {
+    for (const document of revisions) {
+      const revisionNumber = getRevisionNumber(document.revision);
+      let revisionHash;
+      try {
+        revisionHash = getRevisionHash(document.revision);
+      } catch {
+        errors.push({ code: "revision_document_invalid", id: document.id, revision: document.revision });
+        continue;
+      }
+      rows.push({
+        title: `${document.path} (${document.revision})`,
+        id: document.id,
+        path: document.path,
+        revision: document.revision,
+        rev: revisionNumber,
+        revHash: revisionHash,
+        uniqueChunkCount: document.uniqueChunks.size,
+        sharedChunkCount: document.sharedChunks.size,
+        uniqueChunkSize: totalSize(document.uniqueChunks),
+        sharedChunkSize: totalSize(document.sharedChunks)
+      });
+    }
+  }
+  const orphanChunks = [...chunkMap.entries()].filter(([, chunk]) => chunk.refCount === 0);
+  rows.push({
+    title: "__orphan",
+    id: "__orphan",
+    path: "__orphan",
+    revision: "1-xxxxx",
+    rev: "1",
+    revHash: "xxxxx",
+    uniqueChunkCount: orphanChunks.length,
+    sharedChunkCount: 0,
+    uniqueChunkSize: orphanChunks.reduce((size, [, chunk]) => size + chunk.length, 0),
+    sharedChunkSize: 0
+  });
+  if (!cancelled && !isCancelled()) {
+    try {
+      const info = await source.info();
+      endUpdateSeq = info.update_seq;
+      if (endUpdateSeq === void 0) errors.push({ code: "end_update_seq_unavailable" });
+    } catch {
+      errors.push({ code: "end_info_read_failed" });
+    }
+  }
+  if (isCancelled()) cancelled = true;
+  const changedDuringRun = startUpdateSeq === void 0 || endUpdateSeq === void 0 ? void 0 : startUpdateSeq !== endUpdateSeq;
+  const snapshotUncertain = startUpdateSeq === void 0 || endUpdateSeq === void 0;
+  const hasDocumentRows = rows.length > 1;
+  let status;
+  if (cancelled) status = "cancelled";
+  else if (changedDuringRun === true || snapshotUncertain) status = "partial";
+  else if (enumerationFailed && !hasDocumentRows) status = "failed";
+  else if (errors.length > 0) status = "partial";
+  else status = "complete";
+  return {
+    version: 1,
+    kind: "usage",
+    status,
+    ...startUpdateSeq === void 0 ? {} : { startUpdateSeq },
+    ...endUpdateSeq === void 0 ? {} : { endUpdateSeq },
+    ...changedDuringRun === void 0 ? {} : { changedDuringRun },
+    rows,
+    errors
+  };
+}
+export {
+  analyseDatabaseUsage
+};

package/dist/pouchdb/encryption.d.ts

@@ -1,12 +1,14 @@
+import { Logger } from "../common/logger.js";
 import { type EntryDoc, type AnyEntry, type EntryLeaf, type DocumentID, type E2EEAlgorithm } from "../common/types.js";
 import { encryptWorker, decryptWorker, encryptHKDFWorker, decryptHKDFWorker } from "#worker";
 export declare const encrypt: typeof encryptWorker;
 export declare const decrypt: typeof decryptWorker;
 export declare const encryptHKDF: typeof encryptHKDFWorker;
 export declare const decryptHKDF: typeof decryptHKDFWorker;
+export declare function isEncryptedMeta<T extends AnyEntry>(doc: T): boolean;
 export declare let preprocessOutgoing: (doc: AnyEntry | EntryLeaf) => Promise<AnyEntry | EntryLeaf>;
 export declare let preprocessIncoming: (doc: EntryDoc) => Promise<EntryDoc>;
-export declare function getConfiguredFunctionsForEncryption(passphrase: string, useDynamicIterationCount: boolean, migrationDecrypt: boolean, getPBKDF2Salt: () => Promise<Uint8Array<ArrayBuffer>>, algorithm: E2EEAlgorithm, encryptInternalMetadata?: boolean): {
+export declare function getConfiguredFunctionsForEncryption(passphrase: string, useDynamicIterationCount: boolean, migrationDecrypt: boolean, getPBKDF2Salt: () => Promise<Uint8Array<ArrayBuffer>>, algorithm: E2EEAlgorithm, encryptInternalMetadata?: boolean, log?: typeof Logger): {
     incoming: (doc: AnyEntry | EntryLeaf) => Promise<AnyEntry | EntryLeaf>;
     outgoing: (doc: EntryDoc) => Promise<AnyEntry | EntryLeaf>;
 };

package/dist/pouchdb/encryption.js

@@ -32,20 +32,20 @@ function getEncryptionVersion(data) {
   }
   return EncryptionVersions.UNENCRYPTED;
 }
-async function tryDecryptV1AsFallback(encryptedData, passphrase, useDynamicIterationCount) {
+async function tryDecryptV1AsFallback(encryptedData, passphrase, useDynamicIterationCount, log = Logger) {
   try {
     return await decrypt(encryptedData, passphrase, useDynamicIterationCount);
   } catch (ex) {
     try {
-      Logger(
+      log(
         "Failed to decrypt with V1 method. Fallback to disable useDynamicIterationCount.",
         LOG_LEVEL_VERBOSE
       );
-      Logger(ex, LOG_LEVEL_VERBOSE);
+      log(ex, LOG_LEVEL_VERBOSE);
       return await decrypt(encryptedData, passphrase, false);
     } catch (ex2) {
-      Logger("Completely failed to decrypt with V1 method.", LOG_LEVEL_VERBOSE);
-      Logger(ex2, LOG_LEVEL_VERBOSE);
+      log("Completely failed to decrypt with V1 method.", LOG_LEVEL_VERBOSE);
+      log(ex2, LOG_LEVEL_VERBOSE);
       return false;
     }
   }
@@ -153,7 +153,7 @@ async function incomingEncryptHKDF(doc, passphrase, useDynamicIterationCount, ge
   }
   return saveDoc;
 }
-async function outgoingDecryptHKDF(doc, migrationDecrypt, decrypted, passphrase, useDynamicIterationCount, getPBKDF2Salt) {
+async function outgoingDecryptHKDF(doc, migrationDecrypt, decrypted, passphrase, useDynamicIterationCount, getPBKDF2Salt, log) {
   const loadDoc = {
     ...doc
   };
@@ -165,21 +165,26 @@ async function outgoingDecryptHKDF(doc, migrationDecrypt, decrypted, passphrase,
         loadDoc.data = await decryptHKDF(loadDoc.data, passphrase, pbkdf2salt);
         delete loadDoc.e_;
       } else if (encryptionVersion === EncryptionVersions.ENCRYPTED) {
-        const decryptedData = await tryDecryptV1AsFallback(loadDoc.data, passphrase, useDynamicIterationCount);
+        const decryptedData = await tryDecryptV1AsFallback(
+          loadDoc.data,
+          passphrase,
+          useDynamicIterationCount,
+          log
+        );
         if (decryptedData === false) {
-          Logger(MESSAGE_FALLBACK_DECRYPT_FAILED, LOG_LEVEL_NOTICE);
+          log(MESSAGE_FALLBACK_DECRYPT_FAILED, LOG_LEVEL_NOTICE);
           throw new Error(MESSAGE_FALLBACK_DECRYPT_FAILED);
         }
         loadDoc.data = decryptedData;
         delete loadDoc.e_;
       } else if (encryptionVersion === EncryptionVersions.UNENCRYPTED) {
       } else {
-        Logger("Unknown encryption version. Cannot decrypt.", LOG_LEVEL_NOTICE);
+        log("Unknown encryption version. Cannot decrypt.", LOG_LEVEL_NOTICE);
         throw new Error("Unknown encryption version. Cannot decrypt.");
       }
     } catch (ex) {
-      Logger(DECRYPTION_HKDF_FAILED, LOG_LEVEL_NOTICE);
-      Logger(ex);
+      log(DECRYPTION_HKDF_FAILED, LOG_LEVEL_NOTICE);
+      log(ex);
       throw ex;
     }
   }
@@ -192,16 +197,16 @@ async function outgoingDecryptHKDF(doc, migrationDecrypt, decrypted, passphrase,
           loadDoc[key] = metadata[key];
         }
       } catch (ex) {
-        Logger(`${DECRYPTION_HKDF_FAILED} on Path`, LOG_LEVEL_NOTICE);
-        Logger(ex);
+        log(`${DECRYPTION_HKDF_FAILED} on Path`, LOG_LEVEL_NOTICE);
+        log(ex);
         throw ex;
       }
     } else {
       const path = getPath(loadDoc);
       if (isPathProbablyObfuscated(path)) {
-        const decryptedPath = await tryDecryptV1AsFallback(path, passphrase, useDynamicIterationCount);
+        const decryptedPath = await tryDecryptV1AsFallback(path, passphrase, useDynamicIterationCount, log);
         if (decryptedPath === false) {
-          Logger(`${MESSAGE_FALLBACK_DECRYPT_FAILED} on Path`, LOG_LEVEL_NOTICE);
+          log(`${MESSAGE_FALLBACK_DECRYPT_FAILED} on Path`, LOG_LEVEL_NOTICE);
           throw new Error(MESSAGE_FALLBACK_DECRYPT_FAILED);
         }
         loadDoc.path = decryptedPath;
@@ -215,7 +220,8 @@ async function outgoingDecryptHKDF(doc, migrationDecrypt, decrypted, passphrase,
       const decryptedEden = await tryDecryptV1AsFallback(
         loadDoc.eden[EDEN_ENCRYPTED_KEY].data,
         passphrase,
-        useDynamicIterationCount
+        useDynamicIterationCount,
+        log
       );
       if (decryptedEden === false) throw new Error(MESSAGE_FALLBACK_DECRYPT_FAILED);
       readEden = {
@@ -224,8 +230,8 @@ async function outgoingDecryptHKDF(doc, migrationDecrypt, decrypted, passphrase,
       };
       edenDecrypted = true;
     } catch (ex) {
-      Logger(`${DECRYPTION_FALLBACK_FAILED} on Eden`, LOG_LEVEL_NOTICE);
-      Logger(ex);
+      log(`${DECRYPTION_FALLBACK_FAILED} on Eden`, LOG_LEVEL_NOTICE);
+      log(ex);
       throw ex;
     }
   }
@@ -243,8 +249,8 @@ async function outgoingDecryptHKDF(doc, migrationDecrypt, decrypted, passphrase,
       };
       edenDecrypted = true;
     } catch (ex) {
-      Logger(`${DECRYPTION_HKDF_FAILED} on Eden`, LOG_LEVEL_NOTICE);
-      Logger(ex);
+      log(`${DECRYPTION_HKDF_FAILED} on Eden`, LOG_LEVEL_NOTICE);
+      log(ex);
       throw ex;
     }
   }
@@ -296,7 +302,7 @@ async function incomingEncryptV1(doc, passphrase, useDynamicIterationCount) {
   }
   return saveDoc;
 }
-async function outgoingDecryptV1(doc, migrationDecrypt, decrypted, passphrase, useDynamicIterationCount) {
+async function outgoingDecryptV1(doc, migrationDecrypt, decrypted, passphrase, useDynamicIterationCount, log) {
   const loadDoc = {
     ...doc
   };
@@ -361,15 +367,15 @@ async function outgoingDecryptV1(doc, migrationDecrypt, decrypted, passphrase, u
           if (migrationDecrypt && ex2 instanceof SyntaxError) {
             return loadDoc;
           }
-          Logger("Decryption failed.", LOG_LEVEL_NOTICE);
-          Logger(ex2, LOG_LEVEL_VERBOSE);
-          Logger(`id:${loadDoc._id}-${loadDoc._rev?.substring(0, 10)}`, LOG_LEVEL_VERBOSE);
+          log("Decryption failed.", LOG_LEVEL_NOTICE);
+          log(ex2, LOG_LEVEL_VERBOSE);
+          log(`id:${loadDoc._id}-${loadDoc._rev?.substring(0, 10)}`, LOG_LEVEL_VERBOSE);
           throw ex2;
         }
       } else {
-        Logger("Decryption failed.", LOG_LEVEL_NOTICE);
-        Logger(ex, LOG_LEVEL_VERBOSE);
-        Logger(`id:${loadDoc._id}-${loadDoc._rev?.substring(0, 10)}`, LOG_LEVEL_VERBOSE);
+        log("Decryption failed.", LOG_LEVEL_NOTICE);
+        log(ex, LOG_LEVEL_VERBOSE);
+        log(`id:${loadDoc._id}-${loadDoc._rev?.substring(0, 10)}`, LOG_LEVEL_VERBOSE);
         throw ex;
       }
     }
@@ -382,7 +388,7 @@ let preprocessOutgoing = async (doc) => {
 let preprocessIncoming = async (doc) => {
   return await Promise.resolve(doc);
 };
-function getConfiguredFunctionsForEncryption(passphrase, useDynamicIterationCount, migrationDecrypt, getPBKDF2Salt, algorithm, encryptInternalMetadata = false) {
+function getConfiguredFunctionsForEncryption(passphrase, useDynamicIterationCount, migrationDecrypt, getPBKDF2Salt, algorithm, encryptInternalMetadata = false, log = Logger) {
   const decryptedCache = /* @__PURE__ */ new Map();
   const incoming = (doc) => algorithm === E2EEAlgorithms.V2 ? incomingEncryptHKDF(doc, passphrase, useDynamicIterationCount, getPBKDF2Salt, encryptInternalMetadata) : incomingEncryptV1(doc, passphrase, useDynamicIterationCount);
   const outgoing = (doc) => algorithm !== E2EEAlgorithms.ForceV1 ? outgoingDecryptHKDF(
@@ -391,8 +397,9 @@ function getConfiguredFunctionsForEncryption(passphrase, useDynamicIterationCoun
     decryptedCache,
     passphrase,
     useDynamicIterationCount,
-    getPBKDF2Salt
-  ) : outgoingDecryptV1(doc, migrationDecrypt, decryptedCache, passphrase, useDynamicIterationCount);
+    getPBKDF2Salt,
+    log
+  ) : outgoingDecryptV1(doc, migrationDecrypt, decryptedCache, passphrase, useDynamicIterationCount, log);
   return {
     incoming,
     outgoing
@@ -459,6 +466,7 @@ export {
   encrypt,
   encryptHKDF,
   getConfiguredFunctionsForEncryption,
+  isEncryptedMeta,
   preprocessIncoming,
   preprocessOutgoing,
   shouldDecryptEden,

package/dist/serviceFeatures/offlineScanner.d.ts

@@ -1,6 +1,7 @@
 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 type { IPathService } from "../services/base/IService.js";
 import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
 import { VaultScanResults, type VaultScanResult } from "../services/base/VaultScanResult.js";
 export { VaultScanResults };
@@ -105,7 +106,11 @@ export declare function getMetadataDocumentNamespace(value: string): MetadataDoc
  * 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>;
+export declare function inspectMetadataDocumentIdentity(host: {
+    services: {
+        path: Pick<IPathService, "getPath" | "path2id">;
+    };
+}, doc: MetaEntry): Promise<MetadataDocumentIdentityInspection>;
 /**
  * Enumerate Metadata from its actual local document IDs and report only the
  * entries which ordinary path-based inspection cannot address.
@@ -139,7 +144,11 @@ export declare function collectDeletedFiles(host: NecessaryServices<"setting" |
  * @param doc Meta entry document
  * @returns Path string
  */
-export declare function getPathFromEntry(host: NecessaryServices<"path", never>, doc: MetaEntry): FilePathWithPrefix;
+export declare function getPathFromEntry(host: {
+    services: {
+        path: Pick<IPathService, "getPath">;
+    };
+}, doc: MetaEntry): FilePathWithPrefix;
 /**
  * Synchronise a single file between database and storage based on freshness comparison.
  * @param host Services container

package/dist/serviceModules/Rebuilder.js

@@ -183,7 +183,7 @@ Please enable them from the settings screen after setup is complete.`,
     await assertUniqueStoragePathIdentities(selected, this.path);
     if (databaseReady) {
       await assertMetadataPathIdentities(
-        this.database.localDatabase.findAllDocs(),
+        this.database.localDatabase.findAllDocs({ conflicts: true }),
         this.path,
         requireMatchingIds
       );

package/docs/database-diagnostics.md

@@ -0,0 +1,24 @@
+---
+date: 2026-10-19
+commonlib_version: '0.1.43'
+livesync_version: '1.0.38'
+status: unreleased
+---
+
+# Database diagnostics
+
+The focused `/diagnostics` entry supplies read-only database usage analysis and integrity inspection. Hosts choose original names or temporary pseudonyms before each run, provide progress and cancellation controls, and present the resulting reports. Analysis uses the original identifiers; name projection happens afterwards.
+
+Usage retains the existing available-revision selection and incremental chunk accounting. The first processed reference counts a chunk as unique; later references count it as shared. Sizes count JavaScript string units, as in the existing report. These columns do not measure physical database size or establish whether a chunk can be deleted.
+
+Integrity inspection enumerates actual stored document IDs, including logically deleted normal-file Metadata and current conflict branches. It uses the same identity classifier as the existing Metadata inspector. It reads content only for groups with identity discrepancies, conflicting branches, duplicate path claims, or differences between the inspected local and remote Metadata. Content comparisons use reconstructed bytes, including the Vault file where available. Missing, unreadable, and uninspected content remain distinct outcomes. Equal content within this scope does not establish that an entry is safe to delete.
+
+The first implementation supports the local database and CouchDB. Internal-file, customisation, and plug-in storage Metadata, older revision history, and other remote backends are explicitly outside integrity inspection. Usage continues to cover the revisions available to its local source. A remote failure retains the local findings and marks the integrity report partial.
+
+The CouchDB reader only sends GET requests. It reads existing synchronisation parameters when decryption needs a Security Seed and never creates missing parameters, initialises a database, or invokes replication admission. Local content reads do not fetch or cache remote Chunks. Owned requests are cancelled and released when the run ends; host-native request adapters may finish an already dispatched request after cancellation, but its result is discarded.
+
+Database update sequences and the host's configuration identity are checked again before completion. Storage readers must detect changes while reading a file. These observations can detect concurrent changes; they do not provide an atomic snapshot or prevent a file from changing later.
+
+Reports project a whitelist of facts. Pseudonyms preserve exact path equality across sources and keep document, revision, and Chunk identifiers separate. Case and Unicode normalisation facts are computed before projection. Maps are local to one run and are not persisted. Original-name mode still excludes credentials, connection addresses, encryption keys, raw errors, and file contents. JSON and Markdown use the same projected integrity result; TSV uses the same name mapper for Usage.
+
+Hosts may pass Commonlib, plug-in, and application versions to either report projector through its optional third argument. Only those three version fields are retained. Integrity reports also retain the five identity-related settings used for the inspection; credentials and the active connection configuration remain outside the report.

package/docs/development.md

@@ -8,6 +8,7 @@ The source tree is larger than the supported package surface. Consumers may impo
 
 - `src/index.ts`, `src/context.ts`, `src/settings.ts`, `src/remoteConfigurations.ts`, `src/p2p/index.ts`, `src/platform/browser/index.ts`, and `src/platform/node/index.ts` define the focused entries;
 - `src/replication/index.ts` defines the focused provider-capability and interaction contract for hosts which compose replication;
+- `src/diagnostics/index.ts` defines read-only Usage and integrity inspection, report projection, and formatting; hosts own the run dialogue and output destination;
 - `src/rpc/index.ts` defines a transitional entry for the existing LiveSync P2P composition, not a stable Commonlib 1.0 contract;
 - `_tools/build-package.mjs` compiles those entries and creates the publishable manifest under `.package`;
 - `docs/migration/downstream-imports.json` is the reviewed inventory from which explicit `compat/*` exports are generated;

package/docs/proven-in-use.md

@@ -8,6 +8,8 @@ The code paths below identify the maintained Self-hosted LiveSync composition po
 
 ## Obsidian plug-in
 
+Unreleased [database diagnostics](database-diagnostics.md) tests cover preserved Usage accounting, normal-file identity classification, current conflict branches, byte comparisons, embedded Chunks, missing and unreadable content, cancellation, concurrent changes, and consistent pseudonyms. Real in-memory PouchDB tests verify pagination and conflict revision reads while retaining the original database handle. A CouchDB 3.5.0 integration test verifies GET-only access, encrypted Metadata and Chunk reads with an existing Security Seed, missing-seed failure without initialisation, and unchanged database update sequences and Seed documents. Focused tests also reject ciphertext which remains undecoded after an ID mismatch. Self-hosted LiveSync owns the serviceFeature, run-time name choice, dialogue lifecycle, and report copy and download controls. Its real Obsidian 1.12.7 test on Linux verifies cancellation before a run, both name modes, the nine-column Usage report, copy and download payloads, local integrity findings when CouchDB is unavailable, and unchanged settings, database update sequences, and Vault file names. Mobile emulation verifies the choice dialogue's viewport, safe-area, and touch-target layout; native iOS and Android behaviour remains unverified.
+
 Unreleased content-evidence tests replicate 99, 100, and 599 updates between real in-memory PouchDB databases, including a receiver with `revs_limit: 100`. They verify unchanged reflection after the recorded revision is pruned, including a recreated handler, and preserve same-size edits, intentional reverts, and records without valid content evidence. Separate tests verify legacy upgrades and changes during hashing. These are package-owned tests; they do not establish Windows, mobile, or remote CouchDB behaviour.
 
 The exact local packed candidate also passes Self-hosted LiveSync 1.0.37's checks, unit tests, application builds, and CLI E2E. Its focused real-Obsidian `stale-file-restart` scenario prunes the recorded revision before restarting, verifies unchanged reflection and legacy-record upgrades, and preserves an unknown-origin file. The Review Harness exercises the exported hash helper in desktop Obsidian. Maintainer-supplied Android and iOS reports additionally verify the helper and its benchmark on those devices; these timing measurements do not establish complete mobile synchronisation behaviour or peak memory use.
@@ -92,7 +94,9 @@ The CLI extends the same neutral context with its database path and injected `St
 
 The CLI filesystem composition receives a configured base directory and constructs the rooted Node storage adapter in `src/apps/cli/adapters/NodeFileSystemAdapter.ts`. Commonlib's shared storage result table checks the focused root contract; the consumer adds its file cache, Vault-shaped operations, case handling, and command policy.
 
-The unreleased [Unicode path identity contract](unicode-path-identity.md) adds opt-in NFC document IDs for CLI and Obsidian use with CouchDB. Commonlib tests exercise real in-memory Metadata lookup across different host normalisers. CLI temporary-filesystem tests cover resolution, updates, deletions, unchanged physical spellings, and ambiguous NFC paths. File-reflection tests preserve NFC-equivalent physical names while retaining case-only rename behaviour. With the packed candidate installed, the Linux CLI-to-real-Obsidian scenario verifies creation, remote updates, and daemon-applied deletions with and without E2EE and Path Obfuscation. A separate run migrates two legacy CLI databases with Rebuild and Fetch before the Obsidian round trip, preserving both NFD physical names and replacing the remote document ID. These checks do not establish native macOS or iOS behaviour.
+The [Unicode path identity contract](unicode-path-identity.md), introduced in Commonlib `0.1.42`, provides opt-in NFC document IDs for CLI and Obsidian use with CouchDB. Commonlib tests exercise real in-memory Metadata lookup across different host normalisers. CLI temporary-filesystem tests cover resolution, updates, deletions, unchanged physical spellings, and ambiguous NFC paths. File-reflection tests preserve NFC-equivalent physical names while retaining case-only rename behaviour. With the packed candidate installed, the Linux CLI-to-real-Obsidian scenario verifies creation, remote updates, and daemon-applied deletions with and without E2EE and Path Obfuscation. A separate run migrates two legacy CLI databases with Rebuild and Fetch before the Obsidian round trip, preserving both NFD physical names and replacing the remote document ID. These checks do not establish native macOS or iOS behaviour.
+
+The unreleased reconstruction refinement excludes unconflicted logical deletions only when replacing the local database. Rebuilder tests exercise real PouchDB enumeration before the reset boundary across Rebuild, Standard Fetch, and Fast Fetch. Real CouchDB tests cover deletion propagation, fully tombstoned documents, unresolved conflict leaves, and a stale local copy after a remote deletion. Non-deleted duplicates and unresolved conflicts still stop reconstruction, and remote-only Rebuild retains its ID check. These package-owned tests establish preflight decisions; the maintained downstream migration scenario separately owns complete CLI reconstruction and real-Obsidian Fast Fetch with the exact packed candidate.
 
 Unreleased Node timestamp tests verify that `stat` and `trystat` retain an available birth time when change time advances, fall back when birth time is zero, and return integer milliseconds. Packed-package checks exercise the shared `getNodeFileCreationTime` export. With the exact locally packed candidate installed, downstream CLI tests verify that an in-place edit retains creation time in local Metadata. The CLI-to-real-Obsidian scenario additionally verifies the edited content and creation time in received Metadata. These checks do not establish the reporter's ZFS behaviour or physical-file creation times in Obsidian.
 

package/docs/unicode-path-identity.md

@@ -0,0 +1,98 @@
+---
+date: 2026-10-19
+commonlib-version: "0.1.42"
+self-hosted-livesync-version: "1.0.38"
+status: unreleased
+---
+
+# Unicode path identity
+
+`pathNormalizationVersion` controls the logical path used to derive a normal-file
+Metadata document ID. An absent value or `0` preserves legacy behaviour. Value
+`1` applies Unicode NFC before the existing case and ID derivation rules. It
+does not alter the Metadata path or require physical files to be renamed.
+Unsupported values are rejected.
+
+NFC identity shipped in Commonlib `0.1.42` and Self-hosted LiveSync `1.0.38`.
+The deletion handling below is an unreleased refinement of reconstruction.
+
+## Package contract
+
+The Commonlib settings entry exposes `PathNormalizationVersion`,
+`PathIdentitySettings`, `getPathNormalizationVersion`, and
+`normalisePathForIdentity`. Consumers must use the shared path identity
+implementation for Metadata IDs rather than add a host-specific normalisation
+rule. Host storage adapters remain responsible for mapping a logical path back
+to its existing physical entry.
+
+## Database compatibility
+
+Version `1` uses `nfc-path-identity-v1` in the existing generation-13
+`used_features` list. This is separate from `idDerivationVersion`, which selects
+the cryptographic ID key. The NFC setting is a required Tweak even when
+encryption is disabled.
+
+A fresh database declares the feature before its first Metadata mutation. An
+existing database without the feature cannot acquire it through an ordinary
+Metadata write or replication while it already contains Metadata. A client
+configured for version `0` refuses an NFC database. These checks also apply
+when ordinary configuration-mismatch warnings are disabled. The existing
+version-document reception hook stops an active replication session when it
+detects incompatible path identity. It does not revoke server credentials or
+atomically cancel work already admitted by another device.
+
+Fast Fetch checkpoints include the path identity version, so a checkpoint
+created under version `0` cannot resume under version `1`, or vice versa.
+
+## Migration contract
+
+1. Update every participating client, stop synchronisation, and retain a
+   complete backup.
+2. Select a complete, authoritative Vault. Resolve distinct files or Metadata
+   documents which would derive the same NFC document ID. Case-insensitive
+   handling also applies its existing case rule.
+3. Set version `1` on the source and Rebuild both databases from that Vault.
+4. Set version `1` on the remaining clients and Fetch the rebuilt remote before
+   resuming synchronisation.
+
+Reconstruction checks the available storage listing and local Metadata before
+resetting either database. When the local database is not open, the storage
+check conservatively includes every listed file. A collision stops the
+operation; it never chooses a file to keep or merges separate histories.
+Ordinary synchronisation does not rename legacy document IDs in place.
+
+Full Rebuild, Standard Fetch, and Fast Fetch replace the local database. Their
+Metadata check requests conflict information and excludes a logically deleted
+document (`deleted: true`) only when it has no unresolved conflict leaves.
+A deleted winner with any unresolved conflict remains a collision candidate.
+Remote-only Rebuild retains logically deleted Metadata and still requires its
+stored document IDs to match the selected identity.
+
+A fully tombstoned document is already absent from ordinary Metadata
+enumeration. A deletion made only on the remote does not exclude a still
+non-deleted local document until that deletion has been replicated.
+
+The Setup URI shares `pathNormalizationVersion`; an absent value decodes as
+legacy mode, and unsupported versions are rejected. Importing a shared value
+does not itself perform the required reconstruction.
+
+## Supported hosts
+
+The initial support boundary is the maintained CLI and Obsidian with CouchDB.
+`PathService` owns logical ID derivation. The CLI resolves NFC-equivalent names
+against directory entries while preserving the actual entry spelling; its
+generic Node storage contract remains exact-path access. Obsidian supplies its
+normalised storage paths and preserves an existing physical spelling when it
+is NFC-equivalent to the received path.
+
+Journal and P2P refuse version `1`. Direct file access refuses a remote which
+declares the NFC feature. Other host adapters must establish physical path
+resolution before offering this setting. The regression tests cover ASCII,
+NFC, NFD, and mixed paths through in-memory PouchDB Metadata lookup, with and
+without path obfuscation, plus database admission, reconstruction ordering,
+collisions, and physical path handling. These tests do not establish native
+iOS or macOS filesystem behaviour.
+
+The full host setting, Rebuild/Fetch, CLI, and Obsidian migration contract is
+in the [Self-hosted LiveSync Unicode path identity design](https://github.com/vrtmrz/obsidian-livesync/blob/main/docs/design_docs/unicode_path_identity.md)
+and its [decision record](https://github.com/vrtmrz/obsidian-livesync/blob/main/docs/adr/2026_10_unicode_path_identity.md).