@vrtmrz/livesync-commonlib 0.1.4 → 0.1.6

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

@@ -190,4 +190,28 @@ export declare const TweakValuesTemplate: {
 };
 export type TweakValues = Partial<typeof TweakValuesTemplate>;
 export declare const DEVICE_ID_PREFERRED = "PREFERRED";
+export declare const RemotePreferredTweakStatuses: {
+    readonly AVAILABLE: "available";
+    readonly NOT_CONFIGURED: "not-configured";
+    readonly UNAVAILABLE: "unavailable";
+    readonly UNSUPPORTED: "unsupported";
+};
+export type RemotePreferredTweakStatus = (typeof RemotePreferredTweakStatuses)[keyof typeof RemotePreferredTweakStatuses];
+export declare const RemotePreferredTweakNotConfiguredReasons: {
+    readonly MILESTONE_MISSING: "milestone-missing";
+    readonly PREFERRED_VALUES_MISSING: "preferred-values-missing";
+};
+export type RemotePreferredTweakNotConfiguredReason = (typeof RemotePreferredTweakNotConfiguredReasons)[keyof typeof RemotePreferredTweakNotConfiguredReasons];
+export type RemotePreferredTweakResult = {
+    status: typeof RemotePreferredTweakStatuses.AVAILABLE;
+    values: TweakValues;
+} | {
+    status: typeof RemotePreferredTweakStatuses.NOT_CONFIGURED;
+    reason: RemotePreferredTweakNotConfiguredReason;
+} | {
+    status: typeof RemotePreferredTweakStatuses.UNAVAILABLE;
+    error: unknown;
+} | {
+    status: typeof RemotePreferredTweakStatuses.UNSUPPORTED;
+};
 export {};

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

@@ -60,11 +60,23 @@ const TweakValuesTemplate = {
   tweakModified: 0
 };
 const DEVICE_ID_PREFERRED = "PREFERRED";
