@vrtmrz/livesync-commonlib 0.2.3 → 0.3.1

package/README.md

@@ -14,6 +14,19 @@ This package is primarily for maintainers of those clients and for integrations
 
 ## Status and versioning
 
+Commonlib [0.3.0](https://www.npmjs.com/package/@vrtmrz/livesync-commonlib/v/0.3.0)
+is published on npm. Self-hosted LiveSync
+[1.0.44](https://github.com/vrtmrz/obsidian-livesync/releases/tag/1.0.44)
+uses Commonlib 0.2.3. The [0.2.3 release notes](updates.md#023) record its
+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.
@@ -27,6 +40,11 @@ ordinary replication before resuming local writers. Existing hosts can omit
 this optimisation. Resume cursors retain their existing meaning; this resource
 does not provide an arbitrary-time checkpoint jump or On Demand repair.
 
+Unreleased CouchDB work separates encrypted HTTP responses by Security Seed
+while retaining conditional revalidation within a Seed. See
+[CouchDB response caching](docs/couchdb-http-cache.md) for the request,
+replication-preparation, and host-adapter boundaries.
+
 ## Package entry points
 
 | Entry point                                        | Intended use                                                                      | Current contract status                                                                     |
@@ -35,6 +53,7 @@ does not provide an arbitrary-time checkpoint jump or On Demand repair.
 | `@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/storage` | Path types, namespace and comparison helpers, and strict Unicode path resolution | Unreleased additive contract; host integration remains explicit |
 | `@vrtmrz/livesync-commonlib/hashing`               | Chunk ID calculation and exact file-content hashing                            | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/browser`               | Rooted File System Access API storage                                             | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/node`                  | Rooted Node storage, Node standard I/O, and selected Node capabilities            | Supported platform façade; keeps Node-only dependencies behind an explicit boundary         |
@@ -52,8 +71,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 +87,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 +100,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 +311,26 @@ 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.
+Commonlib 0.3.0 provides [Unicode NFC path identity](docs/unicode-path-identity.md) with CouchDB, Object Storage, and P2P for maintained CLI and Obsidian host integrations. Application adoption remains in [Self-hosted LiveSync #1309](https://github.com/vrtmrz/obsidian-livesync/pull/1309). Changing an existing database's path identity requires coordinated Rebuild and Fetch. P2P participants must all be updated and migrated.
+
+## Direct database watches
+
+An unreleased extension lets direct CouchDB integrations select
+`pathNormalizationVersion: 1` in `DirectFileManipulator` options. Omitted or
+`0` retains Legacy identity. The configured mode must match the database;
+NFC does not relabel a populated Legacy database. A confirmed empty database
+can declare the selected feature before its first Metadata write. Hosts still
+own physical path resolution and the coordinated migration of existing data.
+
+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 +357,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

@@ -15,6 +15,7 @@ export type DirectFileManipulatorOptions = {
     obfuscatePassphrase: string | undefined;
     idDerivationVersion?: 0 | 1;
     idDerivationKey?: string;
+    pathNormalizationVersion?: 0 | 1;
     encryptInternalMetadata?: boolean;
     useDynamicIterationCount?: boolean;
     customChunkSize?: number;
@@ -137,7 +138,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,21 +1,21 @@
 import { MemoryValueStore } from "@vrtmrz/value-store";
+import { createDirectChunkFetchSource } from "../managers/chunkFetchSource.js";
 import {
   DEFAULT_SETTINGS,
   DEFAULT_SYNC_PARAMETERS,
   ProtocolVersions,
   DOCID_SYNC_PARAMETERS,
-  VERSIONING_DOCID,
   E2EEAlgorithms,
   VER
 } from "../common/types.js";
 import { checkRemoteVersion } from "../pouchdb/negotiation.js";
 import {
-  assessRemoteFeatureDocument,
-  NFC_PATH_IDENTITY_FEATURE,
   requiredRemoteFeatures,
   usesEncryptedInternalMetadata
 } from "../pouchdb/remoteFeatureCompatibility.js";
 import { assessRemoteDocumentIds } from "../pouchdb/remoteIdCompatibility.js";
+import { assertDatabasePathIdentity } from "../pouchdb/pathIdentityCompatibility.js";
+import { getPathNormalizationVersion } from "../common/pathNormalization.js";
 import { PouchDB } from "../pouchdb/pouchdb-http.js";
 import { LiveSyncLocalDB } from "../pouchdb/LiveSyncLocalDB.js";
 import { isErrorOfMissingDoc } from "../pouchdb/utils_couchdb.js";
@@ -41,11 +41,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;
@@ -74,15 +70,7 @@ class DirectFileManipulator {
       if (idCompatibility === "mismatched") {
         throw new Error("Direct database document IDs do not match the configured ID key.");
       }
-      try {
-        const versionInfo = await this.liveSyncLocalDB.localDatabase.get(VERSIONING_DOCID);
-        const assessment = assessRemoteFeatureDocument(versionInfo);
-        if (assessment.status === "supported" && assessment.usedFeatures.includes(NFC_PATH_IDENTITY_FEATURE)) {
-          throw new Error("Direct database version or features are not compatible.");
-        }
-      } catch (error) {
-        if (!isErrorOfMissingDoc(error)) throw error;
-      }
+      await assertDatabasePathIdentity(this.liveSyncLocalDB.localDatabase, idSettings);
       const requiredFeatures = requiredRemoteFeatures(this.settings);
       if (!await checkRemoteVersion(
         this.liveSyncLocalDB.localDatabase,
@@ -136,7 +124,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 +204,7 @@ class DirectFileManipulator {
     return this.settings;
   }
   async close() {
+    this.endWatch();
     await this.liveSyncLocalDB.close();
     return this.liveSyncLocalDB.onunload();
   }
@@ -229,6 +220,9 @@ class DirectFileManipulator {
         passphrase: this.options.passphrase ?? "",
         idDerivationVersion: this.options.idDerivationVersion ?? 0,
         idDerivationKey: this.options.idDerivationKey ?? "",
+        pathNormalizationVersion: getPathNormalizationVersion({
+          pathNormalizationVersion: this.options.pathNormalizationVersion
+        }),
         deleteMetadataOfDeletedFiles: DEFAULT_SETTINGS.deleteMetadataOfDeletedFiles,
         customChunkSize: this.options.customChunkSize ?? DEFAULT_SETTINGS.customChunkSize,
         doNotPaceReplication: DEFAULT_SETTINGS.doNotPaceReplication,
@@ -375,74 +369,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.d.ts

@@ -156,6 +156,7 @@ export declare function decodeSettingsFromSetupURI(uri: string, passphrase: stri
     jwtSub: string;
     jwtExpDuration: number;
     useRequestAPI: boolean;
+    useCouchDBCacheControlHeadersOnly?: boolean;
     accessKey: string;
     secretKey: string;
     bucket: string;

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.const.defaults.js

@@ -189,6 +189,7 @@ const SETTINGS_SCHEMA_DEFAULTS = {
   jwtSub: "",
   jwtExpDuration: 5,
   useRequestAPI: false,
+  useCouchDBCacheControlHeadersOnly: false,
   bucketPrefix: "",
   chunkSplitterVersion: ChunkAlgorithms.RabinKarp,
   E2EEAlgorithm: E2EEAlgorithms.V2,