@vrtmrz/livesync-commonlib 0.2.3 → 0.3.1

package/dist/platform/pathTypes.d.ts

@@ -0,0 +1,154 @@
+import type { TaggedType } from "octagonal-wheels/common/types";
+import type { FilePath, FilePathWithPrefix, FilePathWithPrefixLC } from "../common/models/db.type.js";
+import type { PathNormalizationVersion } from "../common/models/setting.type.js";
+import type { PathNamespace } from "../common/pathNamespace.js";
+/**
+ * An original file path without a Metadata namespace.
+ *
+ * @remarks
+ * This compatibility type does not establish NFC form, physical spelling, or
+ * existence. Validate raw storage input with `parseFilePath`.
+ */
+export type { FilePath };
+/**
+ * An original document path with an optional recognised Metadata namespace.
+ *
+ * @remarks
+ * Excludes the legacy comparison-key variant. Route the namespace before
+ * validating the remaining file path for storage access.
+ */
+export type DocumentPath = Exclude<FilePathWithPrefix, FilePathWithPrefixLC>;
+declare const unicodeForm: unique symbol;
+declare const storagePath: unique symbol;
+/**
+ * A file path in Unicode NFC form, without case conversion.
+ *
+ * @remarks
+ * NFC form alone does not establish physical storage spelling or existence.
+ * This refinement is used within normalisation helpers and is not re-exported
+ * by the focused storage entry point.
+ */
+export type NfcFilePath = FilePath & {
+    readonly [unicodeForm]: "NFC";
+};
+/**
+ * A root-relative storage target whose existing components use resolved spelling.
+ *
+ * @remarks
+ * Produced by resolution or supported physical enumeration. A write target may
+ * contain missing components; this type does not guarantee existence, entry
+ * kind, or protection against concurrent changes. The empty path denotes the
+ * root, subject to each operation's root rules.
+ */
+export type StoragePath = FilePath & {
+    readonly [storagePath]: true;
+};
+/**
+ * A path identity key produced by the configured Unicode and case comparison.
+ *
+ * @typeParam Domain - `storage` compares within one storage root; `document`
+ * retains the Metadata namespace so different document kinds remain distinct.
+ *
+ * @remarks
+ * Retain the original path separately. A comparison key cannot establish an
+ * original filename and must not be passed to storage or namespace operations.
+ */
+export type PathComparisonKey<Domain extends "storage" | "document"> = TaggedType<string, `PathComparisonKey:${Domain}`>;
+/** Unicode and case settings used to derive path comparison keys. */
+export type PathComparisonSettings = Readonly<{
+    /** `0` retains Legacy Unicode handling; `1` compares Unicode NFC forms. */
+    pathNormalizationVersion: PathNormalizationVersion;
+    /** Preserve letter case when true; otherwise apply the existing `toLowerCase()` rule. */
+    handleFilenameCaseSensitive: boolean;
+}>;
+/** The namespace and original file path obtained by splitting one document path. */
+export type DocumentPathParts = Readonly<{
+    /** One recognised Metadata namespace, or the empty string for an ordinary file. */
+    prefix: PathNamespace;
+    /** Original spelling after removing that one namespace. */
+    path: FilePath;
+}>;
+/** One immediate physical child returned by a strict directory reader. */
+export type DirectoryEntry = Readonly<{
+    /** Unmodified child name, rather than a relative path containing multiple components. */
+    name: string;
+    /** Entry kind reported by the storage host. */
+    kind: "file" | "directory";
+}>;
+/** A physical child path and its kind, ready for a storage scan to consume. */
+export type StorageEntry = Readonly<{
+    /** Root-relative path retaining the directory listing's actual spelling. */
+    path: StoragePath;
+    /** Entry kind from the same directory listing. */
+    kind: DirectoryEntry["kind"];
+}>;
+/**
+ * Read a directory's complete immediate children using actual names and kinds.
+ *
+ * @param physicalDirectory - Resolved directory path relative to the host's root.
+ * @returns The children, including an empty array for an empty directory, or
+ * `null` only when the directory is absent.
+ * @throws Propagates permission, non-directory, and other I/O failures instead
+ * of reporting absence or a successful partial listing.
+ */
+export type ReadDirectory = (physicalDirectory: StoragePath) => Promise<readonly DirectoryEntry[] | null>;
+/** Resolved paths for a rename which the storage host has yet to perform. */
+export type ResolvedRename = Readonly<{
+    /** Existing source spelling. */
+    source: StoragePath;
+    /** Resolved target, retaining a requested leaf spelling change where applicable. */
+    target: StoragePath;
+}>;
+/**
+ * Resolve NFC-equivalent names through strict directory reads under one policy.
+ *
+ * @remarks
+ * Operations reject ambiguous candidates even when an exact spelling exists,
+ * propagate reader failures, and perform no filesystem mutation. Resolution
+ * does not reserve a path against concurrent changes; hosts own that lifecycle.
+ */
+export interface StoragePathResolver {
+    /**
+     * Resolve an existing file or directory using its physical spelling.
+     *
+     * @param path - Original path relative to the selected storage root.
+     * @returns The resolved path, or `null` when a component is absent.
+     */
+    resolveExisting(path: FilePath): Promise<StoragePath | null>;
+    /**
+     * Resolve a write target while preserving any missing suffix as requested.
+     *
+     * @param path - Original target path relative to the selected storage root.
+     * @returns The resolved target; this operation creates no missing entries.
+     */
+    resolveForWrite(path: FilePath): Promise<StoragePath>;
+    /**
+     * Resolve both sides of an explicit rename, including a leaf spelling change.
+     *
+     * @param source - Original source entry path; the root is not an entry.
+     * @param target - Requested target entry path; the root is not an entry.
+     * @returns Both paths, or `null` when the source is absent. The host retains
+     * responsibility for performing the rename and handling replacement.
+     */
+    resolveRename(source: FilePath, target: FilePath): Promise<ResolvedRename | null>;
+    /**
+     * Enumerate an already resolved directory without resolving each child again.
+     *
+     * @param path - Physical directory path relative to the selected root.
+     * @returns Child paths and kinds, or `null` when the directory is absent.
+     * @throws Rejects equivalent child names as ambiguous before returning a listing.
+     */
+    listResolvedDirectory(path: StoragePath): Promise<readonly StorageEntry[] | null>;
+}
+/** Dependencies and comparison policy for constructing an NFC path resolver. */
+export type StoragePathResolverOptions = Readonly<{
+    /** Strict host enumeration; it must distinguish absence from I/O failure. */
+    readDirectory: ReadDirectory;
+    /** Policy copied at construction; construct a new resolver when settings change. */
+    policy: Readonly<{
+        /** The shared resolver accepts NFC mode only; Legacy hosts retain their existing paths. */
+        pathNormalizationVersion: 1;
+        /** Preserve letter case when true; otherwise compare using `toLowerCase()`. */
+        handleFilenameCaseSensitive: boolean;
+    }>;
+}>;

