@vrtmrz/livesync-commonlib 0.1.40 → 0.1.42

package/README.md

@@ -26,7 +26,7 @@ The package is ESM-only and declares Node 20 or later. Browser entry points are
 | -------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
 | `@vrtmrz/livesync-commonlib`                       | `DirectFileManipulator` for integrations which access CouchDB directly            | Deliberately small, but its high-level lifecycle and file-operation semantics are not final |
 | `@vrtmrz/livesync-commonlib/context`               | Instance-owned events, translation injection, and host-neutral standard-I/O types | Focused, package-tested pre-1.0 contract                                                    |
-| `@vrtmrz/livesync-commonlib/hashing`               | Chunk ID calculation with the database's hash manager                            | Focused, package-tested pre-1.0 contract                                                    |
+| `@vrtmrz/livesync-commonlib/hashing`               | Chunk ID calculation and exact file-content hashing                            | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/browser`               | Rooted File System Access API storage                                             | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/node`                  | Rooted Node storage, Node standard I/O, and selected Node capabilities            | Supported platform façade; keeps Node-only dependencies behind an explicit boundary         |
 | `@vrtmrz/livesync-commonlib/p2p`                   | Host-composed P2P service views and composition helpers                           | Focused, package-tested pre-1.0 contract with a temporary compatibility façade              |
@@ -125,6 +125,10 @@ The `/hashing` entry exports `HashManager` and its `HashManagerCoreOptions` type
 
 `computeHash` returns the Chunk hash, including the `+` prefix when encryption is enabled; the database adds its `h:` namespace separately. Reuse a manager for repeated calculations with the same configuration, create a new manager when changing the legacy algorithm or passphrase, and call `clearCaches()` when retiring it. This releases retained key preparation; it does not erase existing settings or in-flight operations. The entry performs ID calculation and does not write Chunks to a database.
 
+## File content hashing
+
+`computeFileContentHash(content: Blob)` returns a `sha256:<lowercase hexadecimal>` digest of the exact bytes. It includes Blob reading and serialises concurrent hashes to limit whole-file buffer overlap. File-reflection provenance uses this helper to recognise unchanged content independently of retained revision history; it does not replace Chunk ID calculation.
+
 ## Remote connection profiles
 
 New profile-management code can create or update a CouchDB, Object Storage, or P2P connection through the focused remote-configurations entry. Profile IDs provide identity, display names remain editable presentation, and the active selection is explicit. Older flat connection fields remain a runtime projection and an import-compatibility boundary rather than the preferred persistence model.
@@ -135,6 +139,8 @@ See [the remote configuration profile guide](docs/remote-configurations.md) for
 
 CouchDB stores the representations already in use as feature identifiers in its version document. Assess that document before synchronisation or direct file operations, and retain unknown identifiers for host diagnostics. See [the remote feature compatibility contract](docs/remote-feature-compatibility.md) for the wire format, update rules, and recovery boundaries.
 
+The maintained CLI and Obsidian hosts can opt into [Unicode NFC path identity](docs/unicode-path-identity.md) with CouchDB. Existing databases require an explicit Rebuild or Fetch migration before using it.
+
 ## Contract scope
 
 The package is currently an infrastructure and compatibility boundary. The context, rooted-storage, standard-I/O, and revision-tree safety contracts have focused cross-platform, instance-isolation, or real-PouchDB tests. Platform details which cannot be shared, such as file timestamp fidelity and browser permission handling, remain host concerns and are documented separately.

package/dist/API/DirectFileManipulatorV2.js

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

package/dist/API/processSetting.d.ts

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

package/dist/API/processSetting.js

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

package/dist/common/fileContentHash.d.ts

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

package/dist/common/fileContentHash.js

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

package/dist/common/pathIdentity.d.ts

@@ -0,0 +1,10 @@
+import type { EntryHasPath, FilePathWithPrefix } from "./types.js";
+import type { IPathService } from "../services/base/IService.js";
+/** Check the complete source listing before an operation can discard either database. */
+export declare function assertUniqueStoragePathIdentities(paths: Iterable<FilePathWithPrefix>, pathService: Pick<IPathService, "path2id">): Promise<void>;
+/** Distinct Metadata documents must not be merged by a change of path identity. */
+export declare function assertMetadataPathIdentities(entries: AsyncIterable<EntryHasPath & {
+    _id: string;
+}> | Iterable<EntryHasPath & {
+    _id: string;
+}>, pathService: Pick<IPathService, "path2id">, requireMatchingIds: boolean): Promise<void>;

