@vrtmrz/livesync-commonlib 0.2.2 → 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.
@@ -32,6 +45,7 @@ does not provide an arbitrary-time checkpoint jump or On Demand repair.
 | Entry point                                        | Intended use                                                                      | Current contract status                                                                     |
 | -------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
 | `@vrtmrz/livesync-commonlib`                       | `DirectFileManipulator` for integrations which access CouchDB directly            | Deliberately small, but its high-level lifecycle and file-operation semantics are not final |
+| `@vrtmrz/livesync-commonlib/conflicts` | Keyed conflict-check scheduling with bounded concurrency and explicit completion | Focused, package-tested pre-1.0 contract |
 | `@vrtmrz/livesync-commonlib/context`               | Instance-owned events, translation injection, and host-neutral standard-I/O types | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/diagnostics` | Read-only Usage and integrity inspection, name projection, and reports | Focused pre-1.0 diagnostic contract |
 | `@vrtmrz/livesync-commonlib/hashing`               | Chunk ID calculation and exact file-content hashing                            | Focused, package-tested pre-1.0 contract                                                    |
@@ -47,6 +61,16 @@ does not provide an arbitrary-time checkpoint jump or On Demand repair.
 | `@vrtmrz/livesync-commonlib/compat/*`              | Exact legacy imports still required by existing clients                           | Migration-only; retained within 0.2.x, with removals treated as 0.3.0 breaking changes       |
 | `@vrtmrz/livesync-commonlib/package.json`          | Package metadata for tooling                                                      | Metadata export, not a runtime API                                                          |
 
+The existing `compat/services/lib` boundary retains `bindableFunction` and `lazyBindableFunction` for current clients. Their `setHandler()` methods return an `UnregisterFunction` which removes only its own current assignment; stale removers, including after an override with the same callback, and repeated removals are no-ops. Existing callers may ignore the return value. These helpers remain a migration boundary, not a general-purpose SDK integration surface.
+
+The `compat/pouchdb/chunks` entry retains the obsolete `transferChunks`,
+`balanceChunkPurgedDBs`, and `fetchAllUsedChunks` helpers for existing consumers.
+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.
+
 Import only the entry point required by the current runtime. Browser code must not import the Node entry.
 
 The Node and browser entries are platform façades. They keep platform-specific adapters and capabilities behind package-owned boundaries, so a consumer does not have to reproduce those imports or their build and review exceptions. The Node entry's selected built-in-module exports are deliberate parts of that façade. Package checks ensure that the root, context, and browser entries do not load the Node implementation.
@@ -55,6 +79,32 @@ The RPC entry exists only while the maintained LiveSync P2P composition depends
 
 The P2P entry exposes eight focused views over one service owner, together with the maintained host-composition helpers. New consumers select only the lifecycle, peer-directory, peer-admission, targeted-transfer, change-relay, configuration-exchange, diagnostic, or connection-probe-admission view which they need. The composition result still carries a deprecated concrete Replicator façade while existing panes migrate; new consumers must not depend on that property or reach through it to a raw room or host.
 
+## Blob helper migration
+
+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
+`text/plain` and `application/octet-stream` respectively.
+
+New code which only needs Blob conversion or byte comparison should use the focused
+`octagonal-wheels/binary/blob` entry in Octagonal Wheels 0.1.56 or later.
+Its normalisation function is named `toBlob`; its creation functions retain
+`createTextBlob` and `createBinaryBlob`. Its `isBlobContentEqual` function
+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. 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
+IndexedDB selection and native receiver. Its fallback delegates bounded reads
+to `isBlobContentEqual`, using the existing Commonlib Base64 encoder and host
+Buffer fallback. The compatibility import retains its existing
+environment initialisation; the focused Octagonal Wheels entry does not
+initialise fetch or DOM services.
+
 ## Host context and initialisation
 
 One service context belongs to one independently composed Commonlib client. It owns that client's event hub and translator. Creating a context without options creates a fresh event hub and renders Commonlib's typed canonical English messages. A host may inject a translator to provide another language:
@@ -255,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
 
@@ -276,3 +338,26 @@ See [Maintained-host examples and evidence](docs/proven-in-use.md) for compositi
 ## Licence
 
 MIT
+
+
+## Shared value helper migration
+
+The shared formatter displays positive infinity as `∞y`, including through the existing `timeDeltaToHumanReadable` entry. Other duration formatting cases retain their previous behaviour.
+
+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 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
+does not interpret escapes. `asCopy<T>` retains its existing type signature
+for compatibility. The typed `cloneViaJSON` entry instead constrains its input
+to JSON-compatible types and defaults its output type to that input shape.
+Explicit output types are caller assertions, not runtime validation. The legacy
+adapter still follows native JSON behaviour for Dates, undefined fields, and
+toJSON hooks; neither entry preserves prototypes or shared object identity.

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/ContentSplitter/ContentSplitterRabinKarp.js

@@ -8,23 +8,8 @@ class ContentSplitterRabinKarp extends ContentSplitterBase {
     return settings.chunkSplitterVersion === ChunkAlgorithms.RabinKarp;
   }
   async processSplit(options) {
-    if (options.useWorker) {
-      return (await splitPieces2WorkerRabinKarp(
-        options.blob,
-        options.pieceSize,
-        options.plainSplit,
-        options.minimumChunkSize,
-        options.path
-      ))();
-    } else {
-      return (await splitPiecesRabinKarp(
-        options.blob,
-        options.pieceSize,
-        options.plainSplit,
-        options.minimumChunkSize,
-        options.path
-      ))();
-    }
+    const split = options.useWorker ? splitPieces2WorkerRabinKarp : splitPiecesRabinKarp;
+    return (await split(options.blob, options.pieceSize, options.plainSplit, options.minimumChunkSize, options.path))();
   }
 }
 export {

package/dist/ContentSplitter/ContentSplitterV1.js

@@ -8,25 +8,15 @@ class ContentSplitterV1 extends ContentSplitterBase {
     return settings.chunkSplitterVersion === ChunkAlgorithms.V1 || settings.chunkSplitterVersion === "" || settings.chunkSplitterVersion === void 0;
   }
   async processSplit(options) {
-    if (options.useWorker) {
-      return (await splitPieces2Worker(
-        options.blob,
-        options.pieceSize,
-        options.plainSplit,
-        options.minimumChunkSize,
-        options.path,
-        options.useSegmenter
-      ))();
-    } else {
-      return (await splitPieces2(
-        options.blob,
-        options.pieceSize,
-        options.plainSplit,
-        options.minimumChunkSize,
-        options.path,
-        options.useSegmenter
-      ))();
-    }
+    const split = options.useWorker ? splitPieces2Worker : splitPieces2;
+    return (await split(
+      options.blob,
+      options.pieceSize,
+      options.plainSplit,
+      options.minimumChunkSize,
+      options.path,
+      options.useSegmenter
+    ))();
   }
 }
 export {