package/dist/platform/storagePathResolution.d.ts

@@ -0,0 +1,13 @@
+import type { StoragePathResolver as ResolverContract, StoragePathResolverOptions } from "./pathTypes.js";
+export type { DirectoryEntry, ReadDirectory, ResolvedRename, StorageEntry, StoragePathResolver, StoragePathResolverOptions, } from "./pathTypes.js";
+export { AmbiguousNormalisedPathError } from "./AmbiguousNormalisedPathError.js";
+/**
+ * Bind strict directory reads to a copied NFC resolution policy.
+ *
+ * @param options - Host enumeration and explicit NFC/case settings.
+ * @returns A resolver which reads current listings without retaining a directory cache.
+ * @throws Rejects a path version other than `1` or a non-boolean case setting.
+ * @remarks Construction performs no I/O. Resolution performs no mutation or
+ * atomic reservation; construct a new resolver when its comparison settings change.
+ */
+export declare function createStoragePathResolver(options: StoragePathResolverOptions): ResolverContract;

package/dist/platform/storagePathResolution.js

@@ -0,0 +1,9 @@
+import { StoragePathResolver } from "./StoragePathResolver.js";
+import { AmbiguousNormalisedPathError } from "./AmbiguousNormalisedPathError.js";
+function createStoragePathResolver(options) {
+  return new StoragePathResolver(options);
+}
+export {
+  AmbiguousNormalisedPathError,
+  createStoragePathResolver
+};