+const RemotePreferredTweakStatuses = {
+  AVAILABLE: "available",
+  NOT_CONFIGURED: "not-configured",
+  UNAVAILABLE: "unavailable",
+  UNSUPPORTED: "unsupported"
+};
+const RemotePreferredTweakNotConfiguredReasons = {
+  MILESTONE_MISSING: "milestone-missing",
+  PREFERRED_VALUES_MISSING: "preferred-values-missing"
+};
 export {
   CompatibleButLossyChanges,
   DEVICE_ID_PREFERRED,
   IncompatibleChanges,
   IncompatibleChangesInSpecificPattern,
+  RemotePreferredTweakNotConfiguredReasons,
+  RemotePreferredTweakStatuses,
   TweakValuesDefault,
   TweakValuesRecommendedTemplate,
   TweakValuesShouldMatchedTemplate,

package/dist/common/types.d.ts

@@ -21,7 +21,7 @@ import { SETTING_KEY_P2P_DEVICE_NAME, configURIBase, configURIBaseQR, SuffixData
 import { configurationNames, LEVEL_ADVANCED, LEVEL_POWER_USER, LEVEL_EDGE_CASE, type ConfigLevel, type ConfigurationItem, statusDisplay, confName, confDesc } from "./models/shared.definition.configNames.js";
 import type { CustomRegExpSource, CustomRegExpSourceList, ParsedCustomRegExp, Prettify } from "./models/shared.type.util.js";
 import { ProtocolVersions, type ProtocolVersion, DOCID_SYNC_PARAMETERS, DOCID_JOURNAL_SYNC_PARAMETERS, type SyncParameters, DEFAULT_SYNC_PARAMETERS } from "./models/sync.definition.js";
-import { TweakValuesShouldMatchedTemplate, IncompatibleChanges, CompatibleButLossyChanges, IncompatibleChangesInSpecificPattern, TweakValuesRecommendedTemplate, TweakValuesDefault, TweakValuesTemplate, type TweakValues, DEVICE_ID_PREFERRED } from "./models/tweak.definition.js";
+import { TweakValuesShouldMatchedTemplate, IncompatibleChanges, CompatibleButLossyChanges, IncompatibleChangesInSpecificPattern, TweakValuesRecommendedTemplate, TweakValuesDefault, TweakValuesTemplate, type TweakValues, DEVICE_ID_PREFERRED, RemotePreferredTweakStatuses, type RemotePreferredTweakStatus, RemotePreferredTweakNotConfiguredReasons, type RemotePreferredTweakNotConfiguredReason, type RemotePreferredTweakResult } from "./models/tweak.definition.js";
 import type { diff_result_leaf, dmp_result, diff_result, DIFF_CHECK_RESULT_AUTO, diff_check_result } from "./models/diff.definition.js";
 import { PREFIXMD_LOGFILE, PREFIXMD_LOGFILE_UC, FlagFilesOriginal, FlagFilesHumanReadable, FLAGMD_REDFLAG, FLAGMD_REDFLAG2, FLAGMD_REDFLAG2_HR, FLAGMD_REDFLAG3, FLAGMD_REDFLAG3_HR } from "./models/redflag.const.js";
 import { DatabaseConnectingStatuses, type DatabaseConnectingStatus } from "./models/shared.definition.js";
@@ -68,6 +68,11 @@ export { confDesc };
 export { TweakValuesTemplate };
 export type { TweakValues };
 export { DEVICE_ID_PREFERRED };
+export { RemotePreferredTweakStatuses };
+export type { RemotePreferredTweakStatus };
+export { RemotePreferredTweakNotConfiguredReasons };
+export type { RemotePreferredTweakNotConfiguredReason };
+export type { RemotePreferredTweakResult };
 export type { NodeKey };
 export type { DeviceInfo };
 export type { NodeData };

package/dist/common/types.js

@@ -110,7 +110,9 @@ import {
   TweakValuesRecommendedTemplate,
   TweakValuesDefault,
   TweakValuesTemplate,
-  DEVICE_ID_PREFERRED
+  DEVICE_ID_PREFERRED,
+  RemotePreferredTweakStatuses,
+  RemotePreferredTweakNotConfiguredReasons
 } from "./models/tweak.definition.js";
 import {
   PREFIXMD_LOGFILE,
@@ -197,6 +199,8 @@ export {
   REPLICATION_BUSY_TIMEOUT,
   RESULT_NOT_FOUND,
   RESULT_TIMED_OUT,
+  RemotePreferredTweakNotConfiguredReasons,
+  RemotePreferredTweakStatuses,
   RemoteTypes,
   SALT_OF_ID,
   SALT_OF_PASSPHRASE,

package/dist/pouchdb/StreamingFetch.d.ts

@@ -1,6 +1,40 @@
 import type { EntryDoc } from "../common/models/db.definition.js";
 import type { AnyEntry, EntryLeaf } from "../common/models/db.type.js";
 type DBSequence = number | string;
+/**
+ * Identifies the boundary at which Fast Fetch stopped.
+ *
+ * - `transport`: the request or response stream was interrupted. Only failures
+ *   explicitly created at this boundary may be retried.
+ * - `authentication`: CouchDB rejected the supplied credentials.
+ * - `protocol`: CouchDB returned an unsuccessful or structurally invalid
+ *   response, or an unexpected exception escaped the processing pipeline.
+ * - `decryption`: a remote document could not be decrypted or did not produce a
+ *   serialisable PouchDB document.
+ * - `storage`: a local batch or its durable checkpoint could not be written.
+ *
+ * This remains a string-literal union because the values are discriminants, not
+ * data to enumerate, persist, or map to user-interface labels. The constructor
+ * and consumers therefore receive typo checking without a runtime constants
+ * object becoming part of the package API.
+ */
+export type StreamingFetchFailureStage = "transport" | "authentication" | "protocol" | "decryption" | "storage";
+/**
+ * A classified Fast Fetch failure. Retryability is explicit rather than inferred
+ * from the stage so that future exceptions can be narrowed without broadening all
+ * failures at that boundary.
+ */
+export declare class StreamingFetchFailure extends Error {
+    readonly stage: StreamingFetchFailureStage;
+    readonly retryable: boolean;
+    readonly name = "StreamingFetchFailure";
+    constructor(stage: StreamingFetchFailureStage, message: string, retryable: boolean, options?: {
+        status?: number;
+        cause?: unknown;
+    });
+    readonly status?: number;
+}
+export declare function isRetryableStreamingFetchFailure(error: unknown): error is StreamingFetchFailure;
 export type FetchChangesForInitialSyncProgress = {
     totalFetched: number;
     totalValidFetched: number;

package/dist/pouchdb/StreamingFetch.js

@@ -1,58 +1,172 @@
 import { _fetch } from "../common/coreEnvFunctions.js";
 import { LOG_LEVEL_VERBOSE, Logger } from "octagonal-wheels/common/logger";
-function generatePouchDBWriteStream(downloadToDB, decryptFunction, onCheckpoint) {
+class StreamingFetchFailure extends Error {
+  constructor(stage, message, retryable, options) {
+    super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
+    this.stage = stage;
+    this.retryable = retryable;
+    this.status = options?.status;
+  }
+  stage;
+  retryable;
+  name = "StreamingFetchFailure";
+  status;
+}
+function isRetryableStreamingFetchFailure(error) {
+  return error instanceof StreamingFetchFailure && error.retryable;
+}
+function errorMessage(error) {
+  if (error instanceof Error && error.message) return error.message;
+  return String(error);
+}
+function asStreamingFetchFailure(error) {
+  if (error instanceof StreamingFetchFailure) return error;
+  return new StreamingFetchFailure(
+    "protocol",
+    `Fast Fetch encountered an unexpected processing failure: ${errorMessage(error)}`,
+    false,
+    { cause: error }
+  );
+}
+function transportFailure(operation, error) {
+  return new StreamingFetchFailure("transport", `Fast Fetch could not ${operation}: ${errorMessage(error)}`, true, {
+    cause: error
+  });
+}
+function responseFailure(response, operation) {
+  const status = response.status;
+  if (status === 401 || status === 403) {
+    return new StreamingFetchFailure(
+      "authentication",
+      `Fast Fetch could not ${operation}: CouchDB returned HTTP ${status}.`,
+      false,
+      { status }
+    );
+  }
+  const retryable = status === 408 || status === 429 || status >= 500;
+  return new StreamingFetchFailure(
+    retryable ? "transport" : "protocol",
+    `Fast Fetch could not ${operation}: CouchDB returned HTTP ${status}.`,
+    retryable,
+    { status }
+  );
+}
+function ensureResponseOK(response, operation) {
+  if (!response.ok) throw responseFailure(response, operation);
+}
+async function fetchResponse(url, init, operation) {
+  let response;
+  try {
+    response = await _fetch(url, init);
+  } catch (error) {
+    throw transportFailure(operation, error);
+  }
+  ensureResponseOK(response, operation);
+  return response;
+}
+async function readResponseText(response, operation) {
+  try {
+    return await response.text();
+  } catch (error) {
+    throw transportFailure(operation, error);
+  }
+}
+async function saveCheckpoint(onCheckpoint, sequence) {
+  try {
+    await onCheckpoint?.(sequence);
+  } catch (error) {
+    throw new StreamingFetchFailure(
+      "storage",
+      `Fast Fetch could not save its checkpoint: ${errorMessage(error)}`,
+      false,
+      { cause: error }
+    );
+  }
+}
+function generatePouchDBBatchWriter(downloadToDB, decryptFunction, onCheckpoint) {
   let batchBuffer = [];
   let currentBatchSizeBytes = 0;
   let batchLastSequence;
   const BATCH_ITEM_LIMIT = 100;
   const BATCH_SIZE_LIMIT = 2 * 1024 * 1024;
-  let flushPromise = null;
-  const flushToDB = async () => {
+  const flush = async () => {
     if (batchBuffer.length === 0) return;
-    if (flushPromise) {
-      await flushPromise;
-    }
+    const documents = batchBuffer;
+    const checkpoint = batchLastSequence;
+    let results;
     try {
-      flushPromise = downloadToDB.bulkDocs(batchBuffer, { new_edits: false });
-      await flushPromise;
-      if (batchLastSequence !== void 0) {
-        await onCheckpoint?.(batchLastSequence);
-      }
+      results = await downloadToDB.bulkDocs(documents, { new_edits: false });
     } catch (error) {
-      Logger("Error bulk writing to PouchDB:", LOG_LEVEL_VERBOSE);
-      Logger(error, LOG_LEVEL_VERBOSE);
-      throw error;
-    } finally {
-      batchBuffer = [];
-      currentBatchSizeBytes = 0;
-      batchLastSequence = void 0;
-      flushPromise = null;
+      throw new StreamingFetchFailure(
+        "storage",
+        `Fast Fetch could not write a batch to the local database: ${errorMessage(error)}`,
+        false,
+        { cause: error }
+      );
+    }
+    const failedResult = results.find(
+      (result) => "error" in result && Boolean(result.error)
+    );
+    if (failedResult) {
+      const detail = failedResult.message || failedResult.name || "the local database rejected a document";
+      throw new StreamingFetchFailure(
+        "storage",
+        `Fast Fetch could not write a batch to the local database: ${detail}`,
+        false,
+        { cause: failedResult }
+      );
     }
+    if (checkpoint !== void 0) {
+      await saveCheckpoint(onCheckpoint, checkpoint);
+    }
+    batchBuffer = [];
+    currentBatchSizeBytes = 0;
+    batchLastSequence = void 0;
   };
-  return new WritableStream({
-    async write(chunk) {
+  return {
+    async write(doc, sequence) {
+      let decryptedDoc;
+      try {
+        decryptedDoc = await decryptFunction(doc);
+      } catch (error) {
+        throw new StreamingFetchFailure(
+          "decryption",
+          `Fast Fetch could not decrypt a document: ${errorMessage(error)}`,
+          false,
+          { cause: error }
+        );
+      }
+      let serialisedDoc;
       try {
-        const decryptedDoc = await decryptFunction(chunk.doc);
-        batchBuffer.push(decryptedDoc);
-        currentBatchSizeBytes += JSON.stringify(decryptedDoc).length;
-        batchLastSequence = chunk.seq;
-        if (batchBuffer.length >= BATCH_ITEM_LIMIT || currentBatchSizeBytes >= BATCH_SIZE_LIMIT) {
-          await flushToDB();
-        }
+        const serialised = JSON.stringify(decryptedDoc);
+        if (serialised === void 0) throw new Error("the decrypted value is not a document");
+        serialisedDoc = serialised;
       } catch (error) {
-        Logger("Error processing document stream:", LOG_LEVEL_VERBOSE);
-        throw error;
+        throw new StreamingFetchFailure(
+          "decryption",
+          `Fast Fetch produced an invalid decrypted document: ${errorMessage(error)}`,
+          false,
+          { cause: error }
+        );
+      }
+      batchBuffer.push(decryptedDoc);
+      currentBatchSizeBytes += serialisedDoc.length;
+      batchLastSequence = sequence;
+      if (batchBuffer.length >= BATCH_ITEM_LIMIT || currentBatchSizeBytes >= BATCH_SIZE_LIMIT) {
+        await flush();
       }
     },
-    async close() {
-      await flushToDB();
+    async flushThrough(sequence) {
+      await flush();
+      await saveCheckpoint(onCheckpoint, sequence);
     },
-    abort(reason) {
-      Logger(`Stream aborted: ${reason}`, LOG_LEVEL_VERBOSE);
+    flush,
+    abort() {
       batchBuffer = [];
       currentBatchSizeBytes = 0;
+      batchLastSequence = void 0;
     }
-  });
+  };
 }
 function setParamsToURL(url, params) {
   for (const [key, value] of Object.entries(params)) {
@@ -60,21 +174,51 @@ function setParamsToURL(url, params) {
   }
   return url;
 }
-function reachedTargetSequence(seq, targetSeq) {
-  if (seq === void 0 || targetSeq === void 0) return false;
-  const seqStr = seq.toString();
-  const targetSeqStr = targetSeq.toString();
-  if (seqStr === targetSeqStr) return true;
-  const seqNum = parseInt(seqStr.split("-")[0], 10);
-  const targetSeqNum = parseInt(targetSeqStr.split("-")[0], 10);
-  if (!isNaN(seqNum) && !isNaN(targetSeqNum)) {
-    return seqNum >= targetSeqNum;
+function isTargetSequence(sequence, targetSequence) {
+  if (sequence === void 0 || targetSequence === void 0) return false;
+  return sequence.toString() === targetSequence.toString();
+}
+function parseStatusSource(source) {
+  const trimmed = source.trim();
+  if (!trimmed) {
+    throw new StreamingFetchFailure("protocol", "Fast Fetch received no changes status from CouchDB.", false);
+  }
+  const candidates = [trimmed, ...trimmed.split("\n").reverse().filter(Boolean)];
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      if (parsed && typeof parsed === "object") return parsed;
+    } catch {
+    }
+  }
+  throw new StreamingFetchFailure("protocol", "Fast Fetch received an invalid changes status from CouchDB.", false);
+}
+function parseChangeLine(line) {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch (error) {
+    throw new StreamingFetchFailure("protocol", "Fast Fetch received a malformed changes-feed row.", false, {
+      cause: error
+    });
+  }
+  if (!parsed || typeof parsed !== "object" || !("seq" in parsed)) {
+    throw new StreamingFetchFailure(
+      "protocol",
+      "Fast Fetch received a changes-feed row without a sequence.",
+      false
+    );
   }
-  return false;
+  const change = parsed;
+  if (change.seq === void 0 || change.doc !== void 0 && (!change.doc || typeof change.doc !== "object")) {
+    throw new StreamingFetchFailure("protocol", "Fast Fetch received an invalid changes-feed row.", false);
+  }
+  return change;
 }
 async function fetchChangesForInitialSync(downloadToDB, remoteDbUrl, authHeader, decryptFunction, since = "0", onProgress, onCheckpoint) {
   let totalFetched = 0;
   let totalValidFetched = 0;
+  let totalBytes = 0;
   const changesBaseParams = {
     feed: "continuous",
     include_docs: "true",
@@ -88,92 +232,81 @@ async function fetchChangesForInitialSync(downloadToDB, remoteDbUrl, authHeader,
     Accept: "application/json",
     Authorization: authHeader
   };
-  let targetSeq = void 0;
-  try {
-    const dbInfoRes = await _fetch(remoteDbUrl, {
-      headers: fetchHeaders
-    });
-    if (dbInfoRes.ok) {
-      const dbInfo = await dbInfoRes.json();
-      targetSeq = dbInfo.update_seq;
-    }
-  } catch (e) {
-    Logger("Failed to fetch database info for target sequence:", LOG_LEVEL_VERBOSE);
-    Logger(e, LOG_LEVEL_VERBOSE);
-  }
-  const fetchURL = setParamsToURL(new URL(`${remoteDbUrl}/_changes`), {
+  const targetURL = setParamsToURL(new URL(`${remoteDbUrl}/_changes`), {
     ...changesBaseParams,
     feed: "normal",
-    limit: "1"
-  });
-  const infoRes = await _fetch(fetchURL.toString(), {
-    headers: fetchHeaders
+    since: "now",
+    limit: "0"
   });
-  const infoSource = await infoRes.text();
-  const infoSourceTrimmed = infoSource.trim();
-  if (!infoSourceTrimmed) {
-    throw new Error("Failed to fetch changes from CouchDB. No data received.");
+  const targetResponse = await fetchResponse(
+    targetURL.toString(),
+    { headers: fetchHeaders },
+    "capture the changes target"
+  );
+  const targetStatus = parseStatusSource(await readResponseText(targetResponse, "read the changes target"));
+  const finalTargetSeq = targetStatus.last_seq;
+  if (finalTargetSeq === void 0) {
+    throw new StreamingFetchFailure(
+      "protocol",
+      "Fast Fetch could not obtain an authoritative changes target from CouchDB.",
+      false
+    );
   }
-  let info;
-  if (infoSourceTrimmed.startsWith("{") && infoSourceTrimmed.endsWith("}")) {
-    try {
-      info = JSON.parse(infoSourceTrimmed);
-    } catch {
-      const infoLines = infoSourceTrimmed.split("\n").filter((line) => line.trim() !== "");
-      const lastLine = infoLines[infoLines.length - 1];
-      info = JSON.parse(lastLine);
-    }
-  } else {
-    const infoLines = infoSourceTrimmed.split("\n").filter((line) => line.trim() !== "");
-    const lastLine = infoLines[infoLines.length - 1];
-    info = JSON.parse(lastLine);
+  if (isTargetSequence(since, finalTargetSeq)) {
+    Logger("Already at the target sequence. Initial data synchronisation is complete.");
+    return;
   }
-  const pendingDocs = info.pending || 0;
-  const docsToFetch = pendingDocs + 1;
-  if (targetSeq === void 0) {
-    targetSeq = info.last_seq || info.update_seq || info.seq;
+  const fetchURL = setParamsToURL(new URL(`${remoteDbUrl}/_changes`), {
+    ...changesBaseParams,
+    feed: "normal",
+    limit: "0"
+  });
+  const infoResponse = await fetchResponse(fetchURL.toString(), { headers: fetchHeaders }, "read changes status");
+  const info = parseStatusSource(await readResponseText(infoResponse, "read changes status"));
+  if (typeof info.pending !== "number" || info.pending < 0) {
+    throw new StreamingFetchFailure(
+      "protocol",
+      "Fast Fetch received changes status without a valid pending count.",
+      false
+    );
   }
-  const finalTargetSeq = targetSeq ?? "";
-  if (reachedTargetSequence(since, finalTargetSeq)) {
-    Logger("Already at the target sequence. Initial data synchronisation is complete.");
+  const pendingDocs = info.pending;
+  const docsToFetch = pendingDocs;
+  if (pendingDocs === 0) {
+    await saveCheckpoint(onCheckpoint, finalTargetSeq);
+    Logger("No changes remain before the captured Fast Fetch target.");
     return;
   }
   Logger(
-    `Starting initial synchronisation. Current sequence: ${since}, Target sequence: ${finalTargetSeq}, Total documents to fetch: ${docsToFetch}.`
+    `Starting initial synchronisation. Current sequence: ${since}, Target sequence: ${finalTargetSeq}, Estimated documents to fetch: ${docsToFetch}.`
   );
   const controller = new AbortController();
-  const url = setParamsToURL(new URL(`${remoteDbUrl}/_changes`), {
-    ...changesBaseParams
-  });
-  const response = await _fetch(url.toString(), {
-    method: "GET",
-    headers: fetchHeaders,
-    signal: controller.signal
-  });
+  const changesURL = setParamsToURL(new URL(`${remoteDbUrl}/_changes`), changesBaseParams);
+  const response = await fetchResponse(
+    changesURL.toString(),
+    {
+      method: "GET",
+      headers: fetchHeaders,
+      signal: controller.signal
+    },
+    "open the changes feed"
+  );
   if (!response.body) {
-    throw new Error("ReadableStream is not supported by this browser.");
+    throw new StreamingFetchFailure("protocol", "Fast Fetch could not read the CouchDB response stream.", false);
   }
   const sizeCaptureStream = new TransformStream({
-    transform(chunk, controller2) {
-      const chunkSize = chunk.length || chunk.byteLength || 0;
-      totalBytes += chunkSize;
-      controller2.enqueue(chunk);
+    transform(chunk, streamController) {
+      totalBytes += chunk.byteLength;
+      streamController.enqueue(chunk);
     }
   });
   const reader = response.body.pipeThrough(sizeCaptureStream).pipeThrough(new TextDecoderStream()).getReader();
-  const writeDocStream = generatePouchDBWriteStream(downloadToDB, decryptFunction, onCheckpoint);
-  const writer = writeDocStream.getWriter();
+  const batchWriter = generatePouchDBBatchWriter(downloadToDB, decryptFunction, onCheckpoint);
   let buffer = "";
   let lastProgress = 0;
   let lastReportTime = Date.now();
-  let totalBytes = 0;
-  let abortedAfterTargetReached = false;
   const reportProgress = () => {
-    if (totalFetched - lastProgress < 25) {
-      if (Date.now() - lastReportTime < 2e3) {
-        return;
-      }
-    }
+    if (totalFetched - lastProgress < 25 && Date.now() - lastReportTime < 2e3) return;
     lastProgress = totalFetched;
     lastReportTime = Date.now();
     onProgress?.({
@@ -184,80 +317,74 @@ async function fetchChangesForInitialSync(downloadToDB, remoteDbUrl, authHeader,
       totalBytes
     });
   };
+  const processLine = async (line) => {
+    const parsed = parseChangeLine(line);
+    totalFetched++;
+    if (parsed.doc) {
+      await batchWriter.write(parsed.doc, parsed.seq);
+      totalValidFetched++;
+    } else {
+      await batchWriter.flushThrough(parsed.seq);
+    }
+    reportProgress();
+    if (!isTargetSequence(parsed.seq, finalTargetSeq)) return false;
+    await batchWriter.flush();
+    Logger("The captured Fast Fetch target is durable in the local database.");
+    controller.abort();
+    reportProgress();
+    return true;
+  };
   try {
     while (true) {
       reportProgress();
-      const { value, done } = await reader.read();
-      if (value) {
-        totalBytes += value.length;
+      let readResult;
+      try {
+        readResult = await reader.read();
+      } catch (error) {
+        throw transportFailure("read the changes feed", error);
       }
-      if (done) {
-        if (buffer.trim()) {
-          try {
-            totalFetched++;
-            const parsed = JSON.parse(buffer);
-            if (parsed.doc) {
-              await writer.write({ doc: parsed.doc, seq: parsed.seq });
-              totalValidFetched++;
-            } else {
-              await onCheckpoint?.(parsed.seq);
-            }
-            reportProgress();
-          } catch (e) {
-            Logger(`Failed to parse the final line: ${buffer}. Skipping it.`);
-            Logger(e, LOG_LEVEL_VERBOSE);
-          }
-        }
-        await writer.close();
-        break;
+      if (readResult.done) {
+        if (buffer.trim() && await processLine(buffer)) return;
+        await batchWriter.flush();
+        throw new StreamingFetchFailure(
+          "transport",
+          "The CouchDB changes feed ended before Fast Fetch reached its captured target.",
+          true
+        );
       }
-      buffer += value;
+      buffer += readResult.value;
       const lines = buffer.split("\n");
       buffer = lines.pop() || "";
       for (const line of lines) {
         if (!line.trim()) continue;
-        try {
-          const parsed = JSON.parse(line);
-          totalFetched++;
-          if (parsed.doc) {
-            await writer.write({ doc: parsed.doc, seq: parsed.seq });
-            totalValidFetched++;
-          } else {
-            await onCheckpoint?.(parsed.seq);
-          }
-          reportProgress();
-          if (totalFetched >= docsToFetch || reachedTargetSequence(parsed.seq, finalTargetSeq)) {
-            Logger(
-              `All documents fetched. Stopping the stream and writing remaining documents to PouchDB...`
-            );
-            await writer.close();
-            abortedAfterTargetReached = true;
-            controller.abort();
-            reportProgress();
-            return;
-          }
-        } catch (e) {
-          Logger(`JSON parsing failed. Skipping line: ${line}`, LOG_LEVEL_VERBOSE);
-          Logger(e, LOG_LEVEL_VERBOSE);
-        }
+        if (await processLine(line)) return;
       }
     }
-    Logger("Initial data synchronisation via stream has completed.");
-    reportProgress();
   } catch (error) {
-    if (abortedAfterTargetReached && error instanceof DOMException && error.name === "AbortError") {
-      Logger(
-        "Stream has been aborted as the target sequence has been reached. Finalising the synchronising process..."
-      );
-      return;
+    const failure = asStreamingFetchFailure(error);
+    if (failure.stage !== "storage") {
+      try {
+        await batchWriter.flush();
+      } catch (flushError) {
+        batchWriter.abort();
+        throw asStreamingFetchFailure(flushError);
+      }
     }
-    Logger("An error occurred during synchronisation:", LOG_LEVEL_VERBOSE);
-    Logger(error, LOG_LEVEL_VERBOSE);
-    throw error;
+    batchWriter.abort();
+    Logger(`Fast Fetch failed during ${failure.stage}.`, LOG_LEVEL_VERBOSE);
+    Logger(failure, LOG_LEVEL_VERBOSE);
+    throw failure;
   } finally {
+    controller.abort();
+    try {
+      await reader.cancel();
+    } catch {
+    }
     reader.releaseLock();
   }
 }
 export {
-  fetchChangesForInitialSync
+  StreamingFetchFailure,
+  fetchChangesForInitialSync,
+  isRetryableStreamingFetchFailure
 };

package/dist/replication/LiveSyncAbstractReplicator.d.ts

@@ -1,4 +1,4 @@
-import { type EntryDoc, type DatabaseConnectingStatus, type RemoteDBSettings, type EntryLeaf, type TweakValues, type NodeData } from "../common/types.js";
+import { type EntryDoc, type DatabaseConnectingStatus, type RemoteDBSettings, type EntryLeaf, type TweakValues, type RemotePreferredTweakResult, type NodeData } from "../common/types.js";
 import type { RequiredServices } from "../interfaces/ServiceModule.js";
 import type { TranslationParameters } from "../services/base/MessageTranslator.js";
 import type { CommonlibMessageKey } from "../services/base/CommonlibMessages.js";
@@ -60,7 +60,7 @@ export declare abstract class LiveSyncAbstractReplicator {
     abstract setPreferredRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
     abstract fetchRemoteChunks(missingChunks: string[], showResult: boolean): Promise<false | EntryLeaf[]>;
     abstract getRemoteStatus(setting: RemoteDBSettings): Promise<false | RemoteDBStatus>;
-    abstract getRemotePreferredTweakValues(setting: RemoteDBSettings): Promise<false | TweakValues>;
+    abstract getRemotePreferredTweakValues(setting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     abstract countCompromisedChunks(setting?: RemoteDBSettings): Promise<number | boolean>;
     abstract getConnectedDeviceList(setting?: RemoteDBSettings): Promise<false | {
         node_info: Record<string, NodeData>;

package/dist/replication/couchdb/LiveSyncReplicator.d.ts

@@ -1,4 +1,4 @@
-import { type EntryDoc, type RemoteDBSettings, type EntryLeaf, type TweakValues, type SyncParameters, type DatabaseEntry, type NodeData } from "../../common/types.js";
+import { type EntryDoc, type RemoteDBSettings, type EntryLeaf, type SyncParameters, type DatabaseEntry, type NodeData, type RemotePreferredTweakResult } from "../../common/types.js";
 import { LiveSyncAbstractReplicator, type LiveSyncReplicatorEnv, type RemoteDBStatus } from "../LiveSyncAbstractReplicator.js";
 import type { ServiceHub } from "../../services/ServiceHub.js";
 export interface LiveSyncCouchDBReplicatorEnv extends LiveSyncReplicatorEnv {
@@ -73,7 +73,7 @@ export declare class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicato
     tryConnectRemote(setting: RemoteDBSettings, showResult?: boolean): Promise<boolean>;
     resetRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
     setPreferredRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
-    getRemotePreferredTweakValues(setting: RemoteDBSettings): Promise<TweakValues | false>;
+    getRemotePreferredTweakValues(setting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     compactRemote(setting: RemoteDBSettings): Promise<boolean>;
     getRemoteStatus(setting: RemoteDBSettings): Promise<RemoteDBStatus | false>;
     countCompromisedChunks(setting?: RemoteDBSettings): Promise<number | boolean>;

package/dist/replication/couchdb/LiveSyncReplicator.js

@@ -9,7 +9,9 @@ import {
   TweakValuesTemplate,
   DOCID_SYNC_PARAMETERS,
   DEFAULT_SYNC_PARAMETERS,
-  ProtocolVersions
+  ProtocolVersions,
+  RemotePreferredTweakNotConfiguredReasons,
+  RemotePreferredTweakStatuses
 } from "../../common/types.js";
 import {
   resolveWithIgnoreKnownError,
@@ -22,6 +24,7 @@ import {
 } from "../../common/utils.js";
 import { Logger } from "../../common/logger.js";
 import { checkRemoteVersion, countCompromisedChunks } from "../../pouchdb/negotiation.js";
+import { isErrorOfMissingDoc } from "../../pouchdb/utils_couchdb.js";
 import { preprocessOutgoing } from "../../pouchdb/encryption.js";
 import { ensureDatabaseIsCompatible } from "../../pouchdb/LiveSyncDBFunctions.js";
 import {
@@ -1050,23 +1053,73 @@ ${sendingDocs}/(${sentDocsCount} done)`,
   }
   async getRemotePreferredTweakValues(setting) {
     const uri = setting.couchDB_URI.replace(/\/+$/, "") + (setting.couchDB_DBNAME == "" ? "" : "/" + setting.couchDB_DBNAME);
-    const dbRet = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), true);
+    let dbRet;
+    try {
+      dbRet = await this.connectRemoteCouchDBWithSetting(setting, this.isMobile(), true);
+    } catch (ex) {
+      Logger(`Could not connect to the remote database`, LOG_LEVEL_NOTICE);
+      Logger(ex, LOG_LEVEL_VERBOSE);
+      return {
+        status: RemotePreferredTweakStatuses.UNAVAILABLE,
+        error: ex
+      };
+    }
     if (typeof dbRet === "string") {
       Logger(this.translate("liveSyncReplicator.couldNotConnectToURI", { uri, dbRet }), LOG_LEVEL_NOTICE);
-      return false;
+      return {
+        status: RemotePreferredTweakStatuses.UNAVAILABLE,
+        error: new Error(dbRet)
+      };
     }
-    if (!await checkRemoteVersion(dbRet.db, this.migrate.bind(this), VER)) {
-      Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
-      return false;
+    try {
+      if (!await checkRemoteVersion(dbRet.db, this.migrate.bind(this), VER)) {
+        const error = new Error("The remote database version is not compatible");
+        Logger(this.translate("liveSyncReplicator.remoteDbCorrupted"), LOG_LEVEL_NOTICE);
+        return {
+          status: RemotePreferredTweakStatuses.UNAVAILABLE,
+          error
+        };
+      }
+    } catch (ex) {
+      Logger(`Could not check the remote database version`, LOG_LEVEL_NOTICE);
+      Logger(ex, LOG_LEVEL_VERBOSE);
+      return {
+        status: RemotePreferredTweakStatuses.UNAVAILABLE,
+        error: ex
+      };
     }
     try {
       const remoteMilestone = await dbRet.db.get(MILESTONE_DOCID);
-      if (!remoteMilestone) throw new Error("Remote milestone not found");
-      return remoteMilestone?.tweak_values?.[DEVICE_ID_PREFERRED] || false;
+      if (!remoteMilestone) {
+        return {
+          status: RemotePreferredTweakStatuses.NOT_CONFIGURED,
+          reason: RemotePreferredTweakNotConfiguredReasons.MILESTONE_MISSING
+        };
+      }
+      const preferred = remoteMilestone.tweak_values?.[DEVICE_ID_PREFERRED];
+      if (!preferred) {
+        return {
+          status: RemotePreferredTweakStatuses.NOT_CONFIGURED,
+          reason: RemotePreferredTweakNotConfiguredReasons.PREFERRED_VALUES_MISSING
+        };
+      }
+      return {
+        status: RemotePreferredTweakStatuses.AVAILABLE,
+        values: preferred
+      };
     } catch (ex) {
+      if (isErrorOfMissingDoc(ex)) {
+        return {
+          status: RemotePreferredTweakStatuses.NOT_CONFIGURED,
+          reason: RemotePreferredTweakNotConfiguredReasons.MILESTONE_MISSING
+        };
+      }
       Logger(`Could not retrieve remote milestone`, LOG_LEVEL_NOTICE);
       Logger(ex, LOG_LEVEL_VERBOSE);
-      return false;
+      return {
+        status: RemotePreferredTweakStatuses.UNAVAILABLE,
+        error: ex
+      };
     }
   }
   async compactRemote(setting) {

package/dist/replication/journal/JournalSyncCore.d.ts

@@ -3,7 +3,7 @@ import type { ReplicationCallback, ReplicationStat } from "../LiveSyncAbstractRe
 import { type SimpleStore } from "../../common/utils.js";
 import { type CheckPointInfo } from "./JournalSyncTypes.js";
 import type { LiveSyncJournalReplicatorEnv } from "./LiveSyncJournalReplicatorEnv.js";
-import type { IJournalStorage } from "./objectstore/JournalStorageAdapter.js";
+import { type IJournalStorage, type JournalStorageReadResult } from "./objectstore/JournalStorageAdapter.js";
 type ProcessingEntry = PouchDB.Core.PutDocument<EntryDoc> & PouchDB.Core.GetMeta;
 export declare class JournalSyncCore {
     _settings: BucketSyncSetting;
@@ -22,6 +22,7 @@ export declare class JournalSyncCore {
     getHash(settings: BucketSyncSetting): string;
     constructor(settings: BucketSyncSetting, store: SimpleStore<CheckPointInfo>, env: LiveSyncJournalReplicatorEnv, storage: IJournalStorage);
     downloadJson<T>(key: string): Promise<T | false>;
+    downloadJsonWithResult<T>(key: string): Promise<JournalStorageReadResult<T>>;
     uploadJson<T>(key: string, body: T): Promise<boolean>;
     applyNewConfig(settings: BucketSyncSetting, store: SimpleStore<CheckPointInfo>, env: LiveSyncJournalReplicatorEnv): void;
     updateInfo(info: Partial<ReplicationStat>): void;

package/dist/replication/journal/JournalSyncCore.js

@@ -18,6 +18,9 @@ import {
 import { shareRunningResult } from "octagonal-wheels/concurrency/lock";
 import { wrappedDeflate, wrappedInflate } from "../../pouchdb/compress.js";
 import { CheckPointInfoDefault } from "./JournalSyncTypes.js";
+import {
+  JournalStorageReadStatuses
+} from "./objectstore/JournalStorageAdapter.js";
 import {
   clearHandlers,
   createSyncParamsHanderForServer,
@@ -116,6 +119,23 @@ class JournalSyncCore {
       return false;
     }
   }
+  async downloadJsonWithResult(key) {
+    const result = await this.storage.downloadWithResult(key, true);
+    if (result.status !== JournalStorageReadStatuses.AVAILABLE) return result;
+    try {
+      return {
+        status: JournalStorageReadStatuses.AVAILABLE,
+        value: JSON.parse(new TextDecoder().decode(result.value))
+      };
+    } catch (ex) {
+      Logger(`Could not parse downloaded json ${key}`);
+      Logger(ex, LOG_LEVEL_VERBOSE);
+      return {
+        status: JournalStorageReadStatuses.UNAVAILABLE,
+        error: ex
+      };
+    }
+  }
   async uploadJson(key, body) {
     try {
       const data = new TextEncoder().encode(JSON.stringify(body));

package/dist/replication/journal/LiveSyncJournalReplicator.d.ts

@@ -1,4 +1,4 @@
-import { type RemoteDBSettings, type EntryLeaf, type ChunkVersionRange, type TweakValues, type NodeData } from "../../common/types.js";
+import { type RemoteDBSettings, type EntryLeaf, type ChunkVersionRange, type NodeData, type RemotePreferredTweakResult } from "../../common/types.js";
 import { JournalSyncCore } from "./JournalSyncCore.js";
 import { LiveSyncAbstractReplicator, type RemoteDBStatus } from "../LiveSyncAbstractReplicator.js";
 import { type ENSURE_DB_RESULT } from "../../pouchdb/LiveSyncDBFunctions.js";
@@ -29,7 +29,7 @@ export declare class LiveSyncJournalReplicator extends LiveSyncAbstractReplicato
     tryConnectRemote(setting: RemoteDBSettings, showResult?: boolean): Promise<boolean>;
     resetRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
     setPreferredRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
-    getRemotePreferredTweakValues(setting: RemoteDBSettings): Promise<false | TweakValues>;
+    getRemotePreferredTweakValues(_setting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     getRemoteStatus(setting: RemoteDBSettings): Promise<false | RemoteDBStatus>;
     countCompromisedChunks(): Promise<number>;
     getConnectedDeviceList(setting?: RemoteDBSettings): Promise<false | {

package/dist/replication/journal/LiveSyncJournalReplicator.js

@@ -2,7 +2,9 @@ import {
   LOG_LEVEL_NOTICE,
   LOG_LEVEL_VERBOSE,
   DEVICE_ID_PREFERRED,
-  TweakValuesTemplate
+  TweakValuesTemplate,
+  RemotePreferredTweakNotConfiguredReasons,
+  RemotePreferredTweakStatuses
 } from "../../common/types.js";
 import { Logger } from "../../common/logger.js";
 import { JournalSyncCore } from "./JournalSyncCore.js";
@@ -11,6 +13,7 @@ import { LiveSyncAbstractReplicator } from "../LiveSyncAbstractReplicator.js";
 import { ensureRemoteIsCompatible } from "../../pouchdb/LiveSyncDBFunctions.js";
 import { extractObject } from "../../common/utils.js";
 import { clearHandlers } from "../SyncParamsHandler.js";
+import { JournalStorageReadStatuses } from "./objectstore/JournalStorageAdapter.js";
 const MILSTONE_DOCID = "_00000000-milestone.json";
 const currentVersionRange = {
   min: 0,
@@ -256,18 +259,31 @@ ${ex.message}`, LOG_LEVEL_NOTICE);
       throw ex;
     }
   }
-  async getRemotePreferredTweakValues(setting) {
-    try {
-      const remoteMilestone = await this.client.downloadJson(MILSTONE_DOCID);
-      if (!remoteMilestone) {
-        throw new Error("Missing remote milestone");
-      }
-      return remoteMilestone?.tweak_values?.[DEVICE_ID_PREFERRED] || false;
-    } catch (ex) {
-      Logger(`Could not retrieve remote milestone`, LOG_LEVEL_NOTICE);
-      Logger(ex, LOG_LEVEL_VERBOSE);
-      return false;
+  async getRemotePreferredTweakValues(_setting) {
+    const result = await this.client.downloadJsonWithResult(MILSTONE_DOCID);
+    if (result.status === JournalStorageReadStatuses.NOT_FOUND) {
+      return {
+        status: RemotePreferredTweakStatuses.NOT_CONFIGURED,
+        reason: RemotePreferredTweakNotConfiguredReasons.MILESTONE_MISSING
+      };
+    }
+    if (result.status === JournalStorageReadStatuses.UNAVAILABLE) {
+      return {
+        status: RemotePreferredTweakStatuses.UNAVAILABLE,
+        error: result.error
+      };
     }
+    const preferred = result.value.tweak_values?.[DEVICE_ID_PREFERRED];
+    if (!preferred) {
+      return {
+        status: RemotePreferredTweakStatuses.NOT_CONFIGURED,
+        reason: RemotePreferredTweakNotConfiguredReasons.PREFERRED_VALUES_MISSING
+      };
+    }
+    return {
+      status: RemotePreferredTweakStatuses.AVAILABLE,
+      values: preferred
+    };
   }
   async getRemoteStatus(setting) {
     const testClient = new MinioStorageAdapter(setting, this.env);

package/dist/replication/journal/objectstore/JournalStorageAdapter.d.ts

@@ -1,8 +1,23 @@
 import type { RemoteDBStatus } from "../../LiveSyncAbstractReplicator.js";
 import type { BucketSyncSetting } from "../../../common/types.js";
+export declare const JournalStorageReadStatuses: {
+    readonly AVAILABLE: "available";
+    readonly NOT_FOUND: "not-found";
+    readonly UNAVAILABLE: "unavailable";
+};
+export type JournalStorageReadResult<T> = {
+    status: typeof JournalStorageReadStatuses.AVAILABLE;
+    value: T;
+} | {
+    status: typeof JournalStorageReadStatuses.NOT_FOUND;
+} | {
+    status: typeof JournalStorageReadStatuses.UNAVAILABLE;
+    error: unknown;
+};
 export interface IJournalStorage {
     upload(key: string, data: Uint8Array, mime: string): Promise<boolean>;
     download(key: string, ignoreCache?: boolean): Promise<Uint8Array | false>;
+    downloadWithResult(key: string, ignoreCache?: boolean): Promise<JournalStorageReadResult<Uint8Array>>;
     listFiles(from: string, limit?: number): Promise<string[]>;
     deleteFiles(keys: string[]): Promise<boolean>;
     isAvailable(): Promise<boolean>;

package/dist/replication/journal/objectstore/JournalStorageAdapter.js

@@ -0,0 +1,8 @@
+const JournalStorageReadStatuses = {
+  AVAILABLE: "available",
+  NOT_FOUND: "not-found",
+  UNAVAILABLE: "unavailable"
+};
+export {
+  JournalStorageReadStatuses
+};

package/dist/replication/journal/objectstore/MinioStorageAdapter.d.ts

@@ -1,7 +1,7 @@
 import { S3 } from "@aws-sdk/client-s3";
 import { type BucketSyncSetting } from "../../../common/types.js";
 import type { RemoteDBStatus } from "../../LiveSyncAbstractReplicator.js";
-import type { IJournalStorage } from "./JournalStorageAdapter.js";
+import { type IJournalStorage, type JournalStorageReadResult } from "./JournalStorageAdapter.js";
 import type { LiveSyncJournalReplicatorEnv } from "../LiveSyncJournalReplicatorEnv.js";
 export declare class MinioStorageAdapter implements IJournalStorage {
     _instance?: S3;
@@ -13,6 +13,7 @@ export declare class MinioStorageAdapter implements IJournalStorage {
     get customHeaders(): [string, string][];
     _getClient(): S3;
     upload(key: string, data: Uint8Array, mime: string): Promise<boolean>;
+    downloadWithResult(key: string, ignoreCache?: boolean): Promise<JournalStorageReadResult<Uint8Array>>;
     download(key: string, ignoreCache?: boolean): Promise<Uint8Array | false>;
     listFiles(from: string, limit?: number): Promise<string[]>;
     deleteFiles(keys: string[]): Promise<boolean>;

package/dist/replication/journal/objectstore/MinioStorageAdapter.js

@@ -11,6 +11,9 @@ import { ConfiguredRetryStrategy } from "@smithy/util-retry";
 import { promiseWithResolvers } from "octagonal-wheels/promises";
 import { LOG_LEVEL_NOTICE, LOG_LEVEL_VERBOSE } from "../../../common/types.js";
 import { Logger } from "../../../common/logger.js";
+import {
+  JournalStorageReadStatuses
+} from "./JournalStorageAdapter.js";
 import { parseHeaderValues } from "../../../common/utils.js";
 import { runWithTrackedPhysicalRequest } from "../../../services/lib/remoteActivity.js";
 class MinioStorageAdapter {
@@ -110,7 +113,7 @@ class MinioStorageAdapter {
     }
     return false;
   }
-  async download(key, ignoreCache = false) {
+  async downloadWithResult(key, ignoreCache = false) {
     const client = this._getClient();
     const cmd = new GetObjectCommand({
       Bucket: this._settings.bucket,
@@ -121,15 +124,31 @@ class MinioStorageAdapter {
       return await this.runTrackedRequest(async () => {
         const r = await client.send(cmd);
         if (r.Body) {
-          return new Uint8Array(await r.Body.transformToByteArray());
+          return {
+            status: JournalStorageReadStatuses.AVAILABLE,
+            value: new Uint8Array(await r.Body.transformToByteArray())
+          };
         }
-        return false;
+        return {
+          status: JournalStorageReadStatuses.UNAVAILABLE,
+          error: new Error(`The response body for ${key} was empty`)
+        };
       });
     } catch (ex) {
+      if (isMissingObjectError(ex)) {
+        return { status: JournalStorageReadStatuses.NOT_FOUND };
+      }
       Logger(`Could not download ${key}`);
       Logger(ex, LOG_LEVEL_VERBOSE);
+      return {
+        status: JournalStorageReadStatuses.UNAVAILABLE,
+        error: ex
+      };
     }
-    return false;
+  }
+  async download(key, ignoreCache = false) {
+    const result = await this.downloadWithResult(key, ignoreCache);
+    return result.status === JournalStorageReadStatuses.AVAILABLE ? result.value : false;
   }
   async listFiles(from, limit) {
     const client = this._getClient();
@@ -199,6 +218,12 @@ class MinioStorageAdapter {
     }
   }
 }
+function isMissingObjectError(error) {
+  if (!error || typeof error !== "object") return false;
+  const { name, Code, code } = error;
+  const errorCode = Code ?? code ?? name;
+  return errorCode === "NoSuchKey" || errorCode === "NotFound";
+}
 export {
   MinioStorageAdapter
 };

package/dist/replication/trystero/LiveSyncTrysteroReplicator.d.ts

@@ -1,4 +1,4 @@
-import { type RemoteDBSettings, type EntryLeaf, type TweakValues, type LOG_LEVEL, type NodeData } from "../../common/types.js";
+import { type RemoteDBSettings, type EntryLeaf, type RemotePreferredTweakResult, type LOG_LEVEL, type NodeData } from "../../common/types.js";
 import { LiveSyncAbstractReplicator, type LiveSyncReplicatorEnv, type RemoteDBStatus } from "../LiveSyncAbstractReplicator.js";
 import { TrysteroReplicator } from "./TrysteroReplicator.js";
 import { P2PHost, type AcceptanceDecision, type RevokeAcceptanceDecision } from "./TrysteroReplicatorP2PServer.js";
@@ -81,7 +81,7 @@ export declare class LiveSyncTrysteroReplicator extends LiveSyncAbstractReplicat
     setPreferredRemoteTweakSettings(_setting: RemoteDBSettings): Promise<void>;
     fetchRemoteChunks(_missingChunks: string[], _showResult: boolean): Promise<false | EntryLeaf[]>;
     getRemoteStatus(_setting: RemoteDBSettings): Promise<false | RemoteDBStatus>;
-    getRemotePreferredTweakValues(_setting: RemoteDBSettings): Promise<false | TweakValues>;
+    getRemotePreferredTweakValues(_setting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     countCompromisedChunks(): Promise<number>;
     getConnectedDeviceList(_setting?: RemoteDBSettings): Promise<false | {
         node_info: Record<string, NodeData>;

package/dist/replication/trystero/LiveSyncTrysteroReplicator.js

@@ -1,5 +1,6 @@
 import { Logger } from "../../common/logger.js";
 import {
+  RemotePreferredTweakStatuses,
   LOG_LEVEL_NOTICE,
   LOG_LEVEL_INFO,
   LOG_LEVEL_VERBOSE,
@@ -369,7 +370,7 @@ class LiveSyncTrysteroReplicator extends LiveSyncAbstractReplicator {
       "Trying to get tweak values but P2P replication does not support to do this. This operation has been ignored",
       LOG_LEVEL_INFO
     );
-    return Promise.resolve(false);
+    return Promise.resolve({ status: RemotePreferredTweakStatuses.UNSUPPORTED });
   }
   countCompromisedChunks() {
     Logger("P2P Replicator cannot count compromised chunks", LOG_LEVEL_VERBOSE);

package/dist/serviceModules/Rebuilder.js

@@ -5,7 +5,7 @@ import { LOG_LEVEL_NOTICE, LOG_LEVEL_VERBOSE } from "octagonal-wheels/common/log
 import { delay } from "octagonal-wheels/promises";
 import { EVENT_DATABASE_REBUILT } from "../events/coreEvents.js";
 import { ServiceModuleBase } from "./ServiceModuleBase.js";
-import { fetchChangesForInitialSync } from "../pouchdb/StreamingFetch.js";
+import { fetchChangesForInitialSync, isRetryableStreamingFetchFailure } from "../pouchdb/StreamingFetch.js";
 import { getConfiguredFunctionsForEncryption } from "../pouchdb/encryption.js";
 import { AuthorizationHeaderGenerator, generateCredentialObject } from "../replication/httplib.js";
 import { sizeToHumanReadable } from "octagonal-wheels/number";
@@ -376,7 +376,7 @@ Total bytes fetched: ${sizeToHumanReadable(progress.totalBytes)}`,
         );
         break;
       } catch (ex) {
-        if (attempt >= FAST_FETCH_RETRY_DELAYS.length) throw ex;
+        if (!isRetryableStreamingFetchFailure(ex) || attempt >= FAST_FETCH_RETRY_DELAYS.length) throw ex;
         checkpoint = this.getFastFetchCheckpoint(remote);
         since = checkpoint?.sequence ?? since;
         this._log(

package/dist/services/base/IService.d.ts

@@ -1,6 +1,6 @@
 import type { FetchHttpHandler } from "@smithy/fetch-http-handler";
 import { type LOG_LEVEL } from "octagonal-wheels/common/logger";
-import type { AnyEntry, AUTO_MERGED, CouchDBCredentials, diff_result, DocumentID, EntryDoc, EntryHasPath, FileEventItem, FilePath, FilePathWithPrefix, LoadedEntry, MetaEntry, MISSING_OR_ERROR, ObsidianLiveSyncSettings, RemoteDBSettings, SettingsMigrationState, TweakValues, UXFileInfo, UXFileInfoStub } from "../../common/types.js";
+import type { AnyEntry, AUTO_MERGED, CouchDBCredentials, diff_result, DocumentID, EntryDoc, EntryHasPath, FileEventItem, FilePath, FilePathWithPrefix, LoadedEntry, MetaEntry, MISSING_OR_ERROR, ObsidianLiveSyncSettings, RemoteDBSettings, RemotePreferredTweakResult, SettingsMigrationState, TweakValues, UXFileInfo, UXFileInfoStub } from "../../common/types.js";
 import type { LiveSyncLocalDB } from "../../pouchdb/LiveSyncLocalDB.js";
 import type { LiveSyncAbstractReplicator } from "../../replication/LiveSyncAbstractReplicator.js";
 import type { SimpleStore } from "octagonal-wheels/databases/SimpleStoreBase";
@@ -221,7 +221,7 @@ export interface ISettingService {
     deleteSmallConfig(key: string): void;
 }
 export interface ITweakValueService {
-    fetchRemotePreferred(trialSetting: RemoteDBSettings): Promise<TweakValues | false>;
+    fetchRemotePreferred(trialSetting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     checkAndAskResolvingMismatched(preferred: Partial<TweakValues>): Promise<[TweakValues | boolean, boolean]>;
     askResolvingMismatched(preferredSource: TweakValues): Promise<"OK" | "CHECKAGAIN" | "IGNORE">;
     checkAndAskUseRemoteConfiguration(settings: RemoteDBSettings): Promise<{

package/dist/services/base/TweakValueService.d.ts

@@ -1,4 +1,4 @@
-import type { RemoteDBSettings, TweakValues } from "../../common/types.js";
+import type { RemoteDBSettings, RemotePreferredTweakResult, TweakValues } from "../../common/types.js";
 import type { ITweakValueService } from "./IService.js";
 import { ServiceBase, type ServiceContext } from "./ServiceBase.js";
 /**
@@ -9,7 +9,7 @@ export declare abstract class TweakValueService<T extends ServiceContext = Servi
      * Fetch and trial the remote database settings to determine if they are preferred.
      * @param trialSetting The remote database settings to connect.
      */
-    abstract fetchRemotePreferred(trialSetting: RemoteDBSettings): Promise<TweakValues | false>;
+    abstract fetchRemotePreferred(trialSetting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     /**
      * Check and ask the user to resolve any mismatched tweak values.
      * @param preferred The preferred tweak values to check against.

package/dist/services/implements/injectable/InjectableTweakValueService.d.ts

@@ -1,7 +1,7 @@
 import type { ServiceContext } from "../../base/ServiceBase.js";
 import { TweakValueService } from "../../base/TweakValueService.js";
 export declare class InjectableTweakValueService<T extends ServiceContext> extends TweakValueService<T> {
-    fetchRemotePreferred: import("../../lib/HandlerUtils.js").HandlerFunction<(trialSetting: import("../../../settings.js").RemoteDBSettings) => Promise<import("../../../common/types.js").TweakValues | false>, unknown>;
+    fetchRemotePreferred: import("../../lib/HandlerUtils.js").HandlerFunction<(trialSetting: import("../../../settings.js").RemoteDBSettings) => Promise<import("../../../common/types.js").RemotePreferredTweakResult>, unknown>;
     checkAndAskResolvingMismatched: import("../../lib/HandlerUtils.js").HandlerFunction<(preferred: Partial<import("../../../common/types.js").TweakValues>) => Promise<[import("../../../common/types.js").TweakValues | boolean, boolean]>, unknown>;
     askResolvingMismatched: import("../../lib/HandlerUtils.js").HandlerFunction<(preferredSource: import("../../../common/types.js").TweakValues) => Promise<"OK" | "CHECKAGAIN" | "IGNORE">, unknown>;
     checkAndAskUseRemoteConfiguration: import("../../lib/HandlerUtils.js").HandlerFunction<(settings: import("../../../settings.js").RemoteDBSettings) => Promise<{

package/docs/proven-in-use.md

@@ -20,6 +20,8 @@ Commonlib's chunk-reachability tests use real PouchDB revision trees. They verif
 
 Commonlib's injected CouchDB tests verify that a mixed remote chunk batch preserves available documents when another requested ID is absent. Its chunk-delivery tests separately verify that available chunks reach local storage and only absent IDs are marked unavailable. Self-hosted LiveSync supplies the real CouchDB connection and start-up composition, so device-specific replication timing remains downstream integration evidence rather than Commonlib unit coverage.
 
+Commonlib's remote-preference result contract distinguishes available synchronisation settings, a remote which has not stored those settings yet, a failed read, and a remote type which does not support central preferences. Focused CouchDB and Object Storage tests cover absent milestone data separately from transport failures, while Self-hosted LiveSync owns the initialisation choices, cancellation policy, and user-facing explanation.
+
 Most replication and storage services used by the plug-in still enter through explicit `compat/*` paths. Those imports prove that the published compatibility boundary supports the current migration; they are not examples of a finished high-level client API.
 
 The plug-in's manual onboarding and Remote Databases pane use the focused `/remote-configurations` entry to create opaque profile IDs, retain user-visible names, and select main and P2P remotes. Commonlib owns the in-memory profile result contract; Self-hosted LiveSync adds dialogue, Setup URI classification, Fetch or Rebuild scheduling, persistence, restart ordering, and real-Obsidian presentation checks.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "license": "MIT",