@vrtmrz/livesync-commonlib 0.1.25 → 0.1.26

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
 };

package/dist/pouchdb/LiveSyncLocalDB.d.ts

@@ -196,12 +196,14 @@ export declare class LiveSyncLocalDB {
     bulkDocsRaw<T extends EntryDoc>(docs: Array<PouchDB.Core.PutDocument<T>>, options?: PouchDB.Core.BulkDocsOptions): Promise<Array<PouchDB.Core.Response | PouchDB.Core.Error>>;
     isTargetFile(filenameSrc: string): boolean;
     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>;
+    /** Preserve existing branches and delegate a fresh root write to the entry manager. */
+    putDBEntryAsIndependentRoot(note: SavingEntry): Promise<false | PouchDB.Core.Response>;
     getConflictedDoc(path: FilePathWithPrefix, rev: string): Promise<false | diff_result_leaf>;
     tryAutoMerge(path: FilePathWithPrefix, enableMarkdownAutoMerge: boolean): AutoMergeResult;
 }

package/dist/pouchdb/LiveSyncLocalDB.js

@@ -457,11 +457,11 @@ class LiveSyncLocalDB {
   async getDBEntryMeta(path, opt, includeDeleted = false) {
     return await this.managers.entryManager.getDBEntryMeta(path, opt, includeDeleted);
   }
-  async getDBEntry(path, opt, dump = false, waitForReady = true, includeDeleted = false) {
-    return await this.managers.entryManager.getDBEntry(path, opt, dump, waitForReady, includeDeleted);
+  async getDBEntry(path, opt, dump = false, waitForReady = true, includeDeleted = false, localOnly = false) {
+    return await this.managers.entryManager.getDBEntry(path, opt, dump, waitForReady, includeDeleted, localOnly);
   }
-  async getDBEntryFromMeta(meta, dump = false, waitForReady = true) {
-    return await this.managers.entryManager.getDBEntryFromMeta(meta, dump, waitForReady);
+  async getDBEntryFromMeta(meta, dump = false, waitForReady = true, localOnly = false) {
+    return await this.managers.entryManager.getDBEntryFromMeta(meta, dump, waitForReady, localOnly);
   }
   async deleteDBEntry(path, opt) {
     return await this.managers.entryManager.deleteDBEntry(path, opt);
@@ -475,6 +475,10 @@ class LiveSyncLocalDB {
   async putDBEntryWithLiveBaseRevision(note, baseRevision, onlyChunks) {
     return await this.managers.entryManager.putDBEntryWithLiveBaseRevision(note, baseRevision, onlyChunks);
   }
+  /** Preserve existing branches and delegate a fresh root write to the entry manager. */
+  async putDBEntryAsIndependentRoot(note) {
+    return await this.managers.entryManager.putDBEntryAsIndependentRoot(note);
+  }
   async getConflictedDoc(path, rev) {
     return await this.managers.conflictManager.getConflictedDoc(path, rev);
   }

package/dist/serviceModules/ServiceDatabaseFileAccessBase.d.ts

@@ -26,21 +26,45 @@ export declare class ServiceDatabaseFileAccessBase extends ServiceModuleBase<Ser
     delete(file: UXFileInfoStub | FilePathWithPrefix, rev?: string): Promise<boolean>;
     createChunks(file: UXFileInfo, force?: boolean, skipCheck?: boolean): Promise<boolean>;
     store(file: UXFileInfo, force?: boolean, skipCheck?: boolean): Promise<boolean>;
+    /** Force a child below the supplied base, even if advanced; an undefined base uses the winner. */
     storeWithBaseRevision(file: UXFileInfo, baseRevision: string | undefined, skipCheck?: boolean): Promise<string | false>;
+    /** Extend a current leaf with ordinary MVCC; an advanced base returns `false`. */
     storeWithLiveBaseRevision(file: UXFileInfo, baseRevision: string, skipCheck?: boolean): Promise<string | false>;
+    /**
+     * Store Chunks and a fresh Metadata root for content with unknown ancestry.
+     * Return its exact revision for provenance, or `false` if no Metadata write succeeded.
+     */
+    storeIndependentRevision(file: UXFileInfo, skipCheck?: boolean): Promise<string | false>;
     storeAsConflictedRevision(file: UXFileInfo, currentRev: string, skipCheck?: boolean): Promise<boolean>;
+    /** Create a sibling of the selected revision; refuse when its parent cannot be found. */
     storeAsConflictedRevisionWithResult(file: UXFileInfo, currentRev: string, skipCheck?: boolean): Promise<string | false>;
+    /** Record a logical deletion below the displayed branch and return its exact revision. */
     storeDeletionWithBaseRevision(file: UXFileInfoStub | FilePathWithPrefix, baseRevision: string): Promise<string | false>;
     storeContent(path: FilePathWithPrefix, content: string): Promise<boolean>;
     private __store;
+    /** Reconstruct the immediate parent ID from revision history, or return `false` if unavailable. */
     private getParentRev;
+    /**
+     * Search available revision bodies across branches and their ancestors.
+     * `stopAfterFirstMatch` serves existence checks without decoding the remaining candidates.
+     * Historical matches alone do not establish the origin of current storage content.
+     */
     private findContentRevisionsInternal;
+    /** Find matching content throughout available history, including non-leaf revisions. */
     findContentRevisions(file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer, currentRev?: string): Promise<string[]>;
+    /**
+     * Find live leaves which already represent these bytes, for deduplication when provenance
+     * is unknown. `open_revs` includes conflicting branches; both deletion markers are excluded.
+     * Unlike the historical search, ancestors cannot match and missing Chunks are not fetched.
+     * A read failure yields no confirmed match. Callers decide whether the result identifies a
+     * unique origin; this method does not mutate provenance or hold the revision tree stable.
+     */
+    findLiveContentRevisions(file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer): Promise<string[]>;
     hasContentInRevisionHistory(file: UXFileInfoStub | FilePathWithPrefix, content: string | string[] | Blob | ArrayBuffer, currentRev?: string): Promise<boolean>;
     getConflictedRevs(file: UXFileInfoStub | FilePathWithPrefix): Promise<string[]>;
     fetch(file: UXFileInfoStub | FilePathWithPrefix, rev?: string, waitForReady?: boolean, skipCheck?: boolean): Promise<UXFileInfo | false>;
     fetchEntryMeta(file: UXFileInfoStub | FilePathWithPrefix, rev?: string, skipCheck?: boolean): Promise<MetaEntry | false>;
-    fetchEntryFromMeta(meta: MetaEntry, waitForReady?: boolean, skipCheck?: boolean): Promise<LoadedEntry | false>;
-    fetchEntry(file: UXFileInfoStub | FilePathWithPrefix, rev?: string, waitForReady?: boolean, skipCheck?: boolean): Promise<LoadedEntry | false>;
+    fetchEntryFromMeta(meta: MetaEntry, waitForReady?: boolean, skipCheck?: boolean, localOnly?: boolean): Promise<LoadedEntry | false>;
+    fetchEntry(file: UXFileInfoStub | FilePathWithPrefix, rev?: string, waitForReady?: boolean, skipCheck?: boolean, localOnly?: boolean): Promise<LoadedEntry | false>;
     deleteFromDBbyPath(fullPath: FilePath | FilePathWithPrefix, rev?: string): Promise<boolean>;
 }

package/dist/serviceModules/ServiceDatabaseFileAccessBase.js

@@ -52,6 +52,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
   async store(file, force = false, skipCheck) {
     return await this.__store(file, force, skipCheck, false) !== false;
   }
+  /** Force a child below the supplied base, even if advanced; an undefined base uses the winner. */
   async storeWithBaseRevision(file, baseRevision, skipCheck) {
     const result = await this.__store(file, true, skipCheck, false, {
       mode: "force-base",
@@ -59,6 +60,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     });
     return result !== null && typeof result === "object" && "rev" in result ? result.rev : false;
   }
+  /** Extend a current leaf with ordinary MVCC; an advanced base returns `false`. */
   async storeWithLiveBaseRevision(file, baseRevision, skipCheck) {
     const result = await this.__store(file, true, skipCheck, false, {
       mode: "live-base",
@@ -66,9 +68,18 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     });
     return result !== null && typeof result === "object" && "rev" in result ? result.rev : false;
   }
+  /**
+   * Store Chunks and a fresh Metadata root for content with unknown ancestry.
+   * Return its exact revision for provenance, or `false` if no Metadata write succeeded.
+   */
+  async storeIndependentRevision(file, skipCheck) {
+    const result = await this.__store(file, true, skipCheck, false, { mode: "independent-root" });
+    return result !== null && typeof result === "object" && "rev" in result ? result.rev : false;
+  }
   async storeAsConflictedRevision(file, currentRev, skipCheck) {
     return await this.storeAsConflictedRevisionWithResult(file, currentRev, skipCheck) !== false;
   }
+  /** Create a sibling of the selected revision; refuse when its parent cannot be found. */
   async storeAsConflictedRevisionWithResult(file, currentRev, skipCheck) {
     const conflictBaseRev = await this.getParentRev(file, currentRev);
     if (!conflictBaseRev) {
@@ -77,6 +88,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     }
     return await this.storeWithBaseRevision(file, conflictBaseRev, skipCheck);
   }
+  /** Record a logical deletion below the displayed branch and return its exact revision. */
   async storeDeletionWithBaseRevision(file, baseRevision) {
     if (!await this.checkIsTargetFile(file)) {
       return false;
@@ -193,7 +205,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
       this._log(msg + " Skip " + fullPath, LOG_LEVEL_VERBOSE);
       return true;
     }
-    const ret = revisionTarget.mode === "live-base" ? await this.database.localDatabase.putDBEntryWithLiveBaseRevision(
+    const ret = revisionTarget.mode === "independent-root" ? await this.database.localDatabase.putDBEntryAsIndependentRoot(d) : revisionTarget.mode === "live-base" ? await this.database.localDatabase.putDBEntryWithLiveBaseRevision(
       d,
       revisionTarget.baseRevision,
       onlyChunks
@@ -208,6 +220,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     }
     return ret;
   }
+  /** Reconstruct the immediate parent ID from revision history, or return `false` if unavailable. */
   async getParentRev(file, rev) {
     const filename = getDatabasePathFromUXFileInfo(file);
     try {
@@ -226,6 +239,11 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
       return false;
     }
   }
+  /**
+   * Search available revision bodies across branches and their ancestors.
+   * `stopAfterFirstMatch` serves existence checks without decoding the remaining candidates.
+   * Historical matches alone do not establish the origin of current storage content.
+   */
   async findContentRevisionsInternal(file, content, currentRev, stopAfterFirstMatch = false) {
     const filename = getDatabasePathFromUXFileInfo(file);
     try {
@@ -285,12 +303,46 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     }
     return [];
   }
+  /** Find matching content throughout available history, including non-leaf revisions. */
   async findContentRevisions(file, content, currentRev) {
     if (!await this.checkIsTargetFile(file)) {
       return [];
     }
     return await this.findContentRevisionsInternal(file, content, currentRev);
   }
+  /**
+   * Find live leaves which already represent these bytes, for deduplication when provenance
+   * is unknown. `open_revs` includes conflicting branches; both deletion markers are excluded.
+   * Unlike the historical search, ancestors cannot match and missing Chunks are not fetched.
+   * A read failure yields no confirmed match. Callers decide whether the result identifies a
+   * unique origin; this method does not mutate provenance or hold the revision tree stable.
+   */
+  async findLiveContentRevisions(file, content) {
+    if (!await this.checkIsTargetFile(file)) return [];
+    const filename = getDatabasePathFromUXFileInfo(file);
+    try {
+      const current = await this.database.localDatabase.getDBEntryMeta(filename, void 0, true);
+      if (current === false) return [];
+      const leaves = await this.database.localDatabase.getRaw(current._id, {
+        open_revs: "all"
+      });
+      if (!Array.isArray(leaves)) return [];
+      const matches = [];
+      for (const leaf of leaves) {
+        const rev = leaf.ok?._rev;
+        if (!rev || leaf.ok?.deleted || leaf.ok?._deleted) continue;
+        const entry = await this.database.localDatabase.getDBEntry(filename, { rev }, false, true, true, true);
+        if (entry !== false && !entry.deleted && !entry._deleted && await isDocContentSame(readContent(entry), content)) {
+          matches.push(rev);
+        }
+      }
+      return matches;
+    } catch (ex) {
+      this._log(`Could not check live revision content for ${filename}`, LOG_LEVEL_VERBOSE);
+      this._log(ex, LOG_LEVEL_VERBOSE);
+      return [];
+    }
+  }
   async hasContentInRevisionHistory(file, content, currentRev) {
     if (!await this.checkIsTargetFile(file)) {
       return true;
@@ -346,17 +398,17 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     }
     return doc;
   }
-  async fetchEntryFromMeta(meta, waitForReady = true, skipCheck = false) {
+  async fetchEntryFromMeta(meta, waitForReady = true, skipCheck = false, localOnly = false) {
     if (skipCheck && !await this.checkIsTargetFile(meta.path)) {
       return false;
     }
-    const doc = await this.database.localDatabase.getDBEntryFromMeta(meta, false, waitForReady);
+    const doc = await this.database.localDatabase.getDBEntryFromMeta(meta, false, waitForReady, localOnly);
     if (doc === false) {
       return false;
     }
     return doc;
   }
-  async fetchEntry(file, rev, waitForReady = true, skipCheck = false) {
+  async fetchEntry(file, rev, waitForReady = true, skipCheck = false, localOnly = false) {
     if (skipCheck && !await this.checkIsTargetFile(file)) {
       return false;
     }
@@ -364,7 +416,7 @@ class ServiceDatabaseFileAccessBase extends ServiceModuleBase {
     if (entry === false) {
       return false;
     }
-    const doc = await this.fetchEntryFromMeta(entry, waitForReady, true);
+    const doc = await this.fetchEntryFromMeta(entry, waitForReady, true, localOnly);
     return doc;
   }
   async deleteFromDBbyPath(fullPath, rev) {