package/dist/pouchdb/LiveSyncDBFunctions.js

@@ -6,6 +6,7 @@ import {
 } from "../common/types.js";
 import { extractObject, isObjectDifferent, resolveWithIgnoreKnownError } from "../common/utils.js";
 import { assessTweakCompatibility } from "../common/models/tweak.compatibility.js";
+import { getPathNormalizationVersion } from "../common/pathNormalization.js";
 import { usesEncryptedInternalMetadata } from "./remoteFeatureCompatibility.js";
 function getEffectiveTweakValues(setting) {
   return {
@@ -56,6 +57,10 @@ async function ensureRemoteIsCompatible(infoSrc, setting, deviceNodeID, currentV
   if (tweakAssessment.entries.some(({ key, relation }) => key === "idDerivationVersion" && relation === "different")) {
     return "ID_KEY_MISMATCH";
   }
+  if (getPathNormalizationVersion(currentTweakValues) !== getPathNormalizationVersion(preferred_tweak)) {
+    recordTweakAssessment?.(tweakAssessment);
+    return ["MISMATCHED", preferred_tweak];
+  }
   if (!setting.disableCheckingConfigMismatch) {
     recordTweakAssessment?.(tweakAssessment);
     if (tweakAssessment.alignment === "mismatched") {

package/dist/pouchdb/LiveSyncLocalDB.d.ts

@@ -1,6 +1,7 @@
 import { type EntryDoc, type EntryLeaf, type Credential, type RemoteDBSettings, type DocumentID, type FilePathWithPrefix, type FilePath, type DatabaseEntry, type LoadedEntry, type MetaEntry, type SavingEntry, type diff_result_leaf } from "../common/types.js";
 import type { LiveSyncEventHub } from "../hub/hub.js";
 import { LiveSyncManagers } from "../managers/LiveSyncManagers.js";
+import type { ChunkFetchSource } from "../managers/chunkFetchSource.js";
 import type { AutoMergeResult } from "../managers/ConflictManager.js";
 import type { IServiceHub } from "../services/base/IService.js";
 import type { ServiceContext } from "../services/base/ServiceBase.js";
@@ -33,7 +34,12 @@ export type GeneratedChunk = {
     id: DocumentID;
     piece: string;
 };
+/** Optional host IO bound afresh to each prepared database instance. */
+export interface LiveSyncLocalDBRuntimeOptions {
+    createChunkFetchSource?: (database: PouchDB.Database<EntryDoc>) => ChunkFetchSource;
+}
 export declare class LiveSyncLocalDB {
+    private readonly runtimeOptions;
     auth: Credential;
     dbname: string;
     settings: RemoteDBSettings;
@@ -52,7 +58,7 @@ export declare class LiveSyncLocalDB {
     /** Share owner retirement across every close path for one physical database lifetime. */
     private activeReplicationClose?;
     private databaseUnloadNotification?;
-    constructor(dbname: string, env: LiveSyncLocalDBEnv);
+    constructor(dbname: string, env: LiveSyncLocalDBEnv, runtimeOptions?: LiveSyncLocalDBRuntimeOptions);
     /** Notify dependent services at most once for each physical database lifecycle. */
     private notifyDatabaseUnload;
     onunload(): void;

package/dist/pouchdb/LiveSyncLocalDB.js

@@ -16,6 +16,18 @@ function getNoFromRev(rev) {
   return parseInt(rev.split("-")[0]);
 }
 class LiveSyncLocalDB {
+  constructor(dbname, env, runtimeOptions = {}) {
+    this.runtimeOptions = runtimeOptions;
+    this.auth = {
+      username: "",
+      password: ""
+    };
+    this.dbname = dbname;
+    this.env = env;
+    this._log = createInstanceLogFunction("LiveSyncLocalDB", this.env.services.API);
+    this.refreshSettings();
+  }
+  runtimeOptions;
   auth;
   dbname;
   settings;
@@ -47,16 +59,6 @@ class LiveSyncLocalDB {
   /** Share owner retirement across every close path for one physical database lifetime. */
   activeReplicationClose;
   databaseUnloadNotification;
-  constructor(dbname, env) {
-    this.auth = {
-      username: "",
-      password: ""
-    };
-    this.dbname = dbname;
-    this.env = env;
-    this._log = createInstanceLogFunction("LiveSyncLocalDB", this.env.services.API);
-    this.refreshSettings();
-  }
   /** Notify dependent services at most once for each physical database lifecycle. */
   notifyDatabaseUnload() {
     if (!this.databaseUnloadNotification) {
@@ -170,6 +172,7 @@ class LiveSyncLocalDB {
     this.databaseUnloadNotification = void 0;
     const manager = new LiveSyncManagers({
       database: this.localDatabase,
+      chunkFetchSource: this.runtimeOptions?.createChunkFetchSource?.(this.localDatabase),
       APIService: this.env.services.API,
       pathService: this.env.services.path,
       replicatorService: this.env.services.replicator,

package/dist/pouchdb/pathIdentityCompatibility.d.ts

@@ -2,6 +2,14 @@ import { type EntryDoc } from "../common/types.js";
 type PathIdentitySettings = {
     pathNormalizationVersion?: number;
 };
+export type PathIdentityInspection = {
+    readonly status: "empty";
+} | {
+    readonly status: "configured";
+    readonly pathNormalizationVersion: 0 | 1;
+};
+/** Read the existing declaration without changing a remote or declaring a new identity. */
+export declare function inspectDatabasePathIdentity(database: PouchDB.Database<EntryDoc>): Promise<PathIdentityInspection>;
 export declare function assertMatchingPathIdentityFeature(document: unknown, settings: PathIdentitySettings): void;
 /** Refuse an implicit migration. A fresh database may declare its identity before its first Metadata write. */
 export declare function assertDatabasePathIdentity(database: PouchDB.Database<EntryDoc>, settings: PathIdentitySettings, declare?: boolean): Promise<void>;

package/dist/pouchdb/pathIdentityCompatibility.js

@@ -2,11 +2,28 @@ import { VERSIONING_DOCID } from "../common/types.js";
 import { getPathNormalizationVersion } from "../common/pathNormalization.js";
 import {
   assessRemoteFeatureDocument,
+  describeRemoteFeatureRejection,
   NFC_PATH_IDENTITY_FEATURE,
   REMOTE_FEATURE_GENERATION
 } from "./remoteFeatureCompatibility.js";
 import { isErrorOfMissingDoc } from "./utils_couchdb.js";
 import { bumpRemoteVersion } from "./negotiation.js";
+async function inspectDatabasePathIdentity(database) {
+  let document;
+  try {
+    document = await database.get(VERSIONING_DOCID);
+  } catch (error) {
+    if (!isErrorOfMissingDoc(error)) throw error;
+    return (await database.info()).doc_count === 0 ? { status: "empty" } : { status: "configured", pathNormalizationVersion: 0 };
+  }
+  const assessment = assessRemoteFeatureDocument(document);
+  if (assessment.status === "older-generation") return { status: "configured", pathNormalizationVersion: 0 };
+  if (assessment.status !== "supported") throw new Error(describeRemoteFeatureRejection(assessment));
+  return {
+    status: "configured",
+    pathNormalizationVersion: assessment.usedFeatures.includes(NFC_PATH_IDENTITY_FEATURE) ? 1 : 0
+  };
+}
 function assertMatchingPathIdentityFeature(document, settings) {
   const assessment = assessRemoteFeatureDocument(document);
   const declared = assessment.status === "supported" && assessment.usedFeatures.includes(NFC_PATH_IDENTITY_FEATURE);
@@ -60,5 +77,6 @@ async function assertDatabasePathIdentity(database, settings, declare = false) {
 }
 export {
   assertDatabasePathIdentity,
-  assertMatchingPathIdentityFeature
+  assertMatchingPathIdentityFeature,
+  inspectDatabasePathIdentity
 };

package/dist/replication/RemoteResource.d.ts

@@ -1,3 +1,4 @@
+import type { PathIdentityInspection } from "../pouchdb/pathIdentityCompatibility.js";
 import type { RemoteDBSettings, RemotePreferredTweakResult } from "../common/types.js";
 import type { JoinedDevicesSnapshot, ForgetJoinedDeviceResult } from "./joinedDevices.js";
 import type { RemoteDBStatus } from "./LiveSyncAbstractReplicator.js";
@@ -36,6 +37,8 @@ export type RemoteConnectionProbeResult = {
 export interface RemoteConnectionProbe {
     check(options?: RemoteConnectionProbeOptions): Promise<RemoteConnectionProbeResult>;
     getStatus(): Promise<false | RemoteDBStatus>;
+    /** Inspect a central remote before choosing initial host settings. */
+    inspectPathIdentity?(): Promise<PathIdentityInspection>;
     dispose(): Promise<void>;
 }
 /** A finite preferred-tweak reader bound to one trial configuration. */

package/dist/replication/couchdb/LiveSyncReplicator.js

@@ -169,7 +169,8 @@ class LiveSyncCouchDBReplicator extends LiveSyncAbstractReplicator {
       value.enableCompression,
       value.pathNormalizationVersion,
       value.readChunksOnline,
-      value.useRequestAPI
+      value.useRequestAPI,
+      value.useCouchDBCacheControlHeadersOnly === true
     ]);
     const binding = identity(snapshot);
     let connection;
@@ -721,7 +722,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
         if (cancellationRequested()) {
           return false;
         }
-        if (await this.ensurePBKDF2Salt(setting, showResult, !retrying) === false || cancellationRequested()) {
+        if (await this.ensurePBKDF2Salt(setting, showResult, false) === false || cancellationRequested()) {
           return false;
         }
         if (this.controller) {
@@ -1442,7 +1443,8 @@ ${sendingDocs}/(${sentDocsCount} done)`,
       {
         ...connectionOptions,
         encryptionAlgorithm: settings.E2EEAlgorithm,
-        encryptInternalMetadata: usesEncryptedInternalMetadata(settings)
+        encryptInternalMetadata: usesEncryptedInternalMetadata(settings),
+        useCouchDBCacheControlHeadersOnly: settings.useCouchDBCacheControlHeadersOnly === true
       }
     );
   }

package/dist/replication/index.d.ts

@@ -13,3 +13,5 @@ export { assessRemoteFeatureDocument, describeRemoteFeatureRejection, ENCRYPTED_
 export type { RemoteFeatureAssessment } from "../pouchdb/remoteFeatureCompatibility.js";
 export type { JoinedDevice, JoinedDevicesSnapshot, ForgetJoinedDeviceResult } from "./joinedDevices.js";
 export type { ReplicationStatics, CouchDBReplicationPhase, CouchDBReplicationProgress, ReplicationCheckpointProgress, } from "../common/models/shared.definition.js";
+export { inspectDatabasePathIdentity } from "../pouchdb/pathIdentityCompatibility.js";
+export type { PathIdentityInspection } from "../pouchdb/pathIdentityCompatibility.js";

package/dist/replication/index.js

@@ -43,6 +43,7 @@ import {
   REMOTE_FEATURE_GENERATION,
   usesEncryptedInternalMetadata
 } from "../pouchdb/remoteFeatureCompatibility.js";
+import { inspectDatabasePathIdentity } from "../pouchdb/pathIdentityCompatibility.js";
 export {
   CAPABILITY_NOT_APPLICABLE,
   CAPABILITY_NOT_IMPLEMENTED,
@@ -72,6 +73,7 @@ export {
   centralRemoteAdministrationVerified,
   defineReplicatorProviderDefinitions,
   describeRemoteFeatureRejection,
+  inspectDatabasePathIdentity,
   isCentralRemoteAdministrationVerified,
   isReplicationCompleted,
   milestoneSatisfiesCentralRemoteAdministration,

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

@@ -62,6 +62,7 @@ export declare class JournalSyncCore {
     private _createSendCompressTransformStream;
     private _createSendUploadWritableStream;
     sendLocalJournal(showMessage?: boolean): Promise<boolean>;
+    hasRemoteJournals(): Promise<boolean>;
     _getRemoteJournals(): Promise<string[]>;
     processDocuments(allDocs: ProcessingEntry[]): Promise<boolean>;
     private _createReceiveReadableStream;

package/dist/replication/journal/JournalSyncCore.js

@@ -33,6 +33,7 @@ import {
   encryptBinary as encryptBinaryHKDF,
   decryptBinary as decryptBinaryHKDF
 } from "octagonal-wheels/encryption/hkdf";
+import { assertDatabasePathIdentity } from "../../pouchdb/pathIdentityCompatibility.js";
 const RECORD_SPLIT = `
 `;
 const UNIT_SPLIT = ``;
@@ -45,6 +46,9 @@ function serializeDoc(doc) {
   }
   return te.encode(JSON.stringify(doc) + RECORD_SPLIT);
 }
+function isJournalKey(key) {
+  return !key.startsWith("_");
+}
 class JournalSyncCore {
   _settings;
   storage;
@@ -217,7 +221,13 @@ class JournalSyncCore {
     this.syncParamsHandler = void 0;
   }
   async resetCheckpointInfo() {
-    await this.updateCheckPointInfo((info) => ({ ...CheckPointInfoDefault }));
+    await this.updateCheckPointInfo(() => ({
+      ...CheckPointInfoDefault,
+      knownIDs: /* @__PURE__ */ new Set(),
+      sentIDs: /* @__PURE__ */ new Set(),
+      receivedFiles: /* @__PURE__ */ new Set(),
+      sentFiles: /* @__PURE__ */ new Set()
+    }));
   }
   getJournalEpochFromSyncParams(params) {
     return `${params.protocolVersion}:${params.pbkdf2salt}`;
@@ -262,32 +272,33 @@ class JournalSyncCore {
   }
   async resetBucket() {
     this.resetAllCaches();
-    let files = [];
     try {
+      const skippedFiles = [];
+      let from = "";
+      let files;
       do {
-        files = await this.storage.listFiles("", 100);
-        if (files.length == 0) {
-          break;
-        }
-        if (!await this.storage.deleteFiles(files)) {
-          return false;
+        files = await this.storage.listFiles(from, 100);
+        if (files.length > 0) {
+          const nextFrom = files[files.length - 1];
+          if (nextFrom <= from) {
+            throw new Error("Journal reset listing did not advance. Control documents have been retained.");
+          }
+          skippedFiles.push(...files.filter((key) => !isJournalKey(key)));
+          const journals = files.filter(isJournalKey);
+          if (journals.length > 0 && !await this.storage.deleteFiles(journals)) return false;
+          from = nextFrom;
         }
-      } while (files.length != 0);
+      } while (files.length > 0);
+      while (skippedFiles.length > 0) {
+        if (!await this.storage.deleteFiles(skippedFiles.splice(0, 100))) return false;
+      }
     } catch (ex) {
       Logger(`WARNING! Could not delete files.`, LOG_LEVEL_NOTICE, "reset-bucket");
       Logger(ex, LOG_LEVEL_VERBOSE);
       return false;
     }
-    const journals = await this._getRemoteJournals();
-    if (journals.length == 0) {
-      Logger("Nothing to delete!", LOG_LEVEL_NOTICE);
-      return true;
-    }
-    if (!await this.storage.deleteFiles(journals)) {
-      return false;
-    }
-    Logger(`${journals.length} items has been deleted!`, LOG_LEVEL_NOTICE);
     await this.resetCheckpointInfo();
+    Logger("Remote bucket cleared", LOG_LEVEL_NOTICE);
     return true;
   }
   getRemoteKey() {
@@ -502,6 +513,7 @@ class JournalSyncCore {
     });
   }
   async sendLocalJournal(showMessage = false) {
+    await assertDatabasePathIdentity(this.db, this.currentSettings);
     this.updateInfo({ syncStatus: "JOURNAL_SEND" });
     return await shareRunningResult("send_journal_stream", async () => {
       this.requestedStop = false;
@@ -544,12 +556,15 @@ class JournalSyncCore {
       }
     });
   }
+  async hasRemoteJournals() {
+    return (await this.storage.listFiles("", 1)).some(isJournalKey);
+  }
   async _getRemoteJournals() {
     const checkPointInfo = await this.getCheckpointInfo();
     const StartAfter = [...checkPointInfo.receivedFiles.keys()].sort(
       (a, b) => b.localeCompare(a, void 0, { numeric: true })
     )[0];
-    const files = (await this.storage.listFiles(StartAfter)).filter((e) => !e.startsWith("_"));
+    const files = (await this.storage.listFiles(StartAfter)).filter(isJournalKey);
     if (!files) return [];
     return files.sort((a, b) => a.localeCompare(b, void 0, { numeric: true }));
   }
@@ -723,6 +738,7 @@ class JournalSyncCore {
     });
   }
   async receiveRemoteJournal(showMessage = false) {
+    await assertDatabasePathIdentity(this.db, this.currentSettings);
     this.updateInfo({ syncStatus: "JOURNAL_RECEIVE" });
     return await shareRunningResult("receive_journal_stream", async () => {
       this.requestedStop = false;

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

@@ -1,3 +1,4 @@
+import type { PathIdentityInspection } from "../../pouchdb/pathIdentityCompatibility.js";
 import { type RemoteDBSettings, type ChunkVersionRange, type NodeData, type RemotePreferredTweakResult, type TweakAssessment } from "../../common/types.js";
 import { JournalSyncCore } from "./JournalSyncCore.js";
 import { LiveSyncAbstractReplicator, type RemoteDBStatus } from "../LiveSyncAbstractReplicator.js";
@@ -23,7 +24,16 @@ export declare class LiveSyncJournalReplicator extends LiveSyncAbstractReplicato
     private journalTransferStopGeneration;
     getReplicationPBKDF2Salt(setting: RemoteDBSettings, refresh?: boolean): Promise<Uint8Array<ArrayBuffer>>;
     setupJournalSyncClient(settings?: RemoteDBSettings): JournalSyncCore;
-    ensureBucketIsCompatible(deviceNodeID: string, currentVersionRange: ChunkVersionRange, setting?: RemoteDBSettings, client?: Pick<JournalSyncCore, "downloadJsonWithResult" | "getCheckpointInfo" | "uploadJson">, recordTweakAssessment?: (assessment: TweakAssessment) => void): Promise<ENSURE_DB_RESULT>;
+    private isBucketPathIdentityCompatible;
+    private isBucketIdDerivationCompatible;
+    private assertBucketIdentity;
+    /** Inspect identity without publishing this node, preparing a seed, or changing checkpoints. */
+    assertRemotePathIdentity(setting: RemoteDBSettings): Promise<void>;
+    /** Read path identity for initial setup without publishing a node or preparing a seed. */
+    inspectRemotePathIdentity(setting: RemoteDBSettings): Promise<PathIdentityInspection>;
+    /** Lock existing journals for replacement without declaring the replacement's identity. */
+    markRemoteLockedForRebuild(setting: RemoteDBSettings): Promise<void>;
+    ensureBucketIsCompatible(deviceNodeID: string, currentVersionRange: ChunkVersionRange, setting?: RemoteDBSettings, client?: Pick<JournalSyncCore, "downloadJsonWithResult" | "getCheckpointInfo" | "uploadJson" | "hasRemoteJournals">, recordTweakAssessment?: (assessment: TweakAssessment) => void): Promise<ENSURE_DB_RESULT>;
     constructor(env: LiveSyncJournalReplicatorEnv);
     migrate(from: number, to: number): Promise<boolean>;
     /**
@@ -62,8 +72,6 @@ export declare class LiveSyncJournalReplicator extends LiveSyncAbstractReplicato
     setPreferredRemoteTweakSettings(setting: RemoteDBSettings): Promise<void>;
     getRemotePreferredTweakValues(setting: RemoteDBSettings): Promise<RemotePreferredTweakResult>;
     getRemoteStatus(setting: RemoteDBSettings): Promise<false | RemoteDBStatus>;
-    private supportsLegacyPathIdentity;
-    private assertLegacyPathIdentity;
     private getOwnJoinedDeviceId;
     getJoinedDevices(setting: RemoteDBSettings): Promise<JoinedDevicesSnapshot>;
     forgetJoinedDevice(setting: RemoteDBSettings, deviceId: string): Promise<ForgetJoinedDeviceResult>;