@vrtmrz/livesync-commonlib 0.1.24 → 0.1.26

package/dist/API/processSetting.d.ts

@@ -37,5 +37,5 @@ type ErasureProperties = keyof ObsidianLiveSyncSettings;
  * @returns Generated setup URI
  */
 export declare function encodeSettingsToSetupURI(settingString: ObsidianLiveSyncSettings, passphrase: string, removeProperties?: ErasureProperties[], skipDefaultValue?: boolean): Promise<string>;
-export declare function decodeSettingsFromSetupURI(uri: string, passphrase: string): Promise<false | ObsidianLiveSyncSettings>;
+export declare function decodeSettingsFromSetupURI(uri: string, passphrase: string): Promise<false | Omit<ObsidianLiveSyncSettings, "P2P_iceServers" | "P2P_iceServersExpiresAt">>;
 export {};

package/dist/API/processSetting.js

@@ -4,11 +4,13 @@ import { decodeAnyArray, encodeAnyArray } from "octagonal-wheels/object";
 import {
   DEFAULT_SETTINGS,
   KeyIndexOfSettings,
-  LOG_LEVEL_NOTICE
+  LOG_LEVEL_NOTICE,
+  omitP2PRuntimeSettings
 } from "../common/types.js";
 import { decryptString, encryptString } from "../encryption/stringEncryption.js";
 import { LOG_LEVEL_VERBOSE, Logger } from "octagonal-wheels/common/logger";
 function encodeSettingsToQRCodeData(settings) {
+  settings = omitP2PRuntimeSettings(settings);
   const fullIndexes = Object.entries(KeyIndexOfSettings);
   let maxIndex = 0;
   for (const [, index] of fullIndexes) {
@@ -48,7 +50,7 @@ function decodeSettingsFromQRCodeData(qr) {
       LOG_LEVEL_VERBOSE
     );
   }
-  return newSettings;
+  return omitP2PRuntimeSettings(newSettings);
 }
 var OutputFormat = /* @__PURE__ */ ((OutputFormat2) => {
   OutputFormat2[OutputFormat2["SVG"] = 0] = "SVG";
@@ -99,8 +101,11 @@ const necessaryErasureProperties = [
 ];
 async function encodeSettingsToSetupURI(settingString, passphrase, removeProperties = ["pluginSyncExtendedSetting"], skipDefaultValue = false) {
   const setting = {
-    ...settingString
+    ...omitP2PRuntimeSettings(settingString)
   };
+  delete setting.P2P_managedType;
+  delete setting.P2P_managedId;
+  delete setting.P2P_managedToken;
   if (skipDefaultValue) {
     const keys = Object.keys(setting);
     for (const k of keys) {
@@ -123,10 +128,9 @@ async function decodeSettingsFromSetupURI(uri, passphrase) {
   const encryptedSetting = uri.substring(configURIBase.length);
   const decrypted = await decryptString(decodeURIComponent(encryptedSetting), passphrase);
   try {
-    return JSON.parse(decrypted);
-  } catch (e) {
+    return omitP2PRuntimeSettings(JSON.parse(decrypted));
+  } catch {
     Logger(`Failed to parse settings from decrypted data`, LOG_LEVEL_NOTICE);
-    Logger(e, LOG_LEVEL_VERBOSE);
     return false;
   }
 }

package/dist/common/ConnectionString.js

@@ -1,9 +1,12 @@
-import { normaliseP2PConnectionPath, normaliseP2PMaxWirePayloadBytes } from "./models/setting.p2p.js";
+import {
+  normaliseP2PConnectionPath,
+  normaliseP2PMaxWirePayloadBytes
+} from "./models/setting.p2p.js";
 const PROXY_SCHEME = "https";
 function parseSlsUri(uriString) {
   const match = uriString.match(/^sls\+([^:]+):(.*)$/);
   if (!match) {
-    throw new Error(`Unsupported URI: ${uriString}`);
+    throw new Error("Unsupported URI");
   }
   const subscheme = match[1];
   const rest = match[2];
@@ -20,7 +23,7 @@ class ConnectionStringParser {
   static parse(uriString) {
     const match = uriString.match(/^sls\+([^:]+):/);
     if (!match) {
-      throw new Error(`Unsupported URI: ${uriString}`);
+      throw new Error("Unsupported URI");
     }
     const subscheme = match[1];
     if (subscheme === "p2p") {
@@ -43,7 +46,7 @@ class ConnectionStringParser {
           settings: this.parseS3(url)
         };
       default:
-        throw new Error(`Unsupported protocol: sls+${subscheme}`);
+        throw new Error("Unsupported protocol");
     }
   }
   /**
@@ -126,9 +129,7 @@ class ConnectionStringParser {
   }
   static parseP2P(uriString) {
     const match = uriString.match(/^sls\+p2p:\/\/([^?#]+)(?:\?([^#]*))?(?:#(.*))?$/);
-    if (!match) {
-      throw new Error(`Invalid P2P URI: ${uriString}`);
-    }
+    if (!match) throw new Error("Invalid P2P URI");
     const authority = match[1];
     const queryString = match[2] || "";
     let userinfo = "";
@@ -158,7 +159,10 @@ class ConnectionStringParser {
       P2P_turnUsername: searchParams.get("turnUser") || "",
       P2P_turnCredential: searchParams.get("turnPass") || "",
       P2P_maxWirePayloadBytes: normaliseP2PMaxWirePayloadBytes(Number(searchParams.get("maxWirePayloadBytes"))),
-      P2P_connectionPath: normaliseP2PConnectionPath(searchParams.get("connectionPath"))
+      P2P_connectionPath: normaliseP2PConnectionPath(searchParams.get("connectionPath")),
+      P2P_managedType: searchParams.get("managedType") || void 0,
+      P2P_managedId: searchParams.get("managedId") || void 0,
+      P2P_managedToken: searchParams.get("token") || void 0
     };
   }
   static serializeP2P(settings) {
@@ -176,6 +180,9 @@ class ConnectionStringParser {
       String(normaliseP2PMaxWirePayloadBytes(settings.P2P_maxWirePayloadBytes))
     );
     searchParams.set("connectionPath", normaliseP2PConnectionPath(settings.P2P_connectionPath));
+    if (settings.P2P_managedType) searchParams.set("managedType", settings.P2P_managedType);
+    if (settings.P2P_managedId) searchParams.set("managedId", settings.P2P_managedId);
+    if (settings.P2P_managedToken) searchParams.set("token", settings.P2P_managedToken);
     const credentials = settings.P2P_passphrase ? `:${encodeURIComponent(settings.P2P_passphrase)}@` : "";
     const host = encodeURIComponent(settings.P2P_roomID);
     const query = searchParams.toString() ? `?${searchParams.toString()}` : "";

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

@@ -159,6 +159,11 @@ const KeyIndexOfSettings = {
   P2P_turnServers: 150,
   P2P_turnUsername: 151,
   P2P_turnCredential: 152,
+  P2P_managedType: -1,
+  P2P_managedId: -1,
+  P2P_managedToken: -1,
+  P2P_iceServers: -1,
+  P2P_iceServersExpiresAt: -1,
   syncInternalFileOverwritePatterns: 153,
   useOnlyLocalChunk: 154,
   maxMTimeForReflectEvents: 155,

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

@@ -4,6 +4,7 @@ import {
   SETTING_VERSION_INITIAL,
   SETTING_VERSION_SUPPORT_CASE_INSENSITIVE
 } from "./setting.const.js";
+import { omitP2PRuntimeSettings } from "./setting.p2p.js";
 const SettingsMigrationReviewCodes = {
   LegacyUpdatePending: "legacy-update-review-pending",
   FutureSchema: "settings-schema-newer-than-runtime",
@@ -22,18 +23,19 @@ const SETTINGS_MIGRATIONS = [
   }
 ];
 function cloneSettings(source, fallbacks) {
+  const persistableSource = omitP2PRuntimeSettings(source);
   return {
     ...fallbacks,
-    ...source,
+    ...persistableSource,
     remoteConfigurations: Object.fromEntries(
-      Object.entries(source.remoteConfigurations ?? fallbacks.remoteConfigurations).map(([id, config]) => [
+      Object.entries(persistableSource.remoteConfigurations ?? fallbacks.remoteConfigurations).map(([id, config]) => [
         id,
         { ...config }
       ])
     ),
     pluginSyncExtendedSetting: {
       ...fallbacks.pluginSyncExtendedSetting,
-      ...source.pluginSyncExtendedSetting
+      ...persistableSource.pluginSyncExtendedSetting
     }
   };
 }

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

@@ -1,4 +1,14 @@
 import { type P2PConnectionPath } from "./setting.const.js";
+import type { P2PConnectionInfo, P2PSyncSetting } from "./setting.type.js";
+/** Report whether the selected P2P settings request host-managed TURN credentials. */
+export declare function hasManagedP2PTurnConfiguration(settings: Partial<Pick<P2PConnectionInfo, "P2P_managedType">>): boolean;
+/** Remove connection-only ICE credentials before settings cross a serialisation boundary. */
+export declare function omitP2PRuntimeSettings<T extends Partial<P2PSyncSetting>>(settings: T): Omit<T, "P2P_iceServers" | "P2P_iceServersExpiresAt">;
+/**
+ * Report whether a P2P profile has a usable manual TURN endpoint or requests
+ * host-managed TURN credentials. STUN-only profiles remain false.
+ */
+export declare function hasP2PTurnConfiguration(settings: Partial<Pick<P2PConnectionInfo, "P2P_turnServers" | "P2P_managedType">>): boolean;
 /**
  * Return a safe outgoing RPC wire-payload bound for Trystero.
  *

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

@@ -1,4 +1,14 @@
 import { P2PConnectionPaths, P2PMessageSizePresets } from "./setting.const.js";
+function hasManagedP2PTurnConfiguration(settings) {
+  return typeof settings.P2P_managedType === "string" && settings.P2P_managedType.trim().length > 0;
+}
+function omitP2PRuntimeSettings(settings) {
+  const { P2P_iceServers: _iceServers, P2P_iceServersExpiresAt: _expiresAt, ...persistable } = settings;
+  return persistable;
+}
+function hasP2PTurnConfiguration(settings) {
+  return hasManagedP2PTurnConfiguration(settings) || typeof settings.P2P_turnServers === "string" && hasValidP2PTurnServerUrl(settings.P2P_turnServers);
+}
 function normaliseP2PMaxWirePayloadBytes(value) {
   if (typeof value !== "number" || !Number.isSafeInteger(value) || value < P2PMessageSizePresets.MaximumCompatibility || value > P2PMessageSizePresets.Standard) {
     return P2PMessageSizePresets.Standard;
@@ -31,10 +41,13 @@ function hasValidP2PTurnServerUrl(value) {
   return splitP2PTurnServerUrls(value).some(isValidP2PTurnServerUrl);
 }
 export {
+  hasManagedP2PTurnConfiguration,
+  hasP2PTurnConfiguration,
   hasValidP2PTurnServerUrl,
   isValidP2PTurnServerUrl,
   normaliseP2PConnectionPath,
   normaliseP2PMaxWirePayloadBytes,
+  omitP2PRuntimeSettings,
   splitP2PRelayUrls,
   splitP2PTurnServerUrls
 };

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

@@ -528,6 +528,12 @@ export interface P2PConnectionInfo {
      * The TURN credential (password, secret, etc...) for the P2P connection.
      */
     P2P_turnCredential: string;
+    /** Host-defined managed TURN provider type. */
+    P2P_managedType?: string;
+    /** Host-defined managed TURN provider identifier. */
+    P2P_managedId?: string;
+    /** Host-defined managed TURN provider token. */
+    P2P_managedToken?: string;
     /**
      * Maximum serialised RPC wire payload sent through Trystero before
      * Commonlib splits it. Applies to outgoing messages.
@@ -552,6 +558,10 @@ export interface P2PSyncSetting extends P2PConnectionInfo {
     P2P_AutoAcceptingPeers: string;
     P2P_AutoDenyingPeers: string;
     P2P_IsHeadless?: boolean;
+    /** ICE servers prepared for one room connection. Never persist or share this value. */
+    P2P_iceServers?: readonly RTCIceServer[];
+    /** Absolute Unix timestamp in milliseconds for the prepared ICE servers. */
+    P2P_iceServersExpiresAt?: number;
 }
 /**
  * Interface representing the settings for a remote type.

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

@@ -261,6 +261,8 @@ export declare const TweakValuesTemplate: {
     P2P_AutoAcceptingPeers?: string;
     P2P_AutoDenyingPeers?: string;
     P2P_IsHeadless?: boolean;
+    P2P_iceServers?: readonly RTCIceServer[];
+    P2P_iceServersExpiresAt?: number;
     P2P_Enabled?: boolean;
     P2P_relays?: string;
     P2P_roomID?: string;
@@ -272,6 +274,9 @@ export declare const TweakValuesTemplate: {
     P2P_turnServers?: string;
     P2P_turnUsername?: string;
     P2P_turnCredential?: string;
+    P2P_managedType?: string;
+    P2P_managedId?: string;
+    P2P_managedToken?: string;
     P2P_maxWirePayloadBytes?: number;
     P2P_connectionPath?: import("./setting.const.js").P2PConnectionPath;
     P2P_useDiagRTC?: boolean;

package/dist/common/settingConstants.d.ts

@@ -185,6 +185,8 @@ export declare const AllSettingDefault: {
     P2P_AutoAcceptingPeers: string;
     P2P_AutoDenyingPeers: string;
     P2P_IsHeadless?: boolean;
+    P2P_iceServers?: readonly RTCIceServer[];
+    P2P_iceServersExpiresAt?: number;
     P2P_Enabled: boolean;
     P2P_relays: string;
     P2P_roomID: string;
@@ -196,6 +198,9 @@ export declare const AllSettingDefault: {
     P2P_turnServers: string;
     P2P_turnUsername: string;
     P2P_turnCredential: string;
+    P2P_managedType?: string;
+    P2P_managedId?: string;
+    P2P_managedToken?: string;
     P2P_maxWirePayloadBytes?: number;
     P2P_connectionPath?: import("./types.js").P2PConnectionPath;
     P2P_useDiagRTC?: boolean;

package/dist/common/types.d.ts

@@ -9,7 +9,7 @@ import { AUTO_MERGED, CANCELLED, LEAVE_TO_SUBSEQUENT, MISSING_OR_ERROR, NOT_CONF
 import { IDPrefixes, LEAF_WAIT_ONLY_REMOTE, LEAF_WAIT_TIMEOUT, LEAF_WAIT_TIMEOUT_SEQUENTIAL_REPLICATOR, MAX_DOC_SIZE, MAX_DOC_SIZE_BIN, PREFIX_CHUNK, PREFIX_ENCRYPTED_CHUNK, PREFIX_OBFUSCATED, RECENT_MODIFIED_DOCS_QTY, REPLICATION_BUSY_TIMEOUT, SALT_OF_ID, SALT_OF_PASSPHRASE, SEED_MURMURHASH, VER } from "./models/shared.const.behabiour.js";
 import { AutoAccepting, type BucketSyncSetting, type ChunkSplitterVersion, type ConfigPassphraseStore, type CouchDBConnection, type E2EEAlgorithm, type EncryptionSettings, type HashAlgorithm, type HasSettings, type LocalDBSettings, type ObsidianLiveSyncSettings, type P2PConnectionInfo, type P2PSyncSetting, type PluginSyncSettingEntry, type RemoteDBSettings, type RemoteType, type RemoteTypeSettings, type SYNC_MODE } from "./models/setting.type.js";
 import { ChunkAlgorithmNames, ChunkAlgorithms, CURRENT_SETTING_VERSION, E2EEAlgorithmNames, E2EEAlgorithms, HashAlgorithms, REMOTE_COUCHDB, REMOTE_MINIO, REMOTE_P2P, RemoteTypes, SETTING_VERSION_INITIAL, SETTING_VERSION_SUPPORT_CASE_INSENSITIVE, MODE_AUTOMATIC, MODE_PAUSED, MODE_SELECTIVE, MODE_SHINY, P2PConnectionPaths, P2PMessageSizePresets, type P2PConnectionPath } from "./models/setting.const.js";
-import { hasValidP2PTurnServerUrl, isValidP2PTurnServerUrl, normaliseP2PConnectionPath, normaliseP2PMaxWirePayloadBytes, splitP2PTurnServerUrls } from "./models/setting.p2p.js";
+import { hasManagedP2PTurnConfiguration, hasP2PTurnConfiguration, hasValidP2PTurnServerUrl, omitP2PRuntimeSettings, isValidP2PTurnServerUrl, normaliseP2PConnectionPath, normaliseP2PMaxWirePayloadBytes, splitP2PTurnServerUrls } from "./models/setting.p2p.js";
 import { PREFERRED_BASE, PREFERRED_JOURNAL_SYNC, PREFERRED_SETTING_CLOUDANT, PREFERRED_SETTING_SELF_HOSTED } from "./models/setting.const.preferred.js";
 import { P2P_DEFAULT_SETTINGS, DEFAULT_SETTINGS, NEW_VAULT_SETTINGS, SETTINGS_SCHEMA_DEFAULTS, createNewVaultSettings } from "./models/setting.const.defaults.js";
 import { prepareSettingsForLoad, SettingsMigrationReviewCodes, type PreparedSettings, type SettingsMigrationReviewCode, type SettingsMigrationReviewReason, type SettingsMigrationState } from "./models/setting.lifecycle.js";
@@ -39,7 +39,7 @@ export { SETTING_VERSION_INITIAL, SETTING_VERSION_SUPPORT_CASE_INSENSITIVE, CURR
 export type { BucketSyncSetting, LocalDBSettings };
 export { RemoteTypes, REMOTE_COUCHDB, REMOTE_MINIO, REMOTE_P2P, P2PConnectionPaths, P2PMessageSizePresets, type RemoteType, AutoAccepting, };
 export type { P2PConnectionInfo, P2PConnectionPath, P2PSyncSetting };
-export { hasValidP2PTurnServerUrl, isValidP2PTurnServerUrl, normaliseP2PConnectionPath, normaliseP2PMaxWirePayloadBytes, splitP2PTurnServerUrls, };
+export { hasManagedP2PTurnConfiguration, hasP2PTurnConfiguration, hasValidP2PTurnServerUrl, omitP2PRuntimeSettings, isValidP2PTurnServerUrl, normaliseP2PConnectionPath, normaliseP2PMaxWirePayloadBytes, splitP2PTurnServerUrls, };
 export { P2P_DEFAULT_SETTINGS };
 export type { RemoteTypeSettings };
 export { E2EEAlgorithmNames, E2EEAlgorithms, type E2EEAlgorithm };
@@ -116,4 +116,4 @@ export { DOCID_SYNC_PARAMETERS };
 export { DOCID_JOURNAL_SYNC_PARAMETERS };
 export type { SyncParameters };
 export { DEFAULT_SYNC_PARAMETERS };
-export { SETTING_KEY_P2P_DEVICE_NAME, configURIBase, configURIBaseQR, SuffixDatabaseName, ExtraSuffixIndexedDB };
+export { SETTING_KEY_P2P_DEVICE_NAME, configURIBase, configURIBaseQR, SuffixDatabaseName, ExtraSuffixIndexedDB, };

package/dist/common/types.js

@@ -64,7 +64,10 @@ import {
   P2PMessageSizePresets
 } from "./models/setting.const.js";
 import {
+  hasManagedP2PTurnConfiguration,
+  hasP2PTurnConfiguration,
   hasValidP2PTurnServerUrl,
+  omitP2PRuntimeSettings,
   isValidP2PTurnServerUrl,
   normaliseP2PConnectionPath,
   normaliseP2PMaxWirePayloadBytes,
@@ -236,11 +239,14 @@ export {
   configURIBaseQR,
   configurationNames,
   createNewVaultSettings,
+  hasManagedP2PTurnConfiguration,
+  hasP2PTurnConfiguration,
   hasValidP2PTurnServerUrl,
   isMetaEntry,
   isValidP2PTurnServerUrl,
   normaliseP2PConnectionPath,
   normaliseP2PMaxWirePayloadBytes,
+  omitP2PRuntimeSettings,
   prepareSettingsForLoad,
   splitP2PTurnServerUrls,
   statusDisplay

package/dist/common/utils.js

@@ -462,7 +462,10 @@ function pickP2PSyncSettings(setting) {
     P2P_turnUsername: setting.P2P_turnUsername,
     P2P_turnCredential: setting.P2P_turnCredential,
     P2P_maxWirePayloadBytes: normaliseP2PMaxWirePayloadBytes(setting.P2P_maxWirePayloadBytes),
-    P2P_connectionPath: normaliseP2PConnectionPath(setting.P2P_connectionPath)
+    P2P_connectionPath: normaliseP2PConnectionPath(setting.P2P_connectionPath),
+    P2P_managedType: setting.P2P_managedType,
+    P2P_managedId: setting.P2P_managedId,
+    P2P_managedToken: setting.P2P_managedToken
   };
 }
 function wrapByDefault(func, onError) {

package/dist/interfaces/DatabaseFileAccess.d.ts

@@ -2,7 +2,10 @@ import type { FilePathWithPrefix, LoadedEntry, MetaEntry, UXFileInfo, UXFileInfo
 export interface DatabaseFileAccess {
     delete: (file: UXFileInfoStub | FilePathWithPrefix, rev?: string) => Promise<boolean>;
     store: (file: UXFileInfo, force?: boolean, skipCheck?: boolean) => Promise<boolean>;
-    /** Store a file as a child of an exact revision and return the created revision. */
+    /**
+     * Store a child of the exact supplied revision, even after that branch has advanced.
+     * An undefined base uses the current winner. Return the created revision, or `false`.
+     */
     storeWithBaseRevision: (file: UXFileInfo, baseRevision: string | undefined, skipCheck?: boolean) => Promise<string | false>;
     /**
      * Store a file as a child of an exact revision only while that revision remains a live leaf.
@@ -14,8 +17,18 @@ export interface DatabaseFileAccess {
      * write without creating a Metadata successor.
      */
     storeWithLiveBaseRevision: (file: UXFileInfo, baseRevision: string, skipCheck?: boolean) => Promise<string | false>;
+    /**
+     * Preserve content of unknown ancestry as a fresh parentless revision of the same document.
+     * Existing branches remain intact; no historical byte match is used as the parent.
+     * Return the created revision, or `false` when no Metadata revision was stored.
+     */
+    storeIndependentRevision: (file: UXFileInfo, skipCheck?: boolean) => Promise<string | false>;
     storeAsConflictedRevision: (file: UXFileInfo, currentRev: string, skipCheck?: boolean) => Promise<boolean>;
-    /** Preserve unknown storage content as a conflict and return its exact revision. */
+    /**
+     * Store a sibling of `currentRev` below its parent and return the created revision.
+     * Return `false` if that parent is unavailable. Use `storeIndependentRevision`
+     * when the storage content has no known ancestor.
+     */
     storeAsConflictedRevisionWithResult: (file: UXFileInfo, currentRev: string, skipCheck?: boolean) => Promise<string | false>;
     /** Store a user deletion as a visible logical-deletion child of an exact revision. */
     storeDeletionWithBaseRevision: (file: UXFileInfoStub | FilePathWithPrefix, baseRevision: string) => Promise<string | false>;
@@ -24,9 +37,24 @@ export interface DatabaseFileAccess {
     hasContentInRevisionHistory: (file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer, currentRev?: string) => Promise<boolean>;
     /** Return every available revision whose content exactly matches the supplied bytes. */
     findContentRevisions: (file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer, currentRev?: string) => Promise<string[]>;
+    /**
+     * Return current, non-deleted leaf revisions whose decoded content matches the supplied bytes.
+     * Include the winning and conflicting leaves, but never their ancestors. Read only locally
+     * available Chunks, without requesting remote data or waiting for missing Chunks to arrive.
+     *
+     * A unique match can recover provenance; several matches avoid a duplicate write but leave
+     * its origin ambiguous. An empty result means no match was confirmed, including when data
+     * could not be read. This read neither records provenance nor reserves a leaf for a later write.
+     */
+    findLiveContentRevisions: (file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer) => Promise<string[]>;
     fetch: (file: UXFileInfoStub | FilePathWithPrefix, rev?: string, waitForReady?: boolean, skipCheck?: boolean) => Promise<UXFileInfo | false>;
     fetchEntryFromMeta: (meta: MetaEntry, waitForReady?: boolean, skipCheck?: boolean) => Promise<LoadedEntry | false>;
     fetchEntryMeta: (file: UXFileInfoStub | FilePathWithPrefix, rev?: string, skipCheck?: boolean) => Promise<MetaEntry | false>;
-    fetchEntry: (file: UXFileInfoStub | FilePathWithPrefix, rev?: string, waitForReady?: boolean, skipCheck?: boolean) => Promise<LoadedEntry | false>;
+    /**
+     * Load a revision's content, or return `false` when it cannot be loaded.
+     * `localOnly` overrides `waitForReady`: missing Chunks cause failure without remote requests
+     * or waiting for delivery, so provenance checks can use only content already available locally.
+     */
+    fetchEntry: (file: UXFileInfoStub | FilePathWithPrefix, rev?: string, waitForReady?: boolean, skipCheck?: boolean, localOnly?: boolean) => Promise<LoadedEntry | false>;
     getConflictedRevs: (file: UXFileInfoStub | FilePathWithPrefix) => Promise<string[]>;
 }

package/dist/interfaces/FileReflectionProvenance.d.ts

@@ -1,9 +1,9 @@
 import type { FilePathWithPrefix } from "../common/types.js";
 import type { SimpleStore } from "../common/utils.js";
 export type FileReflectionProvenanceRecord = {
-    /** Exact database revision which most recently produced the storage state. */
+    /** Exact revision most recently saved from or reflected in storage; the base for subsequent edits. */
     revision: string;
-    /** Raw modification time observed from this device's storage after reflection. */
+    /** Raw modification time of the saved snapshot or storage observed after reflection. */
     observedStorageMtime?: number;
 };
 export interface FileReflectionProvenance {

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

@@ -30,10 +30,12 @@ export declare class EntryManager {
     isTargetFile(filenameSrc: string): boolean;
     prepareChunk(piece: string): Promise<GeneratedChunk>;
     getDBEntryMeta(path: FilePathWithPrefix | FilePath, opt?: PouchDB.Core.GetOptions, includeDeleted?: boolean): Promise<false | LoadedEntry>;
-    getDBEntry(path: FilePathWithPrefix | FilePath, opt?: PouchDB.Core.GetOptions, dump?: boolean, waitForReady?: boolean, includeDeleted?: boolean): Promise<false | LoadedEntry>;
-    getDBEntryFromMeta(meta: LoadedEntry | MetaEntry, dump?: boolean, waitForReady?: boolean): Promise<false | LoadedEntry>;
+    getDBEntry(path: FilePathWithPrefix | FilePath, opt?: PouchDB.Core.GetOptions, dump?: boolean, waitForReady?: boolean, includeDeleted?: boolean, localOnly?: boolean): Promise<false | LoadedEntry>;
+    getDBEntryFromMeta(meta: LoadedEntry | MetaEntry, dump?: boolean, waitForReady?: boolean, localOnly?: boolean): Promise<false | LoadedEntry>;
     deleteDBEntry(path: FilePathWithPrefix | FilePath, opt?: PouchDB.Core.GetOptions): Promise<boolean>;
     storeDeletionAtRevision(path: FilePathWithPrefix | FilePath, baseRevision: string): Promise<false | PouchDB.Core.Response>;
     putDBEntry(note: SavingEntry, onlyChunks?: boolean, conflictBaseRev?: string): Promise<false | PouchDB.Core.Response>;
     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>;
 }

package/dist/managers/EntryManager/EntryManager.js

@@ -10,6 +10,7 @@ import {
   prepareChunk,
   putDBEntry,
   putDBEntryWithLiveBaseRevision,
+  putDBEntryAsIndependentRoot,
   storeDeletionByPathAtRevision
 } from "./EntryManagerImpls.js";
 class EntryManager {
@@ -57,11 +58,11 @@ class EntryManager {
   async getDBEntryMeta(path, opt, includeDeleted = false) {
     return await getDBEntryMetaByPath(this.serviceHost, this, path, opt, includeDeleted);
   }
-  async getDBEntry(path, opt, dump = false, waitForReady = true, includeDeleted = false) {
-    return await getDBEntryByPath(this.serviceHost, this, path, opt, dump, waitForReady, includeDeleted);
+  async getDBEntry(path, opt, dump = false, waitForReady = true, includeDeleted = false, localOnly = false) {
+    return await getDBEntryByPath(this.serviceHost, this, path, opt, dump, waitForReady, includeDeleted, localOnly);
   }
-  async getDBEntryFromMeta(meta, dump = false, waitForReady = true) {
-    return await getDBEntryFromMeta(this.serviceHost, this, meta, dump, waitForReady);
+  async getDBEntryFromMeta(meta, dump = false, waitForReady = true, localOnly = false) {
+    return await getDBEntryFromMeta(this.serviceHost, this, meta, dump, waitForReady, localOnly);
   }
   async deleteDBEntry(path, opt) {
     return await deleteDBEntryByPath(this.serviceHost, this, path, opt);
@@ -75,6 +76,10 @@ class EntryManager {
   async putDBEntryWithLiveBaseRevision(note, baseRevision, onlyChunks) {
     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) {
+    return await putDBEntryAsIndependentRoot(this.serviceHost, this, note);
+  }
 }
 export {
   EntryManager

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

@@ -20,20 +20,28 @@ export declare function putDBEntry(host: NecessaryServicesInterfaces<"path" | "s
  * base has already been advanced, so the caller receives `false` and can retry from fresh state.
  */
 export declare function putDBEntryWithLiveBaseRevision(host: NecessaryServicesInterfaces<"path" | "setting", never>, managers: NecessaryManagers<"localDatabase" | "chunkManager" | "hashManager" | "splitter">, note: SavingEntry, baseRevision: string, onlyChunks?: boolean): Promise<false | PouchDB.Core.Response>;
+/**
+ * Preserve content with unknown ancestry as a fresh parentless revision of the same document.
+ * Store the body as Chunks as usual, then insert a Metadata root with a random revision ID using
+ * `new_edits: false`. This retains existing branches without reusing an identical historical root.
+ * Return the Metadata write result, or `false` when the entry cannot be stored.
+ */
+export declare function putDBEntryAsIndependentRoot(host: NecessaryServicesInterfaces<"path" | "setting", never>, managers: NecessaryManagers<"localDatabase" | "chunkManager" | "hashManager" | "splitter">, note: SavingEntry): Promise<false | PouchDB.Core.Response>;
 export declare function isTargetFile(host: NecessaryServicesInterfaces<"setting", never>, filenameSrc: string): boolean;
 export declare function prepareChunk({ chunkManager, hashManager }: NecessaryManagers<"chunkManager" | "hashManager">, piece: string): Promise<GeneratedChunk>;
 export declare function getDBEntryMetaByPath(host: NecessaryServicesInterfaces<"path" | "setting", never>, { localDatabase }: NecessaryManagers<"localDatabase">, path: FilePathWithPrefix | FilePath, opt?: PouchDB.Core.GetOptions, includeDeleted?: boolean): Promise<false | LoadedEntry>;
 export declare function isLegacyNote(meta: LoadedEntry | MetaEntry): boolean;
 export declare function canUseOnDemandChunking(settings: ObsidianLiveSyncSettings): boolean;
 /**
- * Decide how to retrieve chunks based on settings and waitForReady flag.
+ * Decide how to retrieve chunks based on settings and the caller's read policy.
  * `waitForReady` allows an already-observable finite delivery lifecycle to finish.
+ * `localOnly` overrides both settings and waiting for provenance comparisons.
  */
-export declare function computeChunkRetrievalMethod(waitForReady: boolean, settings: ObsidianLiveSyncSettings): {
+export declare function computeChunkRetrievalMethod(waitForReady: boolean, settings: ObsidianLiveSyncSettings, localOnly?: boolean): {
     waitForDelivery: boolean;
     preventRemoteRequest: boolean;
 };
-export declare function getDBEntryFromMeta(host: NecessaryServicesInterfaces<"path" | "setting", never>, { localDatabase, chunkManager }: NecessaryManagers<"localDatabase" | "chunkManager">, meta: LoadedEntry | MetaEntry, dump?: boolean, waitForReady?: boolean): Promise<false | (import("../../common/types.js").DatabaseEntry & EntryBase & import("../../common/types.js").EntryWithEden & {
+export declare function getDBEntryFromMeta(host: NecessaryServicesInterfaces<"path" | "setting", never>, { localDatabase, chunkManager }: NecessaryManagers<"localDatabase" | "chunkManager">, meta: LoadedEntry | MetaEntry, dump?: boolean, waitForReady?: boolean, localOnly?: boolean): Promise<false | (import("../../common/types.js").DatabaseEntry & EntryBase & import("../../common/types.js").EntryWithEden & {
     path: FilePathWithPrefix;
     data: string | string[];
     type: import("../../common/models/db.type.js").EntryTypes["NOTE_LEGACY"];
@@ -55,7 +63,7 @@ export declare function getDBEntryFromMeta(host: NecessaryServicesInterfaces<"pa
     data: string | string[];
     datatype: import("../../common/types.js").EntryTypeNotes;
 } & PouchDB.Core.IdMeta)>;
-export declare function getDBEntryByPath(host: NecessaryServicesInterfaces<"path" | "setting", never>, managers: NecessaryManagers<"localDatabase" | "chunkManager">, path: FilePathWithPrefix | FilePath, opt?: PouchDB.Core.GetOptions, dump?: boolean, waitForReady?: boolean, includeDeleted?: boolean): Promise<false | (import("../../common/types.js").DatabaseEntry & EntryBase & import("../../common/types.js").EntryWithEden & {
+export declare function getDBEntryByPath(host: NecessaryServicesInterfaces<"path" | "setting", never>, managers: NecessaryManagers<"localDatabase" | "chunkManager">, path: FilePathWithPrefix | FilePath, opt?: PouchDB.Core.GetOptions, dump?: boolean, waitForReady?: boolean, includeDeleted?: boolean, localOnly?: boolean): Promise<false | (import("../../common/types.js").DatabaseEntry & EntryBase & import("../../common/types.js").EntryWithEden & {
     path: FilePathWithPrefix;
     data: string | string[];
     type: import("../../common/models/db.type.js").EntryTypes["NOTE_LEGACY"];

package/dist/managers/EntryManager/EntryManagerImpls.js

@@ -6,6 +6,7 @@ import {
 } from "../../common/types.js";
 import { serialized } from "octagonal-wheels/concurrency/lock";
 import { createTextBlob, getFileRegExp, isTextBlob } from "../../common/utils.js";
+import { compatGlobal } from "../../common/coreEnvFunctions.js";
 import { isErrorOfMissingDoc } from "../../pouchdb/utils_couchdb.js";
 import { stripAllPrefixes } from "../../string_and_binary/path.js";
 import { ICHeader, ICXHeader, PSCHeader } from "../../common/models/fileaccess.const.js";
@@ -126,6 +127,9 @@ async function putDBEntryWithLiveBaseRevision(host, managers, note, baseRevision
     throw ex;
   }
 }
+async function putDBEntryAsIndependentRoot(host, managers, note) {
+  return await putDBEntryInternal(host, managers, note, false, { mode: "independent-root" });
+}
 async function putDBEntryInternal(host, managers, note, onlyChunks, revisionTarget) {
   const { localDatabase, chunkManager, splitter } = managers;
   const filename = host.services.path.id2path(note._id, note);
@@ -163,9 +167,9 @@ async function putDBEntryInternal(host, managers, note, onlyChunks, revisionTarg
       eden: {}
     };
     return await serialized("file:" + filename, async () => {
-      if (revisionTarget.mode !== "latest") {
+      if (revisionTarget.mode === "force-base" || revisionTarget.mode === "live-base") {
         newDoc._rev = revisionTarget.baseRevision;
-      } else {
+      } else if (revisionTarget.mode === "latest") {
         try {
           const old = await localDatabase.get(newDoc._id);
           newDoc._rev = old._rev;
@@ -176,6 +180,15 @@ async function putDBEntryInternal(host, managers, note, onlyChunks, revisionTarg
           }
         }
       }
+      if (revisionTarget.mode === "independent-root") {
+        const randomBytes = compatGlobal.crypto.getRandomValues(new Uint8Array(16));
+        const rootId = Array.from(randomBytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+        newDoc._rev = `1-${rootId}`;
+        const imported = { ...newDoc, _revisions: { start: 1, ids: [rootId] } };
+        await localDatabase.bulkDocs([imported], { new_edits: false });
+        const stored = await localDatabase.get(newDoc._id, { rev: newDoc._rev });
+        return stored._rev === newDoc._rev ? { id: newDoc._id, ok: true, rev: newDoc._rev } : false;
+      }
       const r = revisionTarget.mode === "live-base" ? await localDatabase.put(newDoc) : await localDatabase.put(newDoc, { force: true });
       if (r.ok) {
         return r;
@@ -324,7 +337,10 @@ function canFetchRemotely(settings) {
   }
   return true;
 }
-function computeChunkRetrievalMethod(waitForReady, settings) {
+function computeChunkRetrievalMethod(waitForReady, settings, localOnly = false) {
+  if (localOnly) {
+    return { waitForDelivery: false, preventRemoteRequest: true };
+  }
   const isOnDemandFetchEnabled = canFetchRemotely(settings);
   if (!waitForReady) {
     if (isOnDemandFetchEnabled) {
@@ -343,7 +359,7 @@ function computeChunkRetrievalMethod(waitForReady, settings) {
     preventRemoteRequest: !isOnDemandFetchEnabled
   };
 }
-async function respondEntryFromMeta({ localDatabase, chunkManager }, settings, filename, meta, dump, waitForReady) {
+async function respondEntryFromMeta({ localDatabase, chunkManager }, settings, filename, meta, dump, waitForReady, localOnly = false) {
   const dispFilename = stripAllPrefixes(filename);
   const deleted = meta.deleted ?? meta._deleted ?? void 0;
   if (dump) {
@@ -371,7 +387,7 @@ async function respondEntryFromMeta({ localDatabase, chunkManager }, settings, f
       }));
       edenChunks = Object.fromEntries(chunks2.map((e) => [e._id, e]));
     }
-    const { waitForDelivery, preventRemoteRequest } = computeChunkRetrievalMethod(waitForReady, settings);
+    const { waitForDelivery, preventRemoteRequest } = computeChunkRetrievalMethod(waitForReady, settings, localOnly);
     const childrenKeys = [...meta.children];
     const chunks = await chunkManager.read(
       childrenKeys,
@@ -421,7 +437,7 @@ async function respondEntryFromMeta({ localDatabase, chunkManager }, settings, f
   }
   return false;
 }
-async function getDBEntryFromMeta(host, { localDatabase, chunkManager }, meta, dump = false, waitForReady = true) {
+async function getDBEntryFromMeta(host, { localDatabase, chunkManager }, meta, dump = false, waitForReady = true, localOnly = false) {
   const filename = host.services.path.id2path(meta._id, meta);
   if (!isTargetFile(host, filename)) {
     return false;
@@ -438,15 +454,16 @@ async function getDBEntryFromMeta(host, { localDatabase, chunkManager }, meta, d
       filename,
       meta,
       dump,
-      waitForReady
+      waitForReady,
+      localOnly
     );
   }
   return false;
 }
-async function getDBEntryByPath(host, managers, path, opt, dump = false, waitForReady = true, includeDeleted = false) {
+async function getDBEntryByPath(host, managers, path, opt, dump = false, waitForReady = true, includeDeleted = false, localOnly = false) {
   const meta = await getDBEntryMetaByPath(host, managers, path, opt, includeDeleted);
   if (meta) {
-    return await getDBEntryFromMeta(host, managers, meta, dump, waitForReady);
+    return await getDBEntryFromMeta(host, managers, meta, dump, waitForReady, localOnly);
   } else {
     return false;
   }
@@ -540,6 +557,7 @@ export {
   isTargetFile,
   prepareChunk,
   putDBEntry,
+  putDBEntryAsIndependentRoot,
   putDBEntryWithLiveBaseRevision,
   storeDeletionByPathAtRevision
 };