@vrtmrz/livesync-commonlib 0.2.3 → 0.3.0

package/README.md

@@ -14,6 +14,19 @@ This package is primarily for maintainers of those clients and for integrations
 
 ## Status and versioning
 
+Commonlib [0.2.3](https://github.com/vrtmrz/livesync-commonlib/releases/tag/0.2.3)
+is published on npm through both `latest` and `next`. Self-hosted LiveSync
+[1.0.44](https://github.com/vrtmrz/obsidian-livesync/releases/tag/1.0.44)
+uses that exact version. See the [0.2.3 release notes](updates.md#023) for the
+handler-setter source compatibility change and positive-infinity formatting
+exception.
+
+Version 0.3.0 requires custom clients passed to
+`LiveSyncJournalReplicator.ensureBucketIsCompatible` to implement
+`hasRemoteJournals(): Promise<boolean>`. The standard Journal client already
+provides this operation. See the [0.3.0 release notes](updates.md#030) for the
+custom-client requirement and path identity migration conditions.
+
 Commonlib is pre-1.0. The compatibility policy described here begins with 0.2.0 and does not retroactively apply to published 0.1.x versions. Within 0.2.x, Commonlib preserves published APIs, types, behaviour, supported persisted data, and exported `compat/*` paths; intentional breaking changes use 0.3.0. Consumers may declare ranges such as `^0.2.0`; retain a lockfile and use `npm ci` for reproducible installs. An entry in the package export map means that the import is deliberate and package-tested; it does not make every semantic detail of that entry a final 1.0 guarantee.
 
 Treat every `compat/*` subpath as a migration-only interface. A source-directory import, Git submodule, or consumer-defined TypeScript alias is not a supported package boundary.
@@ -52,8 +65,8 @@ The existing `compat/services/lib` boundary retains `bindableFunction` and `lazy
 
 The `compat/pouchdb/chunks` entry retains the obsolete `transferChunks`,
 `balanceChunkPurgedDBs`, and `fetchAllUsedChunks` helpers for existing consumers.
-The unreleased Self-hosted LiveSync integration removes its purge-based cleanup
-recovery and uses the standard locked-remote recovery dialogue. Garbage
+Self-hosted LiveSync 1.0.44 uses the standard locked-remote recovery dialogue
+in place of its purge-based cleanup recovery. Garbage
 Collection V3 propagates ordinary deletion revisions and does not use these
 helpers. Their compatibility exports and existing transfer behaviour remain
 available; new integrations should not adopt this obsolete cleanup path.
@@ -68,7 +81,7 @@ The P2P entry exposes eight focused views over one service owner, together with
 
 ## Blob helper migration
 
-The unreleased Blob extraction retains `createBlob`, `createTextBlob`, and
+Commonlib 0.2.3 retains `createBlob`, `createTextBlob`, and
 `createBinaryBlob` through the existing `compat/common/utils` entry. Existing
 callers can keep those imports. `createBlob` preserves an existing Blob's
 identity and MIME type; text and binary inputs produce new Blobs with
@@ -81,8 +94,8 @@ Its normalisation function is named `toBlob`; its creation functions retain
 compares two Blobs in bounded parts and accepts an optional synchronous or
 asynchronous ArrayBuffer equality predicate. See the
 [Octagonal Wheels Blob guide](https://github.com/vrtmrz/fancy-kit/blob/main/packages/octagonal-wheels/guides/imports-and-runtime.md#blob-creation-and-normalisation)
-for input and runtime contracts. This unreleased Commonlib integration now pins
-the published Octagonal Wheels 0.1.56 dependency.
+for input and runtime contracts. Commonlib 0.2.3 pins the published
+Octagonal Wheels 0.1.56 dependency.
 
 Commonlib continues to own document classification, decoding in `readAsBlob`,
 and content-comparison policy. The legacy `isDocContentSame` retains its
@@ -292,7 +305,19 @@ 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.
+The maintained CLI and Obsidian hosts can opt into [Unicode NFC path identity](docs/unicode-path-identity.md) with CouchDB, Object Storage, and P2P in the unreleased transport extension. Existing databases require an explicit Rebuild or Fetch migration before using it. P2P participants must all be updated and migrated.
+
+## Direct database watches
+
+Direct CouchDB reads use the same Chunk arrival waiting and bounded retry processing as application replication. They retrieve missing Chunks through the prepared source connection, including its decryption transforms, without writing fetched Chunks back to that source.
+
+Existing integrations can use `DirectFileManipulator.beginWatch(callback, checkIsInterested?, onCheckpoint?)`. The file callback retains its `(doc: ReadyEntry, seq?: string | number)` signature. Resolving it acknowledges delivery. An incomplete read or rejected delivery remains pending and retries after delays from one second up to 30 seconds, while other documents continue. At most four file-processing operations run concurrently. A newer change for the same document supersedes its pending read, including deletion, rename, or exclusion by `checkIsInterested`.
+
+The optional third callback, `(seq: string | number) => Promise<void> | void`, receives the completed feed position before the first unfinished change. Persist that checkpoint before resolving the callback. Commonlib retries rejected checkpoint notifications and advances `since` only after acknowledgement. A successful file callback can have a later sequence than this safe checkpoint; do not save its sequence independently. Sequence tokens are opaque. Without a checkpoint callback, `since` advances in memory.
+
+Reconnects replay from `since`; a new process must restore the host's saved checkpoint before starting its watch. There is no persistent retry queue, so consumers must tolerate repeated delivery after reconnect or restart. `endWatch()` cancels watch retry and reconnect timers and prevents pending reads from delivering into a stopped or replacement watch. `close()` also retires the Chunk fetcher. Already-invoked host callbacks finish their own work, and callbacks for the same document remain serialised across stop and restart. Outstanding transport reads occupy a processing slot until they settle. A disconnected watch still owns its scheduled reconnect and rejects a duplicate `beginWatch()` call.
+
+Logical deletions and note-shaped tombstones are delivered with empty `data` without loading deleted Chunks. A bare tombstone can reuse pending note metadata; without known metadata it remains ignored because an obfuscated document ID does not supply a file path.
 
 ## Contract scope
 
@@ -319,14 +344,14 @@ MIT
 
 The shared formatter displays positive infinity as `∞y`, including through the existing `timeDeltaToHumanReadable` entry. Other duration formatting cases retain their previous behaviour.
 
-The unreleased extraction keeps `timeDeltaToHumanReadable`,
+Commonlib 0.2.3 keeps `timeDeltaToHumanReadable`,
 `splitCustomRegExpList`, and `constructCustomRegExpList` at the existing
 `compat/common/utils` entry. They delegate to `formatDuration` in
 `octagonal-wheels/notation/duration` and the delimiter helpers in
 `octagonal-wheels/string`. Commonlib's internal `asCopy` helper delegates to
 `cloneViaJSON` in `octagonal-wheels/encoding/json`; it does not add a Commonlib
 public entry. New general-purpose callers can use the focused Octagonal Wheels
-entries once a release containing them is available.
+entries in Octagonal Wheels 0.1.56 or later.
 
 Duration units and rounding remain unchanged. The delimiter adapters retain
 their tagged types and string coercion; splitting removes empty parts and

package/dist/API/DirectFileManipulatorV2.d.ts

@@ -137,7 +137,13 @@ export declare class DirectFileManipulator implements LiveSyncLocalDBEnv {
     watching: boolean;
     changes: PouchDB.Core.Changes<EntryDoc> | undefined;
     since: string;
-    beginWatch(callback: (doc: ReadyEntry, seq?: string | number) => Promise<any> | void, checkIsInterested?: (doc: MetaEntry) => boolean): boolean;
+    private watchOwner?;
+    /**
+     * Watch file changes, retrying incomplete reads and rejected consumer callbacks.
+     * Resolving the file callback acknowledges processing. The optional checkpoint
+     * callback must resolve after the host has persisted its safe resume position.
+     */
+    beginWatch(callback: (doc: ReadyEntry, seq?: string | number) => Promise<any> | void, checkIsInterested?: (doc: MetaEntry) => boolean, onCheckpoint?: (seq: string | number) => Promise<void> | void): boolean;
     endWatch(): void;
     followUpdates(callback: (doc: ReadyEntry, seq?: string | number) => Promise<any> | void, checkIsInterested?: (doc: MetaEntry) => boolean): Promise<string | number>;
 }

package/dist/API/DirectFileManipulatorV2.js

@@ -1,4 +1,5 @@
 import { MemoryValueStore } from "@vrtmrz/value-store";
+import { createDirectChunkFetchSource } from "../managers/chunkFetchSource.js";
 import {
   DEFAULT_SETTINGS,
   DEFAULT_SYNC_PARAMETERS,
@@ -41,11 +42,7 @@ import {
 import { HeadlessServiceHub } from "../services/HeadlessServices.js";
 import { HeadlessDatabaseService } from "../services/implements/headless/HeadlessDatabaseService.js";
 import { ServiceContext } from "../services/base/ServiceBase.js";
-import { compatGlobal } from "../common/coreEnvFunctions.js";
-function isNoteEntry(doc) {
-  if (!doc) return false;
-  return doc.type == "newnote" || doc.type == "plain";
-}
+import { DirectFileWatchOwner, isNoteEntry } from "./DirectFileWatchOwner.js";
 function isReadyEntry(doc) {
   if (!doc) return false;
   return "data" in doc;
@@ -136,7 +133,9 @@ class DirectFileManipulator {
     });
     this.services.setting.settings = getSettings();
     this.services.databaseEvents.onDatabaseInitialisation.addHandler(this.$everyOnInitializeDatabase.bind(this));
-    this.liveSyncLocalDB = new LiveSyncLocalDB(this.options.url, this);
+    this.liveSyncLocalDB = new LiveSyncLocalDB(this.options.url, this, {
+      createChunkFetchSource: createDirectChunkFetchSource
+    });
     void this.ready.promise.catch(() => {
     });
     void this.init();
@@ -214,6 +213,7 @@ class DirectFileManipulator {
     return this.settings;
   }
   async close() {
+    this.endWatch();
     await this.liveSyncLocalDB.close();
     return this.liveSyncLocalDB.onunload();
   }
@@ -375,74 +375,53 @@ class DirectFileManipulator {
     }
   }
   watching = false;
-  // _abortController?: AbortController;
   changes;
   since = "";
-  beginWatch(callback, checkIsInterested) {
-    if (this.watching) return false;
-    this.watching = true;
-    this.changes = this.liveSyncLocalDB.localDatabase.changes({
-      include_docs: true,
-      since: this.since,
-      selector: {
-        type: { $ne: "leaf" }
-      },
-      live: true
-    }).on("change", async (change) => {
-      const doc = change.doc;
-      if (!doc) {
-        return;
-      }
-      if (!isNoteEntry(doc)) {
-        return;
-      }
-      if (checkIsInterested) {
-        if (!checkIsInterested(doc)) {
-          Logger(`WATCH: SKIP ${doc.path}: OUT OF TARGET FOLDER`, LOG_LEVEL_VERBOSE, "watch");
-          return;
+  watchOwner;
+  /**
+   * Watch file changes, retrying incomplete reads and rejected consumer callbacks.
+   * Resolving the file callback acknowledges processing. The optional checkpoint
+   * callback must resolve after the host has persisted its safe resume position.
+   */
+  beginWatch(callback, checkIsInterested, onCheckpoint) {
+    const manipulator = this;
+    this.watchOwner ??= new DirectFileWatchOwner({
+      state: {
+        get watching() {
+          return manipulator.watching;
+        },
+        set watching(value) {
+          manipulator.watching = value;
+        },
+        get changes() {
+          return manipulator.changes;
+        },
+        set changes(value) {
+          manipulator.changes = value;
+        },
+        get since() {
+          return manipulator.since;
+        },
+        set since(value) {
+          manipulator.since = value;
         }
-      }
-      Logger(`WATCH: PROCESSING: ${doc.path}`, LEVEL_VERBOSE, "watch");
-      let docX;
-      try {
-        docX = await this.getByMeta(doc);
-      } catch (ex) {
-        Logger(`WATCH: DOCUMENT LOAD FAILED: ${doc.path}`, LEVEL_INFO, "watch");
-        Logger(ex, LEVEL_VERBOSE, "watch");
-        return;
-      }
-      try {
-        await callback(docX, change.seq);
-        Logger(`WATCH: PROCESS DONE: ${doc.path}`, LEVEL_INFO, "watch");
-      } catch (ex) {
-        Logger(`WATCH: PROCESS FAILED`, LEVEL_INFO, "watch");
-        Logger(ex, LEVEL_VERBOSE, "watch");
-      }
-    }).on("complete", () => {
-      Logger(`WATCH: FINISHED`, LEVEL_INFO, "watch");
-      this.watching = false;
-      this.changes = void 0;
-    }).on("error", (err) => {
-      Logger(`WATCH: ERROR: `, LEVEL_INFO, "watch");
-      Logger(err, LEVEL_VERBOSE, "watch");
-      if (this.watching) {
-        Logger(`WATCH: CONNECTION HAS BEEN CLOSED, RECONNECTING...`, LEVEL_INFO, "watch");
-        this.watching = false;
-        this.changes = void 0;
-        compatGlobal.setTimeout(() => {
-          this.beginWatch(callback, checkIsInterested);
-        }, 1e4);
-      } else {
-        Logger(`WATCH: CONNECTION HAS BEEN CLOSED.`, LEVEL_INFO, "watch");
+      },
+      openChanges(since) {
+        return manipulator.liveSyncLocalDB.localDatabase.changes({
+          include_docs: true,
+          since,
+          selector: { type: { $ne: "leaf" } },
+          live: true
+        });
+      },
+      readDocument(doc) {
+        return manipulator.getByMeta(doc);
       }
     });
+    return this.watchOwner.beginWatch(callback, checkIsInterested, onCheckpoint);
   }
   endWatch() {
-    if (this.changes) {
-      Logger(`WATCH: CANCELLING PROCESS.`, LEVEL_INFO, "watch");
-      this.changes.cancel();
-      Logger(`WATCH: CANCELLING SIGNAL HAS BEEN SENT.`, LEVEL_INFO, "watch");
-    }
+    this.watchOwner?.endWatch();
   }
   async followUpdates(callback, checkIsInterested) {
     try {

package/dist/API/DirectFileWatchOwner.d.ts

@@ -0,0 +1,24 @@
+import type { EntryDoc, NewEntry, PlainEntry } from "../common/types.js";
+import type { MetaEntry, ReadyEntry } from "./DirectFileManipulatorV2.js";
+export interface DirectFileWatchState {
+    watching: boolean;
+    changes: PouchDB.Core.Changes<EntryDoc> | undefined;
+    since: string;
+}
+export interface DirectFileWatchHost {
+    readonly state: DirectFileWatchState;
+    openChanges(since: string): PouchDB.Core.Changes<EntryDoc>;
+    readDocument(doc: MetaEntry): Promise<ReadyEntry>;
+}
+type FileCallback = (doc: ReadyEntry, seq?: string | number) => Promise<unknown> | void;
+type SelectionCallback = (doc: MetaEntry) => boolean;
+type CheckpointCallback = (seq: string | number) => Promise<void> | void;
+export declare function isNoteEntry(doc: EntryDoc | false | undefined): doc is NewEntry | PlainEntry;
+/** Own watch sessions and work which remains in flight across stop and restart. */
+export declare class DirectFileWatchOwner {
+    private readonly context;
+    constructor(host: DirectFileWatchHost);
+    beginWatch(callback: FileCallback, checkIsInterested?: SelectionCallback, onCheckpoint?: CheckpointCallback): boolean;
+    endWatch(): void;
+}
+export {};

package/dist/API/DirectFileWatchOwner.js

@@ -0,0 +1,256 @@
+import { compatGlobal } from "../common/coreEnvFunctions.js";
+import { LEVEL_INFO, LEVEL_VERBOSE, Logger } from "octagonal-wheels/common/logger";
+import { bindContext } from "octagonal-wheels/context";
+import { withScope } from "octagonal-wheels/resource/scope";
+function isNoteEntry(doc) {
+  return !!doc && (doc.type == "newnote" || doc.type == "plain");
+}
+function isActive(session) {
+  return session.owner.session === session;
+}
+function isCurrent({ session, item, epoch }) {
+  return isActive(session) && session.connected && session.connection === epoch && session.pending.get(item.id) === item;
+}
+function retryDelay(failures) {
+  return Math.min(3e4, 1e3 * 2 ** Math.min(failures - 1, 5));
+}
+function documentPath(doc) {
+  return doc && "path" in doc ? doc.path : void 0;
+}
+function safePosition(session) {
+  return session.pending.values().next().value?.before ?? session.latest;
+}
+function cancelRetry(session) {
+  if (session.retryTimer !== void 0) clearTimeout(session.retryTimer);
+  session.retryTimer = void 0;
+}
+function cancelFeed(session) {
+  const state = session.owner.host.state;
+  const changes = state.changes;
+  state.changes = void 0;
+  changes?.cancel();
+}
+function stop(session) {
+  session.owner.host.state.watching = false;
+  session.connected = false;
+  session.connection++;
+  cancelRetry(session);
+  if (session.reconnectTimer !== void 0) clearTimeout(session.reconnectTimer);
+  session.reconnectTimer = void 0;
+  session.pending.clear();
+  session.owner.session = void 0;
+  cancelFeed(session);
+}
+function schedule(session) {
+  cancelRetry(session);
+  if (!isActive(session) || !session.connected) return;
+  let next = Infinity;
+  if (session.owner.inFlight < 4) {
+    for (const item of session.pending.values()) {
+      if (!item.running && !session.owner.delivering.has(item.id)) next = Math.min(next, item.due);
+    }
+  }
+  if (!session.checkpointTask && safePosition(session).order > session.durableOrder) {
+    next = Math.min(next, session.checkpointDue);
+  }
+  if (next !== Infinity) {
+    session.retryTimer = compatGlobal.setTimeout(bindContext(session, retry), Math.max(0, next - Date.now()));
+  }
+}
+function retry(session) {
+  session.retryTimer = void 0;
+  void pump(session);
+}
+async function persistCheckpoint({ session, position, epoch, previous }) {
+  if (previous) await previous;
+  if (!isActive(session) || session.connection !== epoch) return;
+  try {
+    await session.onCheckpoint?.(position.seq);
+    if (!isActive(session)) return;
+    session.owner.host.state.since = String(position.seq);
+    if (session.connection === epoch) session.durableOrder = position.order;
+    session.checkpointFailures = 0;
+    session.checkpointDue = 0;
+  } catch (ex) {
+    Logger(`WATCH: CHECKPOINT FAILED`, LEVEL_INFO, "watch");
+    Logger(ex, LEVEL_VERBOSE, "watch");
+    if (isActive(session) && session.connection === epoch) {
+      session.checkpointDue = Date.now() + retryDelay(++session.checkpointFailures);
+    }
+  }
+}
+function finishCheckpoint({ session, task }) {
+  session.checkpointTask = void 0;
+  if (session.owner.checkpointPending === task) session.owner.checkpointPending = void 0;
+  if (isActive(session)) {
+    void flushCheckpoint(session);
+    schedule(session);
+  }
+}
+function flushCheckpoint(session) {
+  if (session.checkpointTask) return session.checkpointTask;
+  if (!isActive(session) || !session.connected || Date.now() < session.checkpointDue) return Promise.resolve();
+  const position = safePosition(session);
+  if (position.order <= session.durableOrder) return Promise.resolve();
+  const context = {
+    session,
+    position,
+    epoch: session.connection,
+    previous: session.owner.checkpointPending
+  };
+  const task = persistCheckpoint(context).finally(bindContext(context, finishCheckpoint));
+  context.task = task;
+  session.checkpointTask = task;
+  session.owner.checkpointPending = task;
+  return task;
+}
+function releaseDelivery({ session, item }) {
+  session.owner.delivering.delete(item.id);
+}
+async function deliver(scope) {
+  const { session, item, ready } = scope.value;
+  session.owner.delivering.add(item.id);
+  scope.defer(bindContext(scope.value, releaseDelivery));
+  await session.callback(ready, item.seq);
+}
+async function processDocument(context) {
+  const { session, item } = context;
+  let loading = true;
+  try {
+    const doc = item.doc;
+    if (isNoteEntry(doc) && (!session.checkIsInterested || session.checkIsInterested(doc))) {
+      Logger(`WATCH: PROCESSING: ${doc.path}`, LEVEL_VERBOSE, "watch");
+      const ready = doc.deleted || doc._deleted ? { ...doc, data: [] } : await session.owner.host.readDocument(doc);
+      if (!isCurrent(context)) return;
+      loading = false;
+      await withScope({ ...context, ready }, deliver);
+      if (!isCurrent(context)) return;
+      Logger(`WATCH: PROCESS DONE: ${doc.path}`, LEVEL_INFO, "watch");
+    }
+    if (!isCurrent(context)) return;
+    session.pending.delete(item.id);
+    void flushCheckpoint(session);
+  } catch (ex) {
+    if (!isCurrent(context)) return;
+    Logger(
+      loading ? `WATCH: DOCUMENT LOAD FAILED: ${documentPath(item.doc)}` : `WATCH: PROCESS FAILED`,
+      LEVEL_INFO,
+      "watch"
+    );
+    Logger(ex, LEVEL_VERBOSE, "watch");
+    item.due = Date.now() + retryDelay(++item.failures);
+  }
+}
+function releaseFileOperation({ session, item }) {
+  item.running = false;
+  session.owner.inFlight--;
+  if (session.owner.session) void pump(session.owner.session);
+}
+async function processFileOperation(scope) {
+  scope.defer(bindContext(scope.value, releaseFileOperation));
+  await processDocument(scope.value);
+}
+function pump(session) {
+  if (!isActive(session) || !session.connected) return Promise.resolve();
+  const tasks = [];
+  for (const item of session.pending.values()) {
+    if (session.owner.inFlight >= 4) break;
+    if (item.running || item.due > Date.now() || session.owner.delivering.has(item.id)) continue;
+    item.running = true;
+    session.owner.inFlight++;
+    tasks.push(withScope({ session, item, epoch: session.connection }, processFileOperation));
+  }
+  void flushCheckpoint(session);
+  schedule(session);
+  return Promise.all(tasks).then(() => {
+  });
+}
+async function reconnectAfterCheckpoint(session) {
+  session.reconnectTimer = void 0;
+  if (session.checkpointTask) await session.checkpointTask;
+  if (isActive(session)) connect(session);
+}
+function reconnect({ session, epoch }) {
+  if (!isActive(session) || !session.connected || session.connection !== epoch) return;
+  session.owner.host.state.watching = false;
+  session.connected = false;
+  session.connection++;
+  cancelRetry(session);
+  session.pending.clear();
+  cancelFeed(session);
+  Logger(`WATCH: CONNECTION HAS BEEN CLOSED, RECONNECTING...`, LEVEL_INFO, "watch");
+  session.reconnectTimer = compatGlobal.setTimeout(bindContext(session, reconnectAfterCheckpoint), 1e4);
+}
+async function receiveChange({ session, epoch }, change) {
+  if (!isActive(session) || !session.connected || session.connection !== epoch) return;
+  const before = session.latest;
+  session.latest = { order: before.order + 1, seq: change.seq };
+  const id = change.id ?? change.doc?._id ?? documentPath(change.doc) ?? `row:${session.latest.order}`;
+  const previous = session.pending.get(id);
+  const doc = change.doc?._deleted && previous?.doc ? { ...previous.doc, ...change.doc } : change.doc;
+  session.pending.set(id, {
+    id,
+    doc,
+    seq: change.seq,
+    before: previous?.before ?? before,
+    running: false,
+    failures: 0,
+    due: 0
+  });
+  await pump(session);
+}
+function receiveError(context, error) {
+  if (!isActive(context.session) || context.session.connection !== context.epoch) return;
+  Logger(`WATCH: ERROR: `, LEVEL_INFO, "watch");
+  Logger(error, LEVEL_VERBOSE, "watch");
+  reconnect(context);
+}
+function connect(session) {
+  if (!isActive(session)) return;
+  const context = { session, epoch: ++session.connection };
+  const { state } = session.owner.host;
+  state.watching = true;
+  session.connected = true;
+  session.latest = { order: 0, seq: state.since };
+  session.durableOrder = 0;
+  session.checkpointFailures = 0;
+  session.checkpointDue = 0;
+  try {
+    state.changes = session.owner.host.openChanges(state.since).on("change", bindContext(context, receiveChange)).on("complete", bindContext(context, reconnect)).on("error", bindContext(context, receiveError));
+  } catch (ex) {
+    Logger(`WATCH: ERROR: `, LEVEL_INFO, "watch");
+    Logger(ex, LEVEL_VERBOSE, "watch");
+    reconnect(context);
+  }
+}
+class DirectFileWatchOwner {
+  context;
+  constructor(host) {
+    this.context = { host, inFlight: 0, delivering: /* @__PURE__ */ new Set() };
+  }
+  beginWatch(callback, checkIsInterested, onCheckpoint) {
+    if (this.context.session || this.context.host.state.watching) return false;
+    const session = {
+      owner: this.context,
+      callback,
+      checkIsInterested,
+      onCheckpoint,
+      pending: /* @__PURE__ */ new Map(),
+      latest: { order: 0, seq: this.context.host.state.since },
+      durableOrder: 0,
+      connection: 0,
+      connected: false,
+      checkpointFailures: 0,
+      checkpointDue: 0
+    };
+    this.context.session = session;
+    connect(session);
+  }
+  endWatch() {
+    if (this.context.session) stop(this.context.session);
+  }
+}
+export {
+  DirectFileWatchOwner,
+  isNoteEntry
+};

package/dist/API/processSetting.js

@@ -10,11 +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";
+import { assertSupportedPathNormalizationVersion, getPathNormalizationVersion } from "../common/pathNormalization.js";
 function encodeSettingsToQRCodeData(settings) {
   settings = omitP2PRuntimeSettings(settings);
   configuredIdKey(settings);
-  getPathNormalizationVersion(settings);
+  assertSupportedPathNormalizationVersion(settings.pathNormalizationVersion);
   const fullIndexes = Object.entries(KeyIndexOfSettings);
   let maxIndex = 0;
   for (const [, index] of fullIndexes) {
@@ -137,7 +137,7 @@ async function encodeSettingsToSetupURI(settingString, passphrase, removePropert
   const setting = {
     ...omitP2PRuntimeSettings(settingString)
   };
-  getPathNormalizationVersion(setting);
+  assertSupportedPathNormalizationVersion(setting.pathNormalizationVersion);
   configuredIdKey({
     idDerivationVersion: setting.idDerivationVersion ?? 0,
     idDerivationKey: setting.idDerivationKey ?? ""

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

@@ -557,7 +557,7 @@ export interface P2PConnectionInfo {
      */
     P2P_useDiagRTC?: boolean;
 }
-export interface P2PSyncSetting extends P2PConnectionInfo {
+export interface P2PSyncSetting extends P2PConnectionInfo, Partial<PathIdentitySettings> {
     P2P_AutoAccepting: AutoAccepting;
     P2P_AutoSyncPeers: string;
     P2P_AutoWatchPeers: string;

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

@@ -66,8 +66,7 @@ const configurationNames = {
   },
   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
+    desc: "Version 0 preserves legacy path identity; version 1 uses Unicode NFC. Physical file names stay unchanged. Update every device and stop synchronisation, then Rebuild from a complete authoritative Vault and Fetch on the other devices. With P2P, Rebuild prepares only the source device's local database. Resolve colliding file names first."
   },
   doNotUseFixedRevisionForChunks: {
     name: "Content-derived chunk revisions (obsolete setting)",

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

@@ -120,8 +120,8 @@ export declare const TweakValuesRecommendedTemplate: Partial<ObsidianLiveSyncSet
 export declare const TweakValuesDefault: Partial<ObsidianLiveSyncSettings>;
 export declare const TweakValuesTemplate: {
     tweakModified: number;
-    usePluginSyncV2: boolean;
     pathNormalizationVersion: import("./setting.type.js").PathNormalizationVersion;
+    usePluginSyncV2: boolean;
     encrypt: boolean;
     idDerivationVersion: 0 | 1;
     usePathObfuscation: boolean;

package/dist/common/pathNormalization.d.ts

@@ -1,4 +1,6 @@
 import type { PathNormalizationVersion } from "./models/setting.type.js";
+/** Reject unsupported path identity versions while allowing an absent legacy value. */
+export declare function assertSupportedPathNormalizationVersion(version: number | undefined): asserts version is PathNormalizationVersion | undefined;
 /** Resolve the stored path identity version, treating an absent legacy value as version zero. */
 export declare function getPathNormalizationVersion(settings: {
     pathNormalizationVersion?: number;

package/dist/common/pathNormalization.js

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

package/dist/managers/ChunkFetcher.d.ts

@@ -1,5 +1,6 @@
 import { type DocumentID } from "../common/types.js";
 import { type ChunkManager } from "./ChunkManager.js";
+import type { ChunkFetchSource } from "./chunkFetchSource.js";
 import type { IReplicatorService, ISettingService } from "../services/base/IService.js";
 export declare const EVENT_MISSING_CHUNKS = "missingChunks";
 export declare const EVENT_MISSING_CHUNK_REMOTE = "missingChunkRemote";
@@ -9,6 +10,8 @@ export type ChunkFetcherOptions = {
     chunkManager: ChunkManager;
     replicatorService: IReplicatorService;
     deliveryStallTimeoutMs?: number;
+    /** Direct hosts replace both retrieval and acceptance; the default uses the active replicator. */
+    source?: ChunkFetchSource;
 };
 export declare class ChunkFetcher {
     options: ChunkFetcherOptions;