@vrtmrz/livesync-commonlib 0.1.43 → 0.1.44

package/dist/diagnostics/names.d.ts

@@ -0,0 +1,16 @@
+import type { DiagnosticNameMode } from "./types.js";
+export interface DiagnosticNameMapper {
+    readonly mode: DiagnosticNameMode;
+    readonly salt?: string;
+    path(value: string): string;
+    id(value: string): string;
+    revision(value: string): string;
+    chunk(value: string): string;
+}
+/** Reads only a complete version-one path token, never a document or revision alias. */
+export declare function parseDiagnosticPathToken(value: string): {
+    salt: string;
+    hash: string;
+} | undefined;
+/** Reuses public report salts without storing paths or a correspondence table outside this mapper. */
+export declare function createDiagnosticNameMapper(mode: DiagnosticNameMode, suppliedSalt?: string): DiagnosticNameMapper;

package/dist/diagnostics/names.js

@@ -0,0 +1,50 @@
+import { Sha256 } from "@aws-crypto/sha256-js";
+const SALT_PATTERN = /^[A-Za-z0-9_-]{8}$/;
+function parseDiagnosticPathToken(value) {
+  const match = /^([A-Za-z0-9_-]{8})\$([0-9a-f]{32})$/.exec(value);
+  return match ? { salt: match[1], hash: match[2] } : void 0;
+}
+function randomSalt() {
+  const bytes = globalThis.crypto.getRandomValues(new Uint8Array(6));
+  return btoa(String.fromCharCode(...bytes)).replaceAll("+", "-").replaceAll("/", "_");
+}
+function nameHash(salt, domain, value) {
+  const hash = new Sha256();
+  hash.update(JSON.stringify(["livesync-diagnostic-v1", salt, domain, value]));
+  return Array.from(hash.digestSync().subarray(0, 16), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function createDiagnosticNameMapper(mode, suppliedSalt) {
+  if (mode === "original") {
+    const original = (value) => value;
+    return { mode, path: original, id: original, revision: original, chunk: original };
+  }
+  const salt = suppliedSalt ?? randomSalt();
+  if (!SALT_PATTERN.test(salt)) throw new Error("Invalid diagnostic salt");
+  const domainMapper = (domain, format) => {
+    const aliases = /* @__PURE__ */ new Map();
+    return (value) => {
+      const existing = aliases.get(value);
+      if (existing !== void 0) return existing;
+      const alias = format(nameHash(salt, domain, value), value);
+      if (aliases.size >= 4096) aliases.clear();
+      aliases.set(value, alias);
+      return alias;
+    };
+  };
+  return {
+    mode,
+    salt,
+    path: domainMapper("path", (hash) => `${salt}$${hash}`),
+    id: domainMapper("document", (hash) => `document-${hash}`),
+    revision: domainMapper("revision", (hash, value) => {
+      const generation = /^([1-9][0-9]*)-.+$/.exec(value)?.[1];
+      const prefix = generation !== void 0 && Number.isSafeInteger(Number(generation)) ? `${generation}-` : "";
+      return `${prefix}psu${hash}`;
+    }),
+    chunk: domainMapper("chunk", (hash) => `chunk-${hash}`)
+  };
+}
+export {
+  createDiagnosticNameMapper,
+  parseDiagnosticPathToken
+};

package/dist/diagnostics/reports.d.ts

@@ -1,19 +1,13 @@
-import type { DatabaseIntegrityResult, DiagnosticCoverage, DiagnosticError, DiagnosticIdentitySettings, DiagnosticNameMode, DiagnosticObservation, DiagnosticSourceName, DiagnosticStatus } from "./types.js";
+import type { DatabaseIntegrityResult, DiagnosticCoverage, DiagnosticError, DiagnosticIdentitySettings, DiagnosticNameMode, DiagnosticObservation, DiagnosticPathEquivalenceGroup, DiagnosticSourceName, DiagnosticStatus } from "./types.js";
 import type { DatabaseUsageError, DatabaseUsageResult, DatabaseUsageStatus } from "./usage.js";
-export interface DiagnosticNameMapper {
-    readonly mode: DiagnosticNameMode;
-    path(value: string): string;
-    id(value: string): string;
-    revision(value: string): string;
-    chunk(value: string): string;
-}
+import type { DiagnosticNameMapper } from "./names.js";
+export { createDiagnosticNameMapper, parseDiagnosticPathToken } from "./names.js";
+export type { DiagnosticNameMapper } from "./names.js";
 export interface DiagnosticReportVersions {
     commonlib?: string;
     plugin?: string;
     application?: string;
 }
-/** Creates run-local name aliases. Each name domain has an independent map. */
-export declare function createDiagnosticNameMapper(mode: DiagnosticNameMode): DiagnosticNameMapper;
 export interface ProjectedDiagnosticError {
     source: DiagnosticError["source"];
     reason: DiagnosticError["reason"];
@@ -36,11 +30,17 @@ export interface ProjectedDiagnosticObservation {
     pathIsNFC: boolean;
     caseEquivalentPaths: boolean;
     nfcEquivalentPaths: boolean;
+    caseEquivalentGroup?: string;
+    nfcEquivalentGroup?: string;
+    metadata?: DiagnosticObservation["metadata"];
     otherSourceGroup: DiagnosticObservation["otherSourceGroup"];
     vault: {
         reference: string;
         status: DiagnosticObservation["vault"]["status"];
         reason?: DiagnosticObservation["vault"]["reason"];
+        size?: number;
+        contentSizeDifference?: number;
+        mtimeDifferenceMs?: number;
     };
     content: {
         status: DiagnosticObservation["content"]["status"];
@@ -50,6 +50,8 @@ export interface ProjectedDiagnosticObservation {
             id: string;
             status: "missing" | "unreadable";
         }[];
+        size?: number;
+        recordedSizeDifference?: number;
     };
     comparisons: {
         against: string;
@@ -65,6 +67,7 @@ export interface ProjectedDatabaseIntegrityReport {
     settings: DiagnosticIdentitySettings;
     coverage: Record<DiagnosticSourceName, DiagnosticCoverage>;
     observations: ProjectedDiagnosticObservation[];
+    pathEquivalenceGroups?: DiagnosticPathEquivalenceGroup[];
     errors: ProjectedDiagnosticError[];
     scope: DatabaseIntegrityResult["scope"];
 }

package/dist/diagnostics/reports.js

@@ -1,26 +1,4 @@
-function createDomainMapper(prefix) {
-  const aliases = /* @__PURE__ */ new Map();
-  return (value) => {
-    const existing = aliases.get(value);
-    if (existing !== void 0) return existing;
-    const alias = `${prefix}-${String(aliases.size + 1).padStart(3, "0")}`;
-    aliases.set(value, alias);
-    return alias;
-  };
-}
-function createDiagnosticNameMapper(mode) {
-  if (mode === "original") {
-    const original = (value) => value;
-    return { mode, path: original, id: original, revision: original, chunk: original };
-  }
-  return {
-    mode,
-    path: createDomainMapper("file"),
-    id: createDomainMapper("document"),
-    revision: createDomainMapper("revision"),
-    chunk: createDomainMapper("chunk")
-  };
-}
+import { createDiagnosticNameMapper, parseDiagnosticPathToken } from "./names.js";
 function copyVersions(versions) {
   return {
     ...versions.commonlib === void 0 ? {} : { commonlib: versions.commonlib },
@@ -39,6 +17,9 @@ function copyCoverage(coverage) {
     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),
@@ -54,11 +35,29 @@ function projectIntegrityObservation(observation, mapper, projectReference) {
     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 }
+      ...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,
@@ -67,7 +66,9 @@ function projectIntegrityObservation(observation, mapper, projectReference) {
       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),
@@ -86,7 +87,7 @@ function projectIntegrityError(error, mapper) {
   };
 }
 function projectIntegrityReport(result, mapper, versions = {}) {
-  const safeReference = /^((local|remote):[0-9]+|vault:(local|remote):[0-9]+)$/;
+  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;
@@ -116,8 +117,16 @@ function projectIntegrityReport(result, mapper, versions = {}) {
     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",
@@ -153,8 +162,8 @@ function projectUsageRow(row, mapper) {
     id: mapper.id(row.id),
     path,
     revision,
-    rev: row.rev,
-    revHash: mapper.mode === "pseudonym" ? revision : row.revHash,
+    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
   };
 }
@@ -213,37 +222,65 @@ function formatUsageTSV(projected) {
 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 backtickRuns = text.match(/`+/g) ?? [];
-  const fence = "`".repeat(Math.max(0, ...backtickRuns.map((run) => run.length)) + 1);
+  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 ? "not recorded" : markdownCode(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)}`,
-    `- Document ID: ${markdownCode(observation.id)}`,
-    `- Revision: ${renderMaybe(observation.revision)}`,
-    `- Expected ID: ${renderMaybe(observation.expectedId)}`,
-    `- Identity: ${observation.identity}`,
-    `- Branch: ${observation.branch}`,
-    `- Logically deleted: ${observation.logicallyDeleted}`,
-    `- Conflict count: ${observation.conflictCount}`,
-    `- Path is NFC: ${observation.pathIsNFC}`,
-    `- Case-equivalent paths: ${observation.caseEquivalentPaths}`,
-    `- NFC-equivalent paths: ${observation.nfcEquivalentPaths}`,
-    `- Other inspected database group: ${observation.otherSourceGroup}`,
-    `- Vault content status: ${observation.vault.status}${observation.vault.reason === void 0 ? "" : ` (${observation.vault.reason})`}`,
-    `- Vault reference: ${markdownCode(observation.vault.reference)}`,
-    `- Content: ${observation.content.status}${observation.content.reason === void 0 ? "" : ` (${observation.content.reason})`}`,
-    `- Chunks read: ${observation.content.chunksRead}`
+    `### ${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(", ")}`
@@ -256,6 +293,66 @@ function renderObservation(observation) {
   }
   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;
@@ -297,8 +394,11 @@ function formatIntegrityMarkdown(projected) {
     "",
     "## 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",
     "",
@@ -319,14 +419,42 @@ function formatIntegrityMarkdown(projected) {
     `- 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) {
@@ -341,13 +469,26 @@ function formatIntegrityMarkdown(projected) {
       lines.push(`- ${details.join(", ")}`);
     }
   }
-  return lines.join("\n").trimEnd();
+  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

@@ -10,13 +10,25 @@ export interface DiagnosticReadOptions {
     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";
@@ -29,6 +41,7 @@ export interface DiagnosticError {
 export type DiagnosticContent = {
     status: "available";
     bytes: Uint8Array<ArrayBuffer>;
+    mtime?: number;
     reason?: never;
 } | {
     status: "missing" | "unreadable" | "not-checked";
@@ -57,13 +70,25 @@ export interface DiagnosticObservation {
     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"];
@@ -73,12 +98,19 @@ export interface DiagnosticObservation {
             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;
@@ -94,17 +126,45 @@ export interface DatabaseIntegrityResult {
     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>;
     }>;
@@ -115,10 +175,10 @@ export interface DatabaseIntegrityOptions {
     /** Captures profile and relevant settings identity without exporting it. */
     isConfigurationCurrent(): boolean;
     signal?: AbortSignal;
-    onProgress?(progress: {
-        phase: "metadata" | "content";
-        processed: number;
-    }): void;
+    /** 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;

package/dist/diagnostics/usage.d.ts

@@ -12,8 +12,12 @@ export interface DatabaseUsageSource {
     get(id: string, options?: DatabaseUsageGetOptions): Promise<object | null | undefined>;
 }
 export interface DatabaseUsageProgress {
+    phase: "reading" | "accounting";
     idsProcessed: number;
     revisionsProcessed: number;
+    processed: number;
+    total: number;
+    totalIsFinal: boolean;
 }
 export type DatabaseUsageStatus = "complete" | "partial" | "failed" | "cancelled";
 export type DatabaseUsageErrorCode = "start_info_read_failed" | "start_update_seq_unavailable" | "end_info_read_failed" | "end_update_seq_unavailable" | "configuration_changed" | "id_enumeration_failed" | "revision_list_read_failed" | "revision_not_found" | "revision_read_failed" | "revision_document_invalid";