package/dist/common/pathIdentity.js

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

package/dist/common/pathNormalization.d.ts

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

package/dist/common/pathNormalization.js

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

package/dist/common/settingConstants.d.ts

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

package/dist/hashing.d.ts

@@ -1,3 +1,4 @@
 /** Chunk ID calculation using the same hash manager as database writes. */
 export { HashManager } from "./managers/HashManager/HashManager.js";
 export type { HashManagerCoreOptions } from "./managers/HashManager/HashManagerCore.js";
+export { computeFileContentHash } from "./common/fileContentHash.js";

package/dist/hashing.js

@@ -1,4 +1,6 @@
 import { HashManager } from "./managers/HashManager/HashManager.js";
+import { computeFileContentHash } from "./common/fileContentHash.js";
 export {
-  HashManager
+  HashManager,
+  computeFileContentHash
 };

package/dist/interfaces/FileReflectionProvenance.d.ts

@@ -5,6 +5,10 @@ export type FileReflectionProvenanceRecord = {
     revision: string;
     /** Raw modification time of the saved snapshot or storage observed after reflection. */
     observedStorageMtime?: number;
+    /** Algorithm-tagged hash of the exact saved or reflected bytes, independent of revision retention. */
+    contentHash?: string;
+    /** Byte length of the hashed snapshot. Old records may omit both content fields. */
+    contentSize?: number;
 };
 export interface FileReflectionProvenance {
     get(path: FilePathWithPrefix): Promise<FileReflectionProvenanceRecord | undefined>;

package/dist/managers/EntryManager/EntryManager.d.ts

@@ -38,4 +38,5 @@ export declare class EntryManager {
     putDBEntryWithLiveBaseRevision(note: SavingEntry, baseRevision: string, onlyChunks?: boolean): Promise<false | PouchDB.Core.Response>;
     /** Store unknown ancestry as a fresh root; return the Metadata write result or `false`. */
     putDBEntryAsIndependentRoot(note: SavingEntry): Promise<false | PouchDB.Core.Response>;
+    private checkPathIdentity;
 }

package/dist/managers/EntryManager/EntryManager.js

@@ -1,6 +1,7 @@
 import {
   REMOTE_COUCHDB
 } from "../../common/types.js";
+import { assertDatabasePathIdentity } from "../../pouchdb/pathIdentityCompatibility.js";
 import {
   deleteDBEntryByPath,
   getDBEntryByPath,
@@ -65,21 +66,29 @@ class EntryManager {
     return await getDBEntryFromMeta(this.serviceHost, this, meta, dump, waitForReady, localOnly);
   }
   async deleteDBEntry(path, opt) {
+    await this.checkPathIdentity();
     return await deleteDBEntryByPath(this.serviceHost, this, path, opt);
   }
   async storeDeletionAtRevision(path, baseRevision) {
+    await this.checkPathIdentity();
     return await storeDeletionByPathAtRevision(this.serviceHost, this, path, baseRevision);
   }
   async putDBEntry(note, onlyChunks, conflictBaseRev) {
+    await this.checkPathIdentity();
     return await putDBEntry(this.serviceHost, this, note, onlyChunks, conflictBaseRev);
   }
   async putDBEntryWithLiveBaseRevision(note, baseRevision, onlyChunks) {
+    await this.checkPathIdentity();
     return await putDBEntryWithLiveBaseRevision(this.serviceHost, this, note, baseRevision, onlyChunks);
   }
   /** Store unknown ancestry as a fresh root; return the Metadata write result or `false`. */
   async putDBEntryAsIndependentRoot(note) {
+    await this.checkPathIdentity();
     return await putDBEntryAsIndependentRoot(this.serviceHost, this, note);
   }
+  async checkPathIdentity() {
+    await assertDatabasePathIdentity(this.localDatabase, this.options.settingService.currentSettings(), true);
+  }
 }
 export {
   EntryManager

package/dist/managers/EntryManager/EntryManagerImpls.js

@@ -247,12 +247,29 @@ async function getDBEntryMetaByPath(host, { localDatabase }, path, opt, includeD
   const id = await host.services.path.path2id(path);
   try {
     let obj = null;
-    if (opt) {
-      obj = await localDatabase.get(id, opt);
-    } else {
-      obj = await localDatabase.get(id);
+    try {
+      if (opt) {
+        obj = await localDatabase.get(id, opt);
+      } else {
+        obj = await localDatabase.get(id);
+      }
+    } catch (ex) {
+      if (!includeDeleted || opt?.rev !== void 0 || !isErrorOfMissingDoc(ex)) throw ex;
+      for (let attempt = 0; attempt < 3; attempt++) {
+        const result = await localDatabase.allDocs({ keys: [id] });
+        const row = result.rows[0];
+        if (!row || !("value" in row) || !row.value.rev) return false;
+        const candidate = await localDatabase.get(id, { ...opt, rev: row.value.rev });
+        const current = (await localDatabase.allDocs({ keys: [id] })).rows[0];
+        if (!current || !("value" in current) || !current.value.rev) return false;
+        if (current.value.rev === candidate._rev) {
+          obj = candidate;
+          break;
+        }
+      }
+      if (!obj) return false;
     }
-    const deleted = obj?.deleted ?? obj._deleted ?? void 0;
+    const deleted = obj._deleted || obj.deleted;
     if (!includeDeleted && deleted) return false;
     if (obj.type && obj.type == "leaf") {
       return false;

package/dist/pouchdb/StreamingFetch.d.ts

@@ -36,7 +36,9 @@ export declare class StreamingFetchFailure extends Error {
 }
 export declare function isRetryableStreamingFetchFailure(error: unknown): error is StreamingFetchFailure;
 /** Check remote feature requirements before Fast Fetch opens or resets the local database. */
-export declare function checkRemoteFeaturesForInitialSync(remoteDbUrl: string, authHeader: string, customHeaders?: Record<string, string>): Promise<void>;
+export declare function checkRemoteFeaturesForInitialSync(remoteDbUrl: string, authHeader: string, customHeaders?: Record<string, string>, settings?: {
+    pathNormalizationVersion?: number;
+}): Promise<void>;
 export type FetchChangesForInitialSyncProgress = {
     totalFetched: number;
     totalValidFetched: number;

package/dist/pouchdb/StreamingFetch.js

@@ -2,6 +2,7 @@ import { _fetch } from "../common/coreEnvFunctions.js";
 import { LOG_LEVEL_VERBOSE, Logger } from "octagonal-wheels/common/logger";
 import { VERSIONING_DOCID } from "../common/types.js";
 import { assessRemoteFeatureDocument, describeRemoteFeatureRejection } from "./remoteFeatureCompatibility.js";
+import { assertMatchingPathIdentityFeature } from "./pathIdentityCompatibility.js";
 const FAST_FETCH_CHANGES_PAGE_LIMIT = 1e4;
 const FAST_FETCH_CHANGES_PAGE_TIMEOUT_MS = 1e3;
 class StreamingFetchFailure extends Error {
@@ -75,7 +76,7 @@ async function readResponseText(response, operation) {
     throw transportFailure(operation, error);
   }
 }
-async function checkRemoteFeaturesForInitialSync(remoteDbUrl, authHeader, customHeaders) {
+async function checkRemoteFeaturesForInitialSync(remoteDbUrl, authHeader, customHeaders, settings = {}) {
   const headers = new Headers(customHeaders);
   headers.set("Accept", "application/json");
   headers.set("Authorization", authHeader);
@@ -97,6 +98,7 @@ async function checkRemoteFeaturesForInitialSync(remoteDbUrl, authHeader, custom
   const row = result.rows[0];
   if (result.total_rows === 0 && row.error === "not_found") return;
   const assessment = assessRemoteFeatureDocument(row.doc);
+  assertMatchingPathIdentityFeature(row.doc, settings);
   if (assessment.status === "supported" || assessment.status === "older-generation") return;
   throw new StreamingFetchFailure("protocol", describeRemoteFeatureRejection(assessment), false);
 }

package/dist/pouchdb/pathIdentityCompatibility.d.ts

@@ -0,0 +1,8 @@
+import { type EntryDoc } from "../common/types.js";
+type PathIdentitySettings = {
+    pathNormalizationVersion?: number;
+};
+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>;
+export {};

package/dist/pouchdb/pathIdentityCompatibility.js

@@ -0,0 +1,64 @@
+import { VERSIONING_DOCID } from "../common/types.js";
+import { getPathNormalizationVersion } from "../common/pathNormalization.js";
+import {
+  assessRemoteFeatureDocument,
+  NFC_PATH_IDENTITY_FEATURE,
+  REMOTE_FEATURE_GENERATION
+} from "./remoteFeatureCompatibility.js";
+import { isErrorOfMissingDoc } from "./utils_couchdb.js";
+import { bumpRemoteVersion } from "./negotiation.js";
+function assertMatchingPathIdentityFeature(document, settings) {
+  const assessment = assessRemoteFeatureDocument(document);
+  const declared = assessment.status === "supported" && assessment.usedFeatures.includes(NFC_PATH_IDENTITY_FEATURE);
+  if (declared !== (getPathNormalizationVersion(settings) === 1)) {
+    throw new Error(
+      "The database and settings use different path identity versions. Rebuild from the authoritative Vault or Fetch with matching settings before synchronising."
+    );
+  }
+}
+async function hasMetadata(database) {
+  let startkey;
+  for (; ; ) {
+    const result = await database.allDocs({
+      include_docs: true,
+      limit: 100,
+      ...startkey ? { startkey, skip: 1 } : {}
+    });
+    for (const row of result.rows) {
+      if (row.doc?.type === "plain" || row.doc?.type === "newnote") return true;
+    }
+    if (result.rows.length < 100) return false;
+    startkey = result.rows[result.rows.length - 1].id;
+  }
+}
+async function assertDatabasePathIdentity(database, settings, declare = false) {
+  let document;
+  try {
+    document = await database.get(VERSIONING_DOCID);
+  } catch (error) {
+    if (!isErrorOfMissingDoc(error)) throw error;
+  }
+  const assessment = assessRemoteFeatureDocument(document);
+  const declared = assessment.status === "supported" && assessment.usedFeatures.includes(NFC_PATH_IDENTITY_FEATURE);
+  if (getPathNormalizationVersion(settings) === 0) {
+    if (declared) assertMatchingPathIdentityFeature(document, settings);
+    return;
+  }
+  if (declared) return;
+  if (await hasMetadata(database)) {
+    try {
+      document = await database.get(VERSIONING_DOCID);
+    } catch (error) {
+      if (!isErrorOfMissingDoc(error)) throw error;
+    }
+    assertMatchingPathIdentityFeature(document, settings);
+    return;
+  }
+  if (declare && !await bumpRemoteVersion(database, REMOTE_FEATURE_GENERATION, [NFC_PATH_IDENTITY_FEATURE])) {
+    throw new Error("The database path identity could not be declared. Synchronisation has been stopped.");
+  }
+}
+export {
+  assertDatabasePathIdentity,
+  assertMatchingPathIdentityFeature
+};

package/dist/pouchdb/remoteFeatureCompatibility.d.ts

@@ -1,6 +1,7 @@
 export declare const REMOTE_FEATURE_GENERATION = 13;
 export declare const ENCRYPTED_INTERNAL_METADATA_FEATURE = "encrypted-internal-metadata-v1";
 export declare const INDEPENDENT_ID_DERIVATION_FEATURE = "independent-id-derivation-v1";
+export declare const NFC_PATH_IDENTITY_FEATURE = "nfc-path-identity-v1";
 export declare const supportedFeatures: Set<string>;
 export declare function requiredRemoteFeatures(setting: {
     encrypt?: boolean;
@@ -9,6 +10,7 @@ export declare function requiredRemoteFeatures(setting: {
     encryptInternalMetadata?: boolean;
     idDerivationVersion: 0 | 1;
     idDerivationKey: string;
+    pathNormalizationVersion?: number;
 }): string[];
 export declare function usesEncryptedInternalMetadata(setting: {
     encrypt?: boolean;

package/dist/pouchdb/remoteFeatureCompatibility.js

@@ -1,12 +1,19 @@
 import { E2EEAlgorithms, VERSIONING_DOCID } from "../common/types.js";
 import { configuredIdKey } from "../common/idDerivation.js";
+import { getPathNormalizationVersion } from "../common/pathNormalization.js";
 const REMOTE_FEATURE_GENERATION = 13;
 const ENCRYPTED_INTERNAL_METADATA_FEATURE = "encrypted-internal-metadata-v1";
 const INDEPENDENT_ID_DERIVATION_FEATURE = "independent-id-derivation-v1";
-const supportedFeatures = /* @__PURE__ */ new Set([ENCRYPTED_INTERNAL_METADATA_FEATURE, INDEPENDENT_ID_DERIVATION_FEATURE]);
+const NFC_PATH_IDENTITY_FEATURE = "nfc-path-identity-v1";
+const supportedFeatures = /* @__PURE__ */ new Set([
+  ENCRYPTED_INTERNAL_METADATA_FEATURE,
+  INDEPENDENT_ID_DERIVATION_FEATURE,
+  NFC_PATH_IDENTITY_FEATURE
+]);
 function requiredRemoteFeatures(setting) {
   const features = [];
   if (usesEncryptedInternalMetadata(setting)) features.push(ENCRYPTED_INTERNAL_METADATA_FEATURE);
+  if (getPathNormalizationVersion(setting) === 1) features.push(NFC_PATH_IDENTITY_FEATURE);
   if (setting.encrypt && configuredIdKey(setting)) features.push(INDEPENDENT_ID_DERIVATION_FEATURE);
   return features;
 }
@@ -54,6 +61,7 @@ function describeRemoteFeatureRejection(assessment) {
 export {
   ENCRYPTED_INTERNAL_METADATA_FEATURE,
   INDEPENDENT_ID_DERIVATION_FEATURE,
+  NFC_PATH_IDENTITY_FEATURE,
   REMOTE_FEATURE_GENERATION,
   assessRemoteFeatureDocument,
   describeRemoteFeatureRejection,

package/dist/replication/couchdb/LiveSyncReplicator.js

@@ -881,6 +881,16 @@ ${sendingDocs}/(${sentDocsCount} done)`,
     }
     let ownershipTransferred = false;
     try {
+      try {
+        await assertDatabasePathIdentity(dbRet.db, setting);
+        await assertDatabasePathIdentity(this.env.services.database.localDatabase.localDatabase, setting);
+      } catch (error) {
+        recordCompatibilityDecision?.(
+          centralCompatibilityRejected(CENTRAL_COMPATIBILITY_REJECTION_REASONS.INCOMPATIBLE_VERSION)
+        );
+        Logger(error, LOG_LEVEL_NOTICE);
+        return false;
+      }
       if (!skipCheck) {
         this.remoteCleaned = false;
         this.remoteLocked = false;
@@ -1617,6 +1627,7 @@ ${sendingDocs}/(${sentDocsCount} done)`,
     });
   }
 }
+import { assertDatabasePathIdentity } from "../../pouchdb/pathIdentityCompatibility.js";
 export {
   LiveSyncCouchDBReplicator
 };

package/dist/replication/index.d.ts

@@ -8,5 +8,5 @@ export { CENTRAL_REMOTE_ADMINISTRATION_ACTIONS, CENTRAL_REMOTE_ADMINISTRATION_FA
 export type { MilestoneCentralRemoteAdministrationObservation, CentralRemoteAdministrationAction, CentralRemoteAdministrationFailureReason, CentralRemoteAdministrationObservation, CentralRemoteAdministrationRequest, CentralRemoteAdministrationReplicator, CentralRemoteAdministrationResult, CentralRemoteAdministrationRunner, CentralRemoteAdministrationVerificationFailed, CentralRemoteAdministrationVerified, } from "./CentralRemoteAdministration.js";
 export { CENTRAL_COMPATIBILITY_REJECTION_REASONS } from "./CentralCompatibility.js";
 export type { CentralCompatibilityRecoveryHint, CentralCompatibilityRejectionReason } from "./CentralCompatibility.js";
-export { assessRemoteFeatureDocument, describeRemoteFeatureRejection, ENCRYPTED_INTERNAL_METADATA_FEATURE, REMOTE_FEATURE_GENERATION, usesEncryptedInternalMetadata, } from "../pouchdb/remoteFeatureCompatibility.js";
+export { assessRemoteFeatureDocument, describeRemoteFeatureRejection, ENCRYPTED_INTERNAL_METADATA_FEATURE, NFC_PATH_IDENTITY_FEATURE, REMOTE_FEATURE_GENERATION, usesEncryptedInternalMetadata, } from "../pouchdb/remoteFeatureCompatibility.js";
 export type { RemoteFeatureAssessment } from "../pouchdb/remoteFeatureCompatibility.js";