@vrtmrz/livesync-commonlib 0.1.41 → 0.1.43

package/README.md

@@ -26,7 +26,8 @@ The package is ESM-only and declares Node 20 or later. Browser entry points are
 | -------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
 | `@vrtmrz/livesync-commonlib`                       | `DirectFileManipulator` for integrations which access CouchDB directly            | Deliberately small, but its high-level lifecycle and file-operation semantics are not final |
 | `@vrtmrz/livesync-commonlib/context`               | Instance-owned events, translation injection, and host-neutral standard-I/O types | Focused, package-tested pre-1.0 contract                                                    |
-| `@vrtmrz/livesync-commonlib/hashing`               | Chunk ID calculation with the database's hash manager                            | Focused, package-tested pre-1.0 contract                                                    |
+| `@vrtmrz/livesync-commonlib/diagnostics` | Read-only Usage and integrity inspection, name projection, and reports | Focused pre-1.0 diagnostic contract |
+| `@vrtmrz/livesync-commonlib/hashing`               | Chunk ID calculation and exact file-content hashing                            | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/browser`               | Rooted File System Access API storage                                             | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/node`                  | Rooted Node storage, Node standard I/O, and selected Node capabilities            | Supported platform façade; keeps Node-only dependencies behind an explicit boundary         |
 | `@vrtmrz/livesync-commonlib/p2p`                   | Host-composed P2P service views and composition helpers                           | Focused, package-tested pre-1.0 contract with a temporary compatibility façade              |
@@ -119,12 +120,37 @@ See [the settings lifecycle guide](docs/settings-lifecycle.md) before initialisi
 
 The focused Setup URI entry offers an Ephemeral mode bound to the current fixed seven-day window and a Persistent mode compatible with existing readers. Both use the same URI structure. See [the Setup URI sharing guide](docs/setup-uri.md) for the availability boundary, import behaviour, and compatibility limits.
 
+## Database diagnostics
+
+The focused `/diagnostics` entry provides read-only Usage and integrity reports, with original names or temporary pseudonyms selected by the host for each run. Integrity inspection covers normal-file Metadata, current conflict branches, and content comparisons for suspect groups in the local database and CouchDB. See [Database diagnostics](docs/database-diagnostics.md) for coverage, cancellation, and privacy boundaries.
+
+```typescript
+import {
+    analyseDatabaseUsage,
+    createDiagnosticNameMapper,
+    createLocalDiagnosticSource,
+    formatUsageTSV,
+    projectUsageReport,
+} from '@vrtmrz/livesync-commonlib/diagnostics';
+
+const result = await analyseDatabaseUsage({ source: createLocalDiagnosticSource(localPouchDB) });
+const report = projectUsageReport(result, createDiagnosticNameMapper('pseudonym'));
+if (report.status === 'complete') {
+    const tsv = formatUsageTSV(report);
+    // Present the report through the host's own UI or output stream.
+}
+```
+
 ## Chunk ID calculation
 
 The `/hashing` entry exports `HashManager` and its `HashManagerCoreOptions` type. It uses the same implementation as database writes, including legacy algorithms and independent ID keys. Hosts supply their settings service and await `initialise()` before calling `computeHash(piece)`.
 
 `computeHash` returns the Chunk hash, including the `+` prefix when encryption is enabled; the database adds its `h:` namespace separately. Reuse a manager for repeated calculations with the same configuration, create a new manager when changing the legacy algorithm or passphrase, and call `clearCaches()` when retiring it. This releases retained key preparation; it does not erase existing settings or in-flight operations. The entry performs ID calculation and does not write Chunks to a database.
 
+## File content hashing
+
+`computeFileContentHash(content: Blob)` returns a `sha256:<lowercase hexadecimal>` digest of the exact bytes. It includes Blob reading and serialises concurrent hashes to limit whole-file buffer overlap. File-reflection provenance uses this helper to recognise unchanged content independently of retained revision history; it does not replace Chunk ID calculation.
+
 ## Remote connection profiles
 
 New profile-management code can create or update a CouchDB, Object Storage, or P2P connection through the focused remote-configurations entry. Profile IDs provide identity, display names remain editable presentation, and the active selection is explicit. Older flat connection fields remain a runtime projection and an import-compatibility boundary rather than the preferred persistence model.
