@vrtmrz/livesync-commonlib 0.1.42 → 0.1.44

package/dist/diagnostics/reports.js

@@ -0,0 +1,494 @@
+import { createDiagnosticNameMapper, parseDiagnosticPathToken } from "./names.js";
+function copyVersions(versions) {
+  return {
+    ...versions.commonlib === void 0 ? {} : { commonlib: versions.commonlib },
+    ...versions.plugin === void 0 ? {} : { plugin: versions.plugin },
+    ...versions.application === void 0 ? {} : { application: versions.application }
+  };
+}
+function copyCoverage(coverage) {
+  return {
+    status: coverage.status,
+    documents: coverage.documents,
+    metadata: coverage.metadata,
+    excluded: coverage.excluded,
+    conflictBranches: coverage.conflictBranches,
+    contentReads: coverage.contentReads,
+    changedDuringRun: coverage.changedDuringRun
+  };
+}
+function finiteField(key, value, nonnegative = false) {
+  return typeof value === "number" && Number.isFinite(value) && (!nonnegative || value >= 0) ? { [key]: value } : {};
+}
+function projectIntegrityObservation(observation, mapper, projectReference) {
+  return {
+    reference: projectReference(observation.reference),
+    source: observation.source,
+    id: mapper.id(observation.id),
+    ...observation.revision === void 0 ? {} : { revision: mapper.revision(observation.revision) },
+    path: mapper.path(observation.path),
+    ...observation.expectedId === void 0 ? {} : { expectedId: mapper.id(observation.expectedId) },
+    identity: observation.identity,
+    logicallyDeleted: observation.logicallyDeleted,
+    branch: observation.branch,
+    conflictCount: observation.conflictCount,
+    pathIsNFC: observation.pathIsNFC,
+    caseEquivalentPaths: observation.caseEquivalentPaths,
+    nfcEquivalentPaths: observation.nfcEquivalentPaths,
+    ...observation.caseEquivalentGroup === void 0 ? {} : {
+      caseEquivalentGroup: projectReference(observation.caseEquivalentGroup)
+    },
+    ...observation.nfcEquivalentGroup === void 0 ? {} : {
+      nfcEquivalentGroup: projectReference(observation.nfcEquivalentGroup)
+    },
+    ...observation.metadata === void 0 ? {} : {
+      metadata: {
+        type: ["plain", "newnote", "notes"].includes(observation.metadata.type) ? observation.metadata.type : "unknown",
+        ...finiteField("recordedSize", observation.metadata.recordedSize, true),
+        chunkReferences: observation.metadata.chunkReferences,
+        uniqueChunkReferences: observation.metadata.uniqueChunkReferences,
+        embeddedChunkReferences: observation.metadata.embeddedChunkReferences
+      }
+    },
+    otherSourceGroup: observation.otherSourceGroup,
+    vault: {
+      reference: projectReference(observation.vault.reference),
+      status: observation.vault.status,
+      ...observation.vault.reason === void 0 ? {} : { reason: observation.vault.reason },
+      ...finiteField("size", observation.vault.size, true),
+      ...finiteField("contentSizeDifference", observation.vault.contentSizeDifference),
+      ...finiteField("mtimeDifferenceMs", observation.vault.mtimeDifferenceMs)
+    },
+    content: {
+      status: observation.content.status,
+      ...observation.content.reason === void 0 ? {} : { reason: observation.content.reason },
+      chunksRead: observation.content.chunksRead,
+      unavailableChunks: observation.content.unavailableChunks.map((chunk) => ({
+        id: mapper.chunk(chunk.id),
+        status: chunk.status
+      })),
+      ...finiteField("size", observation.content.size, true),
+      ...finiteField("recordedSizeDifference", observation.content.recordedSizeDifference)
+    },
+    comparisons: observation.comparisons.map((comparison) => ({
+      against: projectReference(comparison.against),
+      relation: comparison.relation
+    }))
+  };
+}
+function projectIntegrityError(error, mapper) {
+  return {
+    source: error.source,
+    reason: error.reason,
+    ...error.id === void 0 ? {} : { id: mapper.id(error.id) },
+    ...error.revision === void 0 ? {} : { revision: mapper.revision(error.revision) },
+    ...error.path === void 0 ? {} : { path: mapper.path(error.path) },
+    ...error.chunkId === void 0 ? {} : { chunkId: mapper.chunk(error.chunkId) }
+  };
+}
+function projectIntegrityReport(result, mapper, versions = {}) {
+  const safeReference = /^((local|remote):[0-9]+|vault:(local|remote):[0-9]+|(case|nfc):[0-9]+)$/;
+  const referenceAliases = /* @__PURE__ */ new Map();
+  const projectReference = (value) => {
+    if (safeReference.test(value)) return value;
+    const existing = referenceAliases.get(value);
+    if (existing !== void 0) return existing;
+    const alias = `finding-${String(referenceAliases.size + 1).padStart(3, "0")}`;
+    referenceAliases.set(value, alias);
+    return alias;
+  };
+  return {
+    schemaVersion: 1,
+    kind: "integrity",
+    status: result.status,
+    nameMode: mapper.mode,
+    versions: copyVersions(versions),
+    settings: {
+      encrypt: result.settings.encrypt,
+      usePathObfuscation: result.settings.usePathObfuscation,
+      handleFilenameCaseSensitive: result.settings.handleFilenameCaseSensitive,
+      idDerivationVersion: result.settings.idDerivationVersion,
+      pathNormalizationVersion: result.settings.pathNormalizationVersion
+    },
+    coverage: {
+      local: copyCoverage(result.coverage.local),
+      remote: copyCoverage(result.coverage.remote)
+    },
+    observations: result.observations.map(
+      (observation) => projectIntegrityObservation(observation, mapper, projectReference)
+    ),
+    ...result.pathEquivalenceGroups === void 0 ? {} : {
+      pathEquivalenceGroups: result.pathEquivalenceGroups.map((group) => ({
+        reference: projectReference(group.reference),
+        kind: group.kind === "case" ? "case" : "nfc",
+        members: group.members.map(projectReference)
+      }))
+    },
+    errors: result.errors.map((error) => projectIntegrityError(error, mapper)),
+    scope: {
+      remote: result.scope.remote === "excluded" ? "excluded" : "included",
+      metadata: "normal-files-and-current-conflicts",
+      content: "suspect-groups-only",
+      history: "not-checked",
+      atomicSnapshot: false
+    }
+  };
+}
+function isOrphanRow(row) {
+  return row.id === "__orphan" && row.path === "__orphan" && row.title === "__orphan";
+}
+function projectUsageRow(row, mapper) {
+  const statistics = {
+    uniqueChunkCount: row.uniqueChunkCount,
+    sharedChunkCount: row.sharedChunkCount,
+    uniqueChunkSize: row.uniqueChunkSize,
+    sharedChunkSize: row.sharedChunkSize
+  };
+  if (isOrphanRow(row)) {
+    return {
+      title: "__orphan",
+      id: "__orphan",
+      path: "__orphan",
+      revision: "1-xxxxx",
+      rev: "1",
+      revHash: "xxxxx",
+      ...statistics
+    };
+  }
+  const path = mapper.path(row.path);
+  const revision = mapper.revision(row.revision);
+  return {
+    title: `${path} (${revision})`,
+    id: mapper.id(row.id),
+    path,
+    revision,
+    rev: mapper.mode === "pseudonym" ? /^([1-9][0-9]*)-/.exec(revision)?.[1] ?? "" : row.rev,
+    revHash: mapper.mode === "pseudonym" ? revision.replace(/^[1-9][0-9]*-/, "") : row.revHash,
+    ...statistics
+  };
+}
+function projectUsageError(error, mapper) {
+  return {
+    code: error.code,
+    ...error.id === void 0 ? {} : { id: mapper.id(error.id) },
+    ...error.revision === void 0 ? {} : { revision: mapper.revision(error.revision) }
+  };
+}
+function projectUsageReport(result, mapper, versions = {}) {
+  return {
+    version: 1,
+    kind: "usage",
+    status: result.status,
+    nameMode: mapper.mode,
+    versions: copyVersions(versions),
+    ...result.changedDuringRun === void 0 ? {} : { changedDuringRun: result.changedDuringRun },
+    rows: result.rows.map((row) => projectUsageRow(row, mapper)),
+    errors: result.errors.map((error) => projectUsageError(error, mapper))
+  };
+}
+const USAGE_COLUMNS = [
+  "title",
+  "id",
+  "path",
+  "rev",
+  "revHash",
+  "uniqueChunkCount",
+  "sharedChunkCount",
+  "uniqueChunkSize",
+  "sharedChunkSize"
+];
+const USAGE_HEADERS = [
+  "Title",
+  "Document ID",
+  "Path",
+  "Revision No",
+  "Revision Hash",
+  "Unique Chunk Count",
+  "Shared Chunk Count",
+  "Unique Chunk Size",
+  "Shared Chunk Size"
+];
+function escapeTSVField(value) {
+  const text = String(value);
+  return /[\t\r\n"]/.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+function formatUsageTSV(projected) {
+  const lines = [USAGE_HEADERS.map(escapeTSVField).join("	")];
+  for (const row of projected.rows) {
+    lines.push(USAGE_COLUMNS.map((column) => escapeTSVField(row[column])).join("	"));
+  }
+  return lines.join("\n");
+}
+function formatDiagnosticJSON(projected) {
+  return JSON.stringify(projected, null, 2);
+}
+function longestBacktickRun(value) {
+  let longest = 0;
+  for (const match of value.matchAll(/`+/g)) longest = Math.max(longest, match[0].length);
+  return longest;
+}
+function markdownCode(value) {
+  const text = value.replace(/\r\n?|\n|\t/g, " ").replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+  const fence = "`".repeat(longestBacktickRun(text) + 1);
+  const padding = /^\s|\s$/.test(text) ? " " : "";
+  return `${fence}${padding}${text}${padding}${fence}`;
+}
+function renderMaybe(value) {
+  return value === void 0 ? "?" : markdownCode(value);
+}
+const IDENTITY_LABELS = {
+  consistent: "consistent",
+  "document-id-mismatch": "documentIdMismatch",
+  "namespace-mismatch": "namespaceMismatch"
+};
+function renderState(observation) {
+  return [
+    IDENTITY_LABELS[observation.identity],
+    observation.branch,
+    observation.logicallyDeleted ? "logicallyDeleted" : "logicallyLive",
+    observation.pathIsNFC ? "NFC" : "nonNFC",
+    observation.metadata?.type ?? "notRecorded"
+  ].join("-");
+}
+function renderPathGroup(present, group) {
+  return `${present ? "yes" : "none"}${group === void 0 ? "" : `@${markdownCode(group)}`}`;
+}
+function renderContentStatus(value) {
+  return `${value.status}${value.reason === void 0 ? "" : `(${value.reason})`}`;
+}
+function renderDifference(value) {
+  return `${value > 0 ? "+" : ""}${value}`;
+}
+function renderObservation(observation) {
+  const metadata = observation.metadata;
+  const expectedId = observation.expectedId === observation.id ? "self" : renderMaybe(observation.expectedId);
+  const lines = [
+    `### ${markdownCode(observation.reference)} source=${observation.source}`,
+    `path: ${markdownCode(observation.path)}`,
+    `doc: ${markdownCode(observation.id)} rev=${renderMaybe(observation.revision)} expected=${expectedId}`,
+    `state: ${renderState(observation)} conflicts=${observation.conflictCount}`,
+    `paths: case=${renderPathGroup(observation.caseEquivalentPaths, observation.caseEquivalentGroup)} nfcPeers=${renderPathGroup(observation.nfcEquivalentPaths, observation.nfcEquivalentGroup)} | otherDB=${observation.otherSourceGroup}`,
+    `data: recorded=${metadata?.recordedSize === void 0 ? "?" : `${metadata.recordedSize}B`} chunks=${metadata === void 0 ? "?" : `${metadata.chunkReferences}/${metadata.uniqueChunkReferences}/${metadata.embeddedChunkReferences}`} read=${observation.content.chunksRead}`,
+    `check: content=${renderContentStatus(observation.content)} vault=${renderContentStatus(observation.vault)}@${markdownCode(observation.vault.reference)}`
+  ];
+  const measurements = [];
+  if (observation.content.size !== void 0) measurements.push(`content=${observation.content.size}B`);
+  if (observation.vault.size !== void 0) measurements.push(`vault=${observation.vault.size}B`);
+  if (observation.content.recordedSizeDifference !== void 0)
+    measurements.push(`deltaContent=${renderDifference(observation.content.recordedSizeDifference)}B`);
+  if (observation.vault.contentSizeDifference !== void 0)
+    measurements.push(`deltaVault=${renderDifference(observation.vault.contentSizeDifference)}B`);
+  if (observation.vault.mtimeDifferenceMs !== void 0)
+    measurements.push(`deltaMtime=${renderDifference(observation.vault.mtimeDifferenceMs)}ms`);
+  if (measurements.length > 0) lines.push(`measure: ${measurements.join(" ")}`);
+  if (observation.content.unavailableChunks.length > 0) {
+    lines.push(
+      `- Unavailable chunks: ${observation.content.unavailableChunks.map((chunk) => `${markdownCode(chunk.id)} (${chunk.status})`).join(", ")}`
+    );
+  }
+  if (observation.comparisons.length > 0) {
+    lines.push(
+      `- Comparisons: ${observation.comparisons.map((comparison) => `${markdownCode(comparison.against)}: ${comparison.relation}`).join("; ")}`
+    );
+  }
+  return lines;
+}
+function unavailableStatus(status) {
+  return status === "missing" || status === "unreadable";
+}
+function hasMeasuredDifference(observation) {
+  return [
+    observation.content.recordedSizeDifference,
+    observation.vault.contentSizeDifference,
+    observation.vault.mtimeDifferenceMs
+  ].some((value) => value !== void 0 && value !== 0);
+}
+const REVIEW_CONDITIONS = [
+  ["Identity mismatches", (observation) => observation.identity !== "consistent"],
+  ["Current conflicts", (observation) => observation.branch === "conflict" || observation.conflictCount > 0],
+  ["Case-equivalent paths", (observation) => observation.caseEquivalentPaths],
+  ["NFC-equivalent paths", (observation) => observation.nfcEquivalentPaths],
+  ["Non-NFC paths", (observation) => !observation.pathIsNFC],
+  ["Other database group missing", (observation) => observation.otherSourceGroup === "missing"],
+  ["Missing or unreadable database content", (observation) => unavailableStatus(observation.content.status)],
+  ["Missing or unreadable Vault content", (observation) => unavailableStatus(observation.vault.status)],
+  ["Unavailable chunks", (observation) => observation.content.unavailableChunks.length > 0],
+  [
+    "Different or unavailable comparisons",
+    (observation) => observation.comparisons.some(
+      (comparison) => comparison.relation === "different" || comparison.relation === "unavailable"
+    )
+  ],
+  ["Measured differences", hasMeasuredDifference],
+  ["Metadata not recorded", (observation) => observation.metadata === void 0]
+];
+function renderFindingSummary(observations) {
+  const states = /* @__PURE__ */ new Map();
+  for (const observation of observations) {
+    const state = renderState(observation);
+    states.set(state, (states.get(state) ?? 0) + 1);
+  }
+  const lines = [
+    "## State counts",
+    "",
+    "Counts are observations, not unique files. Local and remote observations are counted separately.",
+    "",
+    ...Array.from(states.keys()).sort().map((state) => `- ${state}: ${states.get(state)}`),
+    ...states.size === 0 ? ["No observations were returned."] : [],
+    "",
+    "## Review index",
+    "",
+    "These references match review conditions, not confirmed corruption. Unlisted observations may contain unchecked content.",
+    ""
+  ];
+  let matched = false;
+  for (const [caption, condition] of REVIEW_CONDITIONS) {
+    const references = observations.filter(condition).map((observation) => markdownCode(observation.reference));
+    if (references.length === 0) continue;
+    matched = true;
+    for (let offset = 0; offset < references.length; offset += 8)
+      lines.push(`- ${caption}: ${references.slice(offset, offset + 8).join(", ")}`);
+  }
+  if (!matched) lines.push("No observations matched the review conditions.");
+  lines.push("");
+  return lines;
+}
+function formatIntegrityMarkdown(projected) {
+  const observations = projected.observations;
+  const mismatchCount = observations.filter((observation) => observation.identity !== "consistent").length;
+  const conflictCount = observations.filter((observation) => observation.branch === "conflict").length;
+  const unavailableContentCount = observations.filter(
+    (observation) => observation.content.status === "missing" || observation.content.status === "unreadable"
+  ).length;
+  const unavailableChunkCount = observations.reduce(
+    (count, observation) => count + observation.content.unavailableChunks.length,
+    0
+  );
+  const coverageRows = [
+    ["Local", projected.coverage.local],
+    ["Remote", projected.coverage.remote]
+  ];
+  const lines = [
+    "# Database integrity report",
+    "",
+    `Status: ${projected.status}`,
+    `Names: ${projected.nameMode}`,
+    "",
+    "A complete status means the declared inspection finished. It does not mean that every finding is healthy.",
+    "Equal content applies only within the inspected scope and is not deletion advice.",
+    "",
+    "## Versions",
+    "",
+    ...projected.versions.commonlib === void 0 ? [] : [`- Commonlib version: ${markdownCode(projected.versions.commonlib)}`],
+    ...projected.versions.plugin === void 0 ? [] : [`- Plug-in version: ${markdownCode(projected.versions.plugin)}`],
+    ...projected.versions.application === void 0 ? [] : [`- Application version: ${markdownCode(projected.versions.application)}`],
+    ...projected.versions.commonlib === void 0 && projected.versions.plugin === void 0 && projected.versions.application === void 0 ? ["No version information was provided."] : [],
+    "",
+    "## Settings",
+    "",
+    `- Encryption: ${projected.settings.encrypt ? "enabled" : "disabled"}`,
+    `- Path obfuscation: ${projected.settings.usePathObfuscation ? "enabled" : "disabled"}`,
+    `- Filename case sensitivity: ${projected.settings.handleFilenameCaseSensitive ? "enabled" : "disabled"}`,
+    `- ID derivation version: ${projected.settings.idDerivationVersion}`,
+    `- Path normalisation version: ${projected.settings.pathNormalizationVersion}`,
+    "",
+    "## Scope",
+    "",
+    projected.scope.remote === "excluded" ? "- Remote database: excluded from this inspection" : "- Remote database: included",
+    "- Metadata: normal files and current conflict branches",
+    "- Metadata values are decoded and decrypted before inspection.",
+    "- Content: suspect groups only",
+    "- Size and time measurements use existing reads; absent measurements were not available or not checked.",
+    "- History: not checked",
+    "- Atomic snapshot: no",
+    "",
+    "## Coverage",
+    "",
+    "| Source | Status | Documents | Metadata | Excluded | Conflict branches | Content reads | Changed during run |",
+    "| --- | --- | ---: | ---: | ---: | ---: | ---: | --- |"
+  ];
+  for (const [source, coverage] of coverageRows) {
+    lines.push(
+      `| ${source} | ${coverage.status} | ${coverage.documents} | ${coverage.metadata} | ${coverage.excluded} | ${coverage.conflictBranches} | ${coverage.contentReads} | ${coverage.changedDuringRun} |`
+    );
+  }
+  lines.push(
+    "",
+    "## Counts",
+    "",
+    `- Identity mismatches: ${mismatchCount}`,
+    `- Conflict observations: ${conflictCount}`,
+    `- Missing or unreadable content observations: ${unavailableContentCount}`,
+    `- Content not checked: ${observations.filter((observation) => observation.content.status === "not-checked").length}`,
+    `- Vault content not checked: ${observations.filter((observation) => observation.vault.status === "not-checked").length}`,
+    `- Unavailable chunks: ${unavailableChunkCount}`,
+    `- Errors: ${projected.errors.length}`,
+    "",
+    "## Reading the findings",
+    "",
+    "- state: identity-branch-logicalDeletion-pathNormalisation-MetadataType; conflicts is the current conflict count.",
+    "- Identity: consistent, documentIdMismatch (document-id-mismatch in JSON), or namespaceMismatch (namespace-mismatch in JSON).",
+    "- Branch: winner or conflict. A winner can still have conflicts; a consistent identity does not prove content is readable or equal.",
+    "- Deletion: logicallyLive or logicallyDeleted. Path: NFC or nonNFC. Metadata: plain, newnote, notes, unknown, or notRecorded when absent.",
+    "- path is the original path or report lookup token. doc is the document ID; rev retains the revision generation.",
+    "- expected=self means the expected ID equals doc exactly. ? means not recorded, never zero.",
+    "- paths: case and nfcPeers are yes or none; @ gives the path-equivalence group reference.",
+    "- otherDB: present, missing, or not-checked for the same identity/path group in the other inspected database; present does not prove equal content.",
+    "- data: recorded is the Metadata size in bytes; chunks=total/unique/embedded references; read counts Chunks read, not network requests.",
+    "- check: available, missing, unreadable, or not-checked; parentheses retain the reason, and vault@ references the Vault comparison target.",
+    "- measure includes available values only: content and vault sizes in bytes, deltaContent=content-Metadata, deltaVault=Vault-content, deltaMtime=Vault-Metadata in milliseconds.",
+    "- Differences retain their sign (+ for positive); absent measurements were unavailable or not checked. Measurements do not select an authoritative version.",
+    "- Unavailable chunks, comparisons, path-equivalence groups, and errors retain their references and reasons.",
+    "",
+    ...renderFindingSummary(observations),
+    "## Findings",
+    ""
+  );
+  if (observations.length === 0) lines.push("No observations were returned.");
+  for (const observation of observations) lines.push(...renderObservation(observation), "");
+  if (projected.pathEquivalenceGroups?.length) {
+    lines.push("## Path equivalence groups", "");
+    for (const group of projected.pathEquivalenceGroups) {
+      lines.push(
+        `- ${markdownCode(group.reference)} (${group.kind}): ${group.members.map(markdownCode).join(", ")}`
+      );
+    }
+    lines.push("");
+  }
+  if (projected.errors.length > 0) {
+    lines.push("## Errors", "");
+    for (const error of projected.errors) {
+      const details = [
+        `source=${error.source}`,
+        `reason=${error.reason}`,
+        ...error.id === void 0 ? [] : [`id=${markdownCode(error.id)}`],
+        ...error.revision === void 0 ? [] : [`revision=${markdownCode(error.revision)}`],
+        ...error.path === void 0 ? [] : [`path=${markdownCode(error.path)}`],
+        ...error.chunkId === void 0 ? [] : [`chunkId=${markdownCode(error.chunkId)}`]
+      ];
+      lines.push(`- ${details.join(", ")}`);
+    }
+  }
+  const body = lines.join("\n").trimEnd();
+  const summaryStatus = ["complete", "partial", "failed", "cancelled"].includes(projected.status) ? projected.status : "unknown";
+  const fenceLength = Math.max(3, longestBacktickRun(body) + 1);
+  const fence = "`".repeat(fenceLength);
+  return [
+    "<details>",
+    `<summary>Database integrity report (${summaryStatus})</summary>`,
+    "",
+    `${fence}text`,
+    body,
+    fence,
+    "</details>"
+  ].join("\n");
+}
+export {
+  createDiagnosticNameMapper,
+  formatDiagnosticJSON,
+  formatIntegrityMarkdown,
+  formatUsageTSV,
+  parseDiagnosticPathToken,
+  projectIntegrityReport,
+  projectUsageReport
+};

package/dist/diagnostics/types.d.ts

@@ -0,0 +1,190 @@
+import type { EntryDoc, MetaEntry } from "../common/types.js";
+import type { IPathService } from "../services/base/IService.js";
+export type DiagnosticStatus = "complete" | "partial" | "failed" | "cancelled";
+export type DiagnosticSourceName = "local" | "remote";
+export type DiagnosticNameMode = "original" | "pseudonym";
+export type DiagnosticReason = "source-unavailable" | "unsupported-remote" | "document-unreadable" | "revision-unavailable" | "invalid-metadata" | "unsupported-content" | "chunk-missing" | "chunk-unreadable" | "security-seed-unavailable" | "content-unreadable" | "source-changed" | "storage-changed" | "configuration-changed";
+export interface DiagnosticReadOptions {
+    rev?: string;
+    conflicts?: boolean;
+    revs?: boolean;
+    revs_info?: boolean;
+}
+export type DiagnosticDocumentReadResult = {
+    id: string;
+    document: EntryDoc;
+    error?: never;
+} | {
+    id: string;
+    error: unknown;
+    document?: never;
+};
+/** Only these reads are available to an analyser; it cannot initialise or repair a database. */
+export interface DiagnosticDatabaseSource {
+    info(): Promise<{
+        update_seq?: string | number;
+        doc_count?: number;
+    }>;
+    enumerateIds(): AsyncIterable<string>;
+    get(id: string, options?: DiagnosticReadOptions): Promise<EntryDoc>;
+    /** Current documents only; exact conflict revisions still use get. Results retain input order. */
+    getMany?(ids: string[], options?: Pick<DiagnosticReadOptions, "conflicts">): Promise<DiagnosticDocumentReadResult[]>;
+}
+export interface DiagnosticError {
+    source: DiagnosticSourceName | "storage" | "configuration";
+    reason: DiagnosticReason;
+    id?: string;
+    revision?: string;
+    path?: string;
+    chunkId?: string;
+}
+export type DiagnosticContent = {
+    status: "available";
+    bytes: Uint8Array<ArrayBuffer>;
+    mtime?: number;
+    reason?: never;
+} | {
+    status: "missing" | "unreadable" | "not-checked";
+    reason?: DiagnosticReason;
+};
+export interface DiagnosticCoverage {
+    status: "complete" | "partial" | "failed" | "not-checked";
+    documents: number;
+    metadata: number;
+    excluded: number;
+    conflictBranches: number;
+    contentReads: number;
+    changedDuringRun: boolean;
+}
+export interface DiagnosticObservation {
+    reference: string;
+    source: DiagnosticSourceName;
+    id: string;
+    revision?: string;
+    /** Exact stored spelling, retained independently of the host's identity normalisation. */
+    path: string;
+    expectedId?: string;
+    identity: "consistent" | "document-id-mismatch" | "namespace-mismatch";
+    logicallyDeleted: boolean;
+    branch: "winner" | "conflict";
+    conflictCount: number;
+    pathIsNFC: boolean;
+    caseEquivalentPaths: boolean;
+    caseEquivalentGroup?: string;
+    nfcEquivalentPaths: boolean;
+    nfcEquivalentGroup?: string;
+    /** Presence of this identity/path group in the other inspected database. */
+    otherSourceGroup: "present" | "missing" | "not-checked";
+    metadata?: {
+        type: string;
+        recordedSize?: number;
+        chunkReferences: number;
+        uniqueChunkReferences: number;
+        embeddedChunkReferences: number;
+    };
+    vault: {
+        reference: string;
+        status: DiagnosticContent["status"];
+        reason?: DiagnosticReason;
+        size?: number;
+        contentSizeDifference?: number;
+        mtimeDifferenceMs?: number;
+    };
+    content: {
+        status: DiagnosticContent["status"];
+        reason?: DiagnosticReason;
+        chunksRead: number;
+        unavailableChunks: {
+            id: string;
+            status: "missing" | "unreadable";
+        }[];
+        size?: number;
+        recordedSizeDifference?: number;
+    };
+    comparisons: {
+        against: string;
+        relation: "equal" | "different" | "unavailable" | "not-checked";
+    }[];
+}
+export interface DiagnosticPathEquivalenceGroup {
+    reference: string;
+    kind: "case" | "nfc";
+    members: string[];
+}
+/** A whitelist: connection details, keys, and passphrases have no report field. */
+export interface DiagnosticIdentitySettings {
+    encrypt: boolean;
+    usePathObfuscation: boolean;
+    handleFilenameCaseSensitive: boolean;
+    idDerivationVersion: number;
+    pathNormalizationVersion: number;
+}
+export interface DatabaseIntegrityResult {
+    schemaVersion: 1;
+    kind: "integrity";
+    status: DiagnosticStatus;
+    settings: DiagnosticIdentitySettings;
+    coverage: Record<DiagnosticSourceName, DiagnosticCoverage>;
+    observations: DiagnosticObservation[];
+    pathEquivalenceGroups?: DiagnosticPathEquivalenceGroup[];
+    errors: DiagnosticError[];
+    /** Scope declarations are part of every report, including a successful one. */
+    scope: {
+        remote: "included" | "excluded";
+        metadata: "normal-files-and-current-conflicts";
+        content: "suspect-groups-only";
+        history: "not-checked";
+        atomicSnapshot: false;
+    };
+}
+export interface DatabaseIntegrityProgress {
+    phase: "metadata" | "content";
+    source?: DiagnosticSourceName;
+    /** Completed documents (including exclusions), or completed suspect content groups. */
+    processed: number;
+    /** A source's document count, or the number of suspect groups; absent until known. */
+    total?: number;
+    elapsedMs: number;
+}
+/** Timing and counters only: no document identifiers, paths, or connection details. */
+export interface DatabaseIntegrityLog {
+    phase: "metadata" | "grouping" | "content";
+    source?: DiagnosticSourceName;
+    event: "started" | "progress" | "completed" | "partial" | "cancelled";
+    processed: number;
+    total?: number;
+    elapsedMs: number;
+    concurrency: number;
+    activeReads: number;
+    peakActiveReads: number;
+    readOperations: number;
+    /** Sum of read durations, including overlap between parallel reads. */
+    readDurationMs: number;
+}
+export interface DatabaseIntegrityOptions {
+    local: DiagnosticDatabaseSource;
+    /** Defaults to true. False inspects only local evidence and never opens the remote source. */
+    includeRemote?: boolean;
+    remote?: () => Promise<DiagnosticDatabaseSource & {
+        close(): Promise<void>;
+    }>;
+    remoteUnavailableReason?: "unsupported-remote" | "source-unavailable";
+    path: Pick<IPathService, "getPath" | "path2id">;
+    settings: DiagnosticIdentitySettings;
+    readStorage(path: string): Promise<DiagnosticContent>;
+    /** Captures profile and relevant settings identity without exporting it. */
+    isConfigurationCurrent(): boolean;
+    signal?: AbortSignal;
+    /** Concurrent Metadata classifications or content groups, default four, clamped to 1–16. Source-internal bulk decoding has its own limit. */
+    concurrency?: number;
+    onProgress?(progress: DatabaseIntegrityProgress): void;
+    onLog?(event: DatabaseIntegrityLog): void;
+}
+export declare class DiagnosticReadError extends Error {
+    readonly reason: DiagnosticReason;
+    readonly missing: boolean;
+    constructor(reason: DiagnosticReason, missing?: boolean);
+}
+export type InspectedMetadata = MetaEntry & {
+    _conflicts?: string[];
+};