@@ -135,6 +161,8 @@ See [the remote configuration profile guide](docs/remote-configurations.md) for
 
 CouchDB stores the representations already in use as feature identifiers in its version document. Assess that document before synchronisation or direct file operations, and retain unknown identifiers for host diagnostics. See [the remote feature compatibility contract](docs/remote-feature-compatibility.md) for the wire format, update rules, and recovery boundaries.
 
+The maintained CLI and Obsidian hosts can opt into [Unicode NFC path identity](docs/unicode-path-identity.md) with CouchDB. Existing databases require an explicit Rebuild or Fetch migration before using it.
+
 ## Contract scope
 
 The package is currently an infrastructure and compatibility boundary. The context, rooted-storage, standard-I/O, and revision-tree safety contracts have focused cross-platform, instance-isolation, or real-PouchDB tests. Platform details which cannot be shared, such as file timestamp fidelity and browser permission handling, remain host concerns and are documented separately.

package/dist/API/DirectFileManipulatorV2.js

@@ -3,11 +3,17 @@ import {
   DEFAULT_SYNC_PARAMETERS,
   ProtocolVersions,
   DOCID_SYNC_PARAMETERS,
+  VERSIONING_DOCID,
   E2EEAlgorithms,
   VER
 } from "../common/types.js";
 import { checkRemoteVersion } from "../pouchdb/negotiation.js";
-import { requiredRemoteFeatures, usesEncryptedInternalMetadata } from "../pouchdb/remoteFeatureCompatibility.js";
+import {
+  assessRemoteFeatureDocument,
+  NFC_PATH_IDENTITY_FEATURE,
+  requiredRemoteFeatures,
+  usesEncryptedInternalMetadata
+} from "../pouchdb/remoteFeatureCompatibility.js";
 import { assessRemoteDocumentIds } from "../pouchdb/remoteIdCompatibility.js";
 import { PouchDB } from "../pouchdb/pouchdb-http.js";
 import { LiveSyncLocalDB } from "../pouchdb/LiveSyncLocalDB.js";
@@ -67,6 +73,15 @@ class DirectFileManipulator {
       if (idCompatibility === "mismatched") {
         throw new Error("Direct database document IDs do not match the configured ID key.");
       }
+      try {
+        const versionInfo = await this.liveSyncLocalDB.localDatabase.get(VERSIONING_DOCID);
+        const assessment = assessRemoteFeatureDocument(versionInfo);
+        if (assessment.status === "supported" && assessment.usedFeatures.includes(NFC_PATH_IDENTITY_FEATURE)) {
+          throw new Error("Direct database version or features are not compatible.");
+        }
+      } catch (error) {
+        if (!isErrorOfMissingDoc(error)) throw error;
+      }
       const requiredFeatures = requiredRemoteFeatures(this.settings);
       if (!await checkRemoteVersion(
         this.liveSyncLocalDB.localDatabase,

package/dist/API/processSetting.d.ts

@@ -57,6 +57,7 @@ export declare function decodeSettingsFromSetupURI(uri: string, passphrase: stri
     encryptInternalMetadata: boolean;
     idDerivationVersion: 0 | 1;
     idDerivationKey: string;
+    pathNormalizationVersion: import("../settings.js").PathNormalizationVersion;
     liveSync: boolean;
     syncOnSave: boolean;
     syncOnStart: boolean;

package/dist/API/processSetting.js

@@ -10,9 +10,11 @@ import {
 import { decryptString, encryptString } from "../encryption/stringEncryption.js";
 import { LOG_LEVEL_VERBOSE, Logger } from "octagonal-wheels/common/logger";
 import { configuredIdKey } from "../common/idDerivation.js";
+import { getPathNormalizationVersion } from "../common/pathNormalization.js";
 function encodeSettingsToQRCodeData(settings) {
   settings = omitP2PRuntimeSettings(settings);
   configuredIdKey(settings);
+  getPathNormalizationVersion(settings);
   const fullIndexes = Object.entries(KeyIndexOfSettings);
   let maxIndex = 0;
   for (const [, index] of fullIndexes) {
@@ -53,6 +55,7 @@ function decodeSettingsFromQRCodeData(qr) {
     );
   }
   configuredIdKey(newSettings);
+  newSettings.pathNormalizationVersion = getPathNormalizationVersion(newSettings);
   return omitP2PRuntimeSettings(newSettings);
 }
 var OutputFormat = /* @__PURE__ */ ((OutputFormat2) => {
@@ -134,6 +137,7 @@ async function encodeSettingsToSetupURI(settingString, passphrase, removePropert
   const setting = {
     ...omitP2PRuntimeSettings(settingString)
   };
+  getPathNormalizationVersion(setting);
   configuredIdKey({
     idDerivationVersion: setting.idDerivationVersion ?? 0,
     idDerivationKey: setting.idDerivationKey ?? ""
@@ -211,7 +215,8 @@ async function decodeSettingsFromSetupURI(uri, passphrase) {
       ...imported,
       encryptInternalMetadata: typeof imported.encryptInternalMetadata === "boolean" ? imported.encryptInternalMetadata : false,
       idDerivationVersion: imported.idDerivationVersion ?? 0,
-      idDerivationKey: imported.idDerivationKey ?? ""
+      idDerivationKey: imported.idDerivationKey ?? "",
+      pathNormalizationVersion: getPathNormalizationVersion(imported)
     };
     configuredIdKey(settings);
     return omitP2PRuntimeSettings(settings);

package/dist/common/fileContentHash.d.ts

@@ -0,0 +1,2 @@
+/** Hash the exact bytes of one immutable file snapshot. */
+export declare function computeFileContentHash(content: Blob): Promise<`sha256:${string}`>;

package/dist/common/fileContentHash.js

@@ -0,0 +1,18 @@
+import { Semaphore } from "octagonal-wheels/concurrency/semaphore";
+import { getWebCrypto } from "../mods.js";
+import { uint8ArrayToHexString } from "../string_and_binary/convert.js";
+const hashing = Semaphore(1);
+async function computeFileContentHash(content) {
+  const release = await hashing.acquire();
+  try {
+    const crypto = await getWebCrypto();
+    const bytes = await content.arrayBuffer();
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return `sha256:${uint8ArrayToHexString(new Uint8Array(digest))}`;
+  } finally {
+    release();
+  }
+}
+export {
+  computeFileContentHash
+};

package/dist/common/models/setting.const.defaults.js

@@ -58,6 +58,7 @@ const SETTINGS_SCHEMA_DEFAULTS = {
   passphrase: "",
   idDerivationVersion: 0,
   idDerivationKey: "",
+  pathNormalizationVersion: 0,
   usePathObfuscation: false,
   encryptInternalMetadata: false,
   doNotDeleteFolder: false,

package/dist/common/models/setting.const.qr.js

@@ -180,6 +180,7 @@ const KeyIndexOfSettings = {
   encryptInternalMetadata: 165,
   idDerivationVersion: 166,
   idDerivationKey: 167,
+  pathNormalizationVersion: 168,
   encryptedIdDerivationKey: -1
 };
 export {

package/dist/common/models/setting.policy.d.ts

@@ -485,6 +485,10 @@ export declare const SETTINGS_PROPERTY_POLICY: {
         readonly markdown: "credentials";
         readonly persistence: "include";
     };
+    readonly pathNormalizationVersion: {
+        readonly markdown: "credentials";
+        readonly persistence: "include";
+    };
     readonly idDerivationKey: {
         readonly markdown: "credentials";
         readonly persistence: "id-key";

package/dist/common/models/setting.policy.js

@@ -122,6 +122,7 @@ const SETTINGS_PROPERTY_POLICY = {
   encrypt: SettingPolicies.Default,
   passphrase: SettingPolicies.E2EEPassphrase,
   idDerivationVersion: SettingPolicies.MarkdownCredentials,
+  pathNormalizationVersion: SettingPolicies.MarkdownCredentials,
   idDerivationKey: SettingPolicies.IdDerivationKey,
   usePathObfuscation: SettingPolicies.Default,
   encryptInternalMetadata: SettingPolicies.Default,

package/dist/common/models/setting.type.d.ts

@@ -575,6 +575,13 @@ export interface RemoteTypeSettings {
     remoteType: RemoteType;
 }
 export type E2EEAlgorithm = (typeof E2EEAlgorithms)[keyof typeof E2EEAlgorithms] | "";
+/** Path identity modes retained in persisted settings and shared tweak snapshots. */
+export type PathNormalizationVersion = 0 | 1;
+/** Identity settings for mapping logical paths to remote document IDs. */
+export interface PathIdentitySettings {
+    /** Zero preserves legacy path identity; one applies Unicode NFC before ID derivation. */
+    pathNormalizationVersion: PathNormalizationVersion;
+}
 /**
  * Represents the settings used for End-to-End encryption.
  */
@@ -937,7 +944,7 @@ export interface RemoteConfigurations {
 }
 interface ObsidianLiveSyncSettings_PluginSetting extends SyncMethodSettings, UISettings, FileHandlingSettings, MergeBehaviourSettings, EncryptedUserSettings, PeriodicReplicationSettings, InternalFileSettings, PluginSyncSettings, ModeSettings, ExtraTweakSettings, BetaTweakSettings, ObsoleteSettings, DebugModeSettings, SettingSyncSettings, SafetyValveSettings, DataOnSettings, RemoteConfigurations {
 }
-export type RemoteDBSettings = CouchDBConnection & BucketSyncSetting & RemoteTypeSettings & EncryptionSettings & ChunkSettings & EdenSettings & DataOnRemoteDBSettings & ObsoleteRemoteDBSettings & OnDemandChunkSettings & BetaRemoteDBSettings & ReplicationSetting & RemoteDBTweakSettings & FileHandlingSettings & ProcessingBehaviourSettings & OptionalAndNotExposedRemoteDBSettings & CrossPlatformInteroperabilitySettings & ConflictHandlingSettings & EdgeCaseHandlingSettings & DeletedFileMetadataSettings & P2PSyncSetting & RemoteConfigurations;
+export type RemoteDBSettings = CouchDBConnection & BucketSyncSetting & RemoteTypeSettings & PathIdentitySettings & EncryptionSettings & ChunkSettings & EdenSettings & DataOnRemoteDBSettings & ObsoleteRemoteDBSettings & OnDemandChunkSettings & BetaRemoteDBSettings & ReplicationSetting & RemoteDBTweakSettings & FileHandlingSettings & ProcessingBehaviourSettings & OptionalAndNotExposedRemoteDBSettings & CrossPlatformInteroperabilitySettings & ConflictHandlingSettings & EdgeCaseHandlingSettings & DeletedFileMetadataSettings & P2PSyncSetting & RemoteConfigurations;
 export type ObsidianLiveSyncSettings = ObsidianLiveSyncSettings_PluginSetting & RemoteDBSettings & LocalDBSettings;
 export interface HasSettings<T extends Partial<ObsidianLiveSyncSettings>> {
     settings: T;

package/dist/common/models/shared.definition.configNames.js

@@ -64,6 +64,11 @@ const configurationNames = {
     name: "Handle files as Case-Sensitive",
     desc: "If this enabled, All files are handled as case-Sensitive (Previous behaviour)."
   },
+  pathNormalizationVersion: {
+    name: "Path identity mode",
+    desc: "CouchDB only. Version 0 preserves legacy path identity; version 1 uses Unicode NFC. Physical file names stay unchanged. Update every device and stop synchronisation, then Rebuild both databases from a complete authoritative Vault and Fetch on the other devices. Resolve colliding file names first. P2P and Object Storage do not support version 1.",
+    isAdvanced: true
+  },
   doNotUseFixedRevisionForChunks: {
     name: "Content-derived chunk revisions (obsolete setting)",
     desc: "Chunk revisions are always derived from their content. This stored key is retained only for compatibility."

package/dist/common/models/tweak.definition.d.ts

@@ -25,6 +25,11 @@ export declare const TweakCompatibilityRules: readonly [{
     readonly templateValue: 0;
     readonly reconstruction: "required";
     readonly knownDefault: 0;
+}, {
+    readonly key: "pathNormalizationVersion";
+    readonly templateValue: 0;
+    readonly reconstruction: "required";
+    readonly knownDefault: 0;
 }, {
     readonly key: "encryptInternalMetadata";
     readonly templateValue: false;
@@ -116,6 +121,7 @@ export declare const TweakValuesDefault: Partial<ObsidianLiveSyncSettings>;
 export declare const TweakValuesTemplate: {
     tweakModified: number;
     usePluginSyncV2: boolean;
+    pathNormalizationVersion: import("./setting.type.js").PathNormalizationVersion;
     encrypt: boolean;
     idDerivationVersion: 0 | 1;
     usePathObfuscation: boolean;

package/dist/common/models/tweak.definition.js

@@ -6,6 +6,7 @@ const TweakCompatibilityRules = Object.freeze([
   { key: "encrypt", templateValue: false, reconstruction: "required" },
   { key: "usePathObfuscation", templateValue: false, reconstruction: "required" },
   { key: "idDerivationVersion", templateValue: 0, reconstruction: "required", knownDefault: 0 },
+  { key: "pathNormalizationVersion", templateValue: 0, reconstruction: "required", knownDefault: 0 },
   { key: "encryptInternalMetadata", templateValue: false, reconstruction: "none", knownDefault: false },
   { key: "enableCompression", templateValue: false, reconstruction: "none" },
   { key: "useEden", templateValue: false, reconstruction: "none" },

package/dist/common/pathIdentity.d.ts

@@ -0,0 +1,19 @@
+import type { EntryHasPath, FilePathWithPrefix } from "./types.js";
+import type { IPathService } from "../services/base/IService.js";
+/** Check the complete source listing before an operation can discard either database. */
+export declare function assertUniqueStoragePathIdentities(paths: Iterable<FilePathWithPrefix>, pathService: Pick<IPathService, "path2id">): Promise<void>;
+/**
+ * Distinct Metadata documents must not be merged by a change of path identity.
+ * Callers must enumerate entries with `conflicts: true` so unresolved revisions remain visible.
+ * `requireMatchingIds: false` is reserved for preflight checks before replacing the local database;
+ * only that mode excludes conflict-free logical deletions from collision checks.
+ */
+export declare function assertMetadataPathIdentities(entries: AsyncIterable<EntryHasPath & {
+    _id: string;
+    deleted?: boolean;
+    _conflicts?: string[];
+}> | Iterable<EntryHasPath & {
+    _id: string;
+    deleted?: boolean;
+    _conflicts?: string[];
+}>, pathService: Pick<IPathService, "path2id">, requireMatchingIds: boolean): Promise<void>;

package/dist/common/pathIdentity.js

@@ -0,0 +1,35 @@
+import { id2path_base } from "../string_and_binary/path.js";
+function collision(first, second) {
+  return new Error(
+    `File path identity collision: ${JSON.stringify(first)} and ${JSON.stringify(second)}. Rename or exclude the distinct files before continuing.`
+  );
+}
+async function assertUniqueStoragePathIdentities(paths, pathService) {
+  const identities = /* @__PURE__ */ new Map();
+  for (const path of paths) {
+    const id = await pathService.path2id(path);
+    const previous = identities.get(id);
+    if (previous !== void 0 && previous !== path) throw collision(previous, path);
+    identities.set(id, path);
+  }
+}
+async function assertMetadataPathIdentities(entries, pathService, requireMatchingIds) {
+  const identities = /* @__PURE__ */ new Map();
+  for await (const entry of entries) {
+    if (!requireMatchingIds && entry.deleted === true && !entry._conflicts?.length) continue;
+    const path = id2path_base(entry._id, entry);
+    const id = await pathService.path2id(path);
+    const previous = identities.get(id);
+    if (previous && previous.id !== entry._id) throw collision(previous.path, path);
+    identities.set(id, { path, id: entry._id });
+    if (requireMatchingIds && entry._id !== id) {
+      throw new Error(
+        `The stored document ID for ${JSON.stringify(path)} uses a different path identity. Rebuild from the authoritative Vault or Fetch the migrated database before synchronising.`
+      );
+    }
+  }
+}
+export {
+  assertMetadataPathIdentities,
+  assertUniqueStoragePathIdentities
+};

package/dist/common/pathNormalization.d.ts

@@ -0,0 +1,7 @@
+import type { PathNormalizationVersion } from "./models/setting.type.js";
+/** Resolve the stored path identity version, treating an absent legacy value as version zero. */
+export declare function getPathNormalizationVersion(settings: {
+    pathNormalizationVersion?: number;
+}): PathNormalizationVersion;
+/** Normalise a logical path for document ID derivation without changing its stored path. */
+export declare function normalisePathForIdentity(path: string, version?: number): string;

package/dist/common/pathNormalization.js

@@ -0,0 +1,13 @@
+function getPathNormalizationVersion(settings) {
+  const version = settings.pathNormalizationVersion === void 0 ? 0 : settings.pathNormalizationVersion;
+  if (version === 0 || version === 1) return version;
+  throw new Error(`Unsupported path normalisation version: ${version}`);
+}
+function normalisePathForIdentity(path, version) {
+  const resolvedVersion = getPathNormalizationVersion({ pathNormalizationVersion: version });
+  return resolvedVersion === 1 ? path.normalize("NFC") : path;
+}
+export {
+  getPathNormalizationVersion,
+  normalisePathForIdentity
+};

package/dist/common/settingConstants.d.ts

@@ -134,6 +134,7 @@ export declare const AllSettingDefault: {
     bucketPrefix: string;
     forcePathStyle: boolean;
     remoteType: import("./types.js").RemoteType;
+    pathNormalizationVersion: import("./models/setting.type.js").PathNormalizationVersion;
     encrypt: boolean;
     passphrase: string;
     idDerivationVersion: 0 | 1;

package/dist/diagnostics/couchdb.d.ts

@@ -0,0 +1,15 @@
+import { type RemoteDBSettings } from "../common/types.js";
+import { type DiagnosticDatabaseSource } from "./types.js";
+export interface CouchDBDiagnosticSourceOptions {
+    settings: RemoteDBSettings;
+    fetch(request: string, options: RequestInit): Promise<Response>;
+    signal?: AbortSignal;
+}
+/**
+ * Open an operation-owned HTTP reader. All requests are GETs, including the
+ * Security Seed lookup; the replication connection and its setup paths are
+ * deliberately absent from this boundary.
+ */
+export declare function createCouchDBDiagnosticSource({ settings: originalSettings, fetch, signal, }: CouchDBDiagnosticSourceOptions): DiagnosticDatabaseSource & {
+    close(): Promise<void>;
+};

package/dist/diagnostics/couchdb.js

@@ -0,0 +1,129 @@
+import { DOCID_SYNC_PARAMETERS } from "../common/types.js";
+import { isObfuscatedEntry, parseHeaderValues } from "../common/utils.js";
+import { getConfiguredFunctionsForEncryption, isEncryptedMeta } from "../pouchdb/encryption.js";
+import { isPathProbablyObfuscated } from "octagonal-wheels/encryption/encryption";
+import { decompressDoc } from "../pouchdb/compress.js";
+import { AuthorizationHeaderGenerator, generateCredentialObject } from "../replication/httplib.js";
+import { base64ToArrayBuffer } from "../string_and_binary/convert.js";
+import { DiagnosticReadError } from "./types.js";
+function createCouchDBDiagnosticSource({
+  settings: originalSettings,
+  fetch,
+  signal
+}) {
+  const settings = { ...originalSettings };
+  const root = `${settings.couchDB_URI.replace(/\/+$/, "")}/${encodeURIComponent(settings.couchDB_DBNAME)}`;
+  const url = new URL(root);
+  if (!settings.couchDB_DBNAME || !["https:", "http:"].includes(url.protocol) || url.search || url.hash) {
+    throw new DiagnosticReadError("source-unavailable");
+  }
+  if (settings.encrypt && !settings.passphrase && !settings.permitEmptyPassphrase) {
+    throw new DiagnosticReadError("source-unavailable");
+  }
+  const controller = new AbortController();
+  const abort = () => controller.abort();
+  if (signal?.aborted) abort();
+  else signal?.addEventListener("abort", abort, { once: true });
+  const auth = new AuthorizationHeaderGenerator();
+  const credentials = generateCredentialObject(settings);
+  const headers = new Headers(parseHeaderValues(settings.couchDB_CustomHeaders));
+  const checkCancelled = () => {
+    if (controller.signal.aborted) throw new DOMException("Diagnostic cancelled", "AbortError");
+  };
+  const readJSON = async (path, parameters = {}) => {
+    checkCancelled();
+    const requestURL = new URL(`${root}${path}`);
+    for (const [key, value] of Object.entries(parameters)) requestURL.searchParams.set(key, value);
+    headers.set("authorization", await auth.getAuthorizationHeader(credentials));
+    checkCancelled();
+    const response = await fetch(requestURL.toString(), {
+      method: "GET",
+      headers,
+      cache: "no-store",
+      signal: controller.signal
+    });
+    checkCancelled();
+    if (!response.ok) throw new DiagnosticReadError("document-unreadable", response.status === 404);
+    const result = await response.json();
+    checkCancelled();
+    return result;
+  };
+  let salt;
+  const readSalt = () => salt ??= (async () => {
+    try {
+      const parameters = await readJSON(`/${DOCID_SYNC_PARAMETERS}`);
+      if (typeof parameters.pbkdf2salt !== "string" || !parameters.pbkdf2salt) {
+        throw new DiagnosticReadError("security-seed-unavailable");
+      }
+      const bytes = new Uint8Array(base64ToArrayBuffer(parameters.pbkdf2salt));
+      if (!bytes.length) throw new DiagnosticReadError("security-seed-unavailable");
+      return bytes;
+    } catch {
+      checkCancelled();
+      throw new DiagnosticReadError("security-seed-unavailable");
+    }
+  })();
+  const decrypt = settings.encrypt ? getConfiguredFunctionsForEncryption(
+    settings.passphrase,
+    settings.useDynamicIterationCount,
+    false,
+    readSalt,
+    settings.E2EEAlgorithm,
+    false,
+    () => {
+    }
+  ).outgoing : async (doc) => doc;
+  return {
+    async info() {
+      const info = await readJSON("");
+      return { update_seq: info.update_seq };
+    },
+    async *enumerateIds() {
+      let previous;
+      while (true) {
+        const parameters = { limit: "256" };
+        if (previous !== void 0) {
+          parameters.startkey = JSON.stringify(previous);
+          parameters.skip = "1";
+        }
+        const page = await readJSON("/_all_docs", parameters);
+        if (!Array.isArray(page.rows)) throw new DiagnosticReadError("source-unavailable");
+        if (page.rows.length === 0) return;
+        for (const row of page.rows) {
+          checkCancelled();
+          if (typeof row.id !== "string") throw new DiagnosticReadError("source-unavailable");
+          if (!row.value?.deleted) yield row.id;
+        }
+        const last = page.rows.at(-1).id;
+        if (last === previous) throw new DiagnosticReadError("source-unavailable");
+        previous = last;
+        if (page.rows.length < 256) return;
+      }
+    },
+    async get(id, options = {}) {
+      const parameters = {};
+      if (options.rev !== void 0) parameters.rev = options.rev;
+      if (options.conflicts) parameters.conflicts = "true";
+      if (options.revs) parameters.revs = "true";
+      if (options.revs_info) parameters.revs_info = "true";
+      const raw = await readJSON(`/${encodeURIComponent(id)}`, parameters);
+      if (raw._id !== id || typeof raw._rev !== "string") {
+        throw new DiagnosticReadError("document-unreadable");
+      }
+      const decoded = await decompressDoc(await decrypt(raw));
+      if ("e_" in decoded && decoded.e_ === true || "path" in decoded && typeof decoded.path === "string" && (isEncryptedMeta(decoded) || isObfuscatedEntry(decoded) && isPathProbablyObfuscated(decoded.path))) {
+        throw new DiagnosticReadError("document-unreadable");
+      }
+      checkCancelled();
+      return decoded;
+    },
+    close() {
+      signal?.removeEventListener("abort", abort);
+      controller.abort();
+      return Promise.resolve();
+    }
+  };
+}
+export {
+  createCouchDBDiagnosticSource
+};

package/dist/diagnostics/index.d.ts

@@ -0,0 +1,10 @@
+export { analyseDatabaseUsage } from "./usage.js";
+export type { DatabaseUsageSource, DatabaseUsageResult, DatabaseUsageRow, DatabaseUsageProgress, DatabaseUsageError, } from "./usage.js";
+export { analyseDatabaseIntegrity } from "./integrity.js";
+export { createLocalDiagnosticSource } from "./local.js";
+export { createCouchDBDiagnosticSource } from "./couchdb.js";
+export type { CouchDBDiagnosticSourceOptions } from "./couchdb.js";
+export { createDiagnosticNameMapper, projectIntegrityReport, projectUsageReport, formatDiagnosticJSON, formatIntegrityMarkdown, formatUsageTSV, } from "./reports.js";
+export type { DiagnosticNameMapper, DiagnosticReportVersions, ProjectedDiagnosticReport, ProjectedDatabaseIntegrityReport, ProjectedDatabaseUsageReport, } from "./reports.js";
+export { DiagnosticReadError } from "./types.js";
+export type { DiagnosticStatus, DiagnosticNameMode, DiagnosticSourceName, DiagnosticReason, DiagnosticReadOptions, DiagnosticDatabaseSource, DiagnosticError, DiagnosticContent, DiagnosticCoverage, DiagnosticObservation, DiagnosticIdentitySettings, DatabaseIntegrityResult, DatabaseIntegrityOptions, } from "./types.js";

package/dist/diagnostics/index.js

@@ -0,0 +1,26 @@
+import { analyseDatabaseUsage } from "./usage.js";
+import { analyseDatabaseIntegrity } from "./integrity.js";
+import { createLocalDiagnosticSource } from "./local.js";
+import { createCouchDBDiagnosticSource } from "./couchdb.js";
+import {
+  createDiagnosticNameMapper,
+  projectIntegrityReport,
+  projectUsageReport,
+  formatDiagnosticJSON,
+  formatIntegrityMarkdown,
+  formatUsageTSV
+} from "./reports.js";
+import { DiagnosticReadError } from "./types.js";
+export {
+  DiagnosticReadError,
+  analyseDatabaseIntegrity,
+  analyseDatabaseUsage,
+  createCouchDBDiagnosticSource,
+  createDiagnosticNameMapper,
+  createLocalDiagnosticSource,
+  formatDiagnosticJSON,
+  formatIntegrityMarkdown,
+  formatUsageTSV,
+  projectIntegrityReport,
+  projectUsageReport
+};

package/dist/diagnostics/integrity.d.ts

@@ -0,0 +1,5 @@
+import type { DatabaseIntegrityOptions, DatabaseIntegrityResult } from "./types.js";
+/**
+ * Inspect current normal-file Metadata and content evidence without changing a source.
+ */
+export declare function analyseDatabaseIntegrity(options: DatabaseIntegrityOptions): Promise<DatabaseIntegrityResult>;