@vrtmrz/livesync-commonlib 0.1.44 → 0.2.1

package/README.md

@@ -14,12 +14,19 @@ This package is primarily for maintainers of those clients and for integrations
 
 ## Status and versioning
 
-The package is pre-1.0. Pin an exact reviewed version, and review changes before upgrading. 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.
+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.
 
 The package is ESM-only and declares Node 20 or later. Browser entry points are built with browser conditions, but the host remains responsible for checking the availability of browser capabilities such as the File System Access API.
 
+Fast Fetch imports all current leaf revisions listed by CouchDB, including
+deleted conflict leaves. A host may supply the optional
+`initial-fetch-fast-forward` resource to hand a fresh, complete import to
+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.
+
 ## Package entry points
 
 | Entry point                                        | Intended use                                                                      | Current contract status                                                                     |
@@ -36,7 +43,8 @@ The package is ESM-only and declares Node 20 or later. Browser entry points are
 | `@vrtmrz/livesync-commonlib/remote-configurations` | Multiple-remote profile creation, naming, and selection                           | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/settings`              | New-Vault defaults, stored-setting fallbacks, and settings migration results      | Focused, package-tested pre-1.0 contract                                                    |
 | `@vrtmrz/livesync-commonlib/setup-uri`             | Encrypted Setup URI generation, availability, and import                          | Focused, package-tested pre-1.0 contract                                                    |
-| `@vrtmrz/livesync-commonlib/compat/*`              | Exact legacy imports still required by existing clients                           | Migration-only; paths may be removed as consumers migrate                                   |
+| `@vrtmrz/livesync-commonlib/ui-commands` | Instance-owned typed UI command declarations and handlers | Focused, package-tested contract |
+| `@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                                                          |
 
 Import only the entry point required by the current runtime. Browser code must not import the Node entry.
@@ -75,6 +83,74 @@ After the Self-hosted LiveSync 1.0 work, the planned high-level composition is a
 
 The factory is not implemented yet. Until it is available, service implementations exposed under `compat/*` retain their owning client's lifecycle rather than becoming a general public composition API.
 
+## UI commands
+
+Import `declareUICommand` and `UICommandRegistry` from `@vrtmrz/livesync-commonlib/ui-commands`. A declaration binds a stable command ID to its request and result types. Each `UIService` owns its own `commands` registry; declarations do not register global handlers.
+
+```ts
+import { declareUICommand } from "@vrtmrz/livesync-commonlib/ui-commands";
+
+const showDevices = declareUICommand<void, 'closed'>('example:show-devices');
+const unregister = services.UI.commands.register(showDevices, async () => {
+    await openHostDeviceDialogue();
+    return 'closed';
+});
+const result = await services.UI.commands.invoke(showDevices, undefined);
+// result is { status: 'handled', value: 'closed' } or { status: 'unavailable' }.
+unregister();
+```
+
+A feature releases its handler when it unloads. The host dialogue owner remains responsible for active UI work. Duplicate handlers and conflicting declarations with the same ID are rejected; handler failures propagate. Calling an unavailable or disposed registry settles immediately. `UIService` disposes its registry on the context's plug-in-unloaded event.
+
+## Joined device records
+
+The `/replication` entry includes the `joined-devices` finite resource contract. A provider binds each resource to one settings snapshot; its owner calls `dispose()` in `finally`. `read()` returns recorded device IDs, acceptance, versions, platform, and connection times where available. An absent milestone is explicit. Joined-device operations never initialise a missing CouchDB database. These records do not establish online presence.
+
+`forget(id)` removes one other device from all participation maps and the accepted list, while retaining the lock state, preferred tweaks, and unknown fields. The CouchDB implementation rereads the existing milestone before editing and verifies removal after saving. CouchDB local documents do not reject stale revisions, so concurrent changes to other device records can be overwritten. A failed verification is reported to the caller for manual refresh and retry. Object Storage checks ETags with conditional writes and retries conflicts a bounded number of times. Missing records, unsupported conditional writes, and exhausted conflicts have distinct results. Forgetting is not credential revocation: an unlocked remote permits a returning device to register again.
+
+## Replication statistics
+
+Hosts can read the latest `services.replicator.replicationStatics.value` and
+subscribe to that reactive source. The focused `/replication` entry exports
+`ReplicationStatics`, `CouchDBReplicationProgress`, and
+`ReplicationCheckpointProgress`. Existing transfer counters and `syncStatus`
+retain their meanings.
+
+The optional `couchDB` snapshot describes the ordinary CouchDB replication
+attempt. Other providers omit it. Its `phase` distinguishes `one-shot`,
+`catch-up` (the pull preceding each continuous start or reconnect),
+`continuous`, and `idle`. Preparation can expose a phase before directional
+progress is available. This is independent of activity, pause, or failure in
+`syncStatus`; entering `continuous` does not establish that Vault reflection
+has finished or that editing is safe.
+
+Optional `pull` and `push` observations each contain:
+
+- `checkedChanges`: changes-feed entries presented for revision comparison,
+  including both existing and missing revisions. One entry with several
+  revisions counts once; repeated entries during retries can count again.
+  This is neither a Vault file count nor an exact count of skipped transfers.
+- `completedBatches`: batches which reached PouchDB's checkpoint notification,
+  including batches which transferred no documents.
+- `lastSeq`: the last processed checkpoint position, preserved as a number or
+  an opaque string. It is not a remaining-work estimate, percentage, or proof
+  that a checkpoint was durably written.
+- `checking`: observed revision comparison in the current batch, cleared by
+  a transfer notification, pause, or termination. It does not establish that
+  network transfer has not begun.
+
+Counts and positions reset for each underlying PouchDB handler, including the
+transition from catch-up to continuous replication and a replacement attempt.
+Completion, failure, and cancellation retain final values with `phase: 'idle'`
+and `checking: false`. Replacing the provider clears its previous snapshot.
+
+Checkpoint events are accumulated internally and published periodically
+(currently about 200 ms). Transfer, pause, and terminal boundaries flush
+pending observations promptly. The interval is an implementation detail.
+The observer releases its timer and listeners on termination; late callbacks
+cannot publish into the next attempt. These observations do not modify the
+replication options, received documents, or native checkpoints.
+
 ## Rooted storage
 
 Both platform storage factories receive an existing root from the host. They never select a directory, request browser permission, infer a process directory, or persist a handle.
@@ -191,11 +267,11 @@ The accepted replacement direction is an asynchronously created file client with
 
 Package developers should read [the developer guide](docs/development.md). The focused contracts are described in [the storage guide](docs/platform-storage.md), [the standard-I/O guide](docs/platform-standard-io.md), [the settings lifecycle guide](docs/settings-lifecycle.md), [the remote configuration profile guide](docs/remote-configurations.md), [the remote feature compatibility contract](docs/remote-feature-compatibility.md), [the conflict-resolution guide](docs/conflict-resolution.md), and [the P2P transport lifecycle guide](docs/p2p-transport-lifecycle.md).
 
-## Proven in maintained hosts
+## Maintained-host examples and evidence
 
 The package boundary is exercised by Self-hosted LiveSync's Obsidian plug-in, CLI, WebApp, and WebPeer compositions. Their validation is not uniform: the Obsidian plug-in and CLI have the strongest device and long-running synchronisation evidence, while WebApp and WebPeer have focused adapter and runtime tests, browser smoke tests, a cross-application P2P scenario ending at the production CLI, and public Pages smoke validation.
 
-See [Proven in maintained hosts](docs/proven-in-use.md) for the actual composition points, downstream tests, and remaining limits. The examples deliberately separate focused public entries which a new consumer may copy from `compat/*` imports which exist to migrate the current application.
+See [Maintained-host examples and evidence](docs/proven-in-use.md) for composition points, downstream tests, and remaining limits. This optional page records examples and evidence; it does not define package support or create a release or adoption requirement. The examples deliberately separate focused public entries which a new consumer may copy from `compat/*` imports which exist to migrate the current application.
 
 ## Licence
 

package/dist/API/DirectFileManipulatorV2.d.ts

@@ -24,6 +24,8 @@ export type DirectFileManipulatorOptions = {
     maxChunksInEden?: number;
     maxTotalLengthInEden?: number;
     maxAgeInEden?: number;
+    /** Enables synchronisation of dot-prefixed internal files. */
+    syncInternalFiles?: boolean;
     /**
      * @deprecated use chunkSplitterVersion instead.
      */

package/dist/API/DirectFileManipulatorV2.js

@@ -1,3 +1,4 @@
+import { MemoryValueStore } from "@vrtmrz/value-store";
 import {
   DEFAULT_SETTINGS,
   DEFAULT_SYNC_PARAMETERS,
@@ -119,6 +120,7 @@ class DirectFileManipulator {
     const getSettings = () => this.settings;
     const context = new ServiceContext();
     this.services = new HeadlessServiceHub(context, {
+      deviceValues: new MemoryValueStore(),
       pouchDB: PouchDB,
       database: this.getBoundDatabaseService(() => this.options, this.runtimeOptions),
       getPathObfuscationPassphrase: () => this.options.obfuscatePassphrase ?? false,
@@ -253,6 +255,7 @@ class DirectFileManipulator {
         handleFilenameCaseSensitive: this.options.handleFilenameCaseSensitive ?? DEFAULT_SETTINGS.handleFilenameCaseSensitive,
         usePathObfuscation: !!this.options.obfuscatePassphrase,
         encryptInternalMetadata: this.options.encryptInternalMetadata ?? false,
+        syncInternalFiles: this.options.syncInternalFiles ?? DEFAULT_SETTINGS.syncInternalFiles,
         E2EEAlgorithm: this.options.E2EEAlgorithm ?? E2EEAlgorithms.V2
       }
     };

package/dist/API/processSetting.d.ts

@@ -59,6 +59,7 @@ export declare function decodeSettingsFromSetupURI(uri: string, passphrase: stri
     idDerivationKey: string;
     pathNormalizationVersion: import("../settings.js").PathNormalizationVersion;
     liveSync: boolean;
+    batchSaveInLiveSync?: boolean;
     syncOnSave: boolean;
     syncOnStart: boolean;
     syncOnFileOpen: boolean;

package/dist/common/configForDoc.d.ts

@@ -53,6 +53,7 @@ export declare const DoctorRegulationV0_25_0: DoctorRegulation;
 export declare const DoctorRegulationV0_25_27: DoctorRegulation;
 export declare const DoctorRegulationV1_0_0: DoctorRegulation;
 export declare const DoctorRegulationV1_0_33: DoctorRegulation;
+export declare const DoctorRegulationV1_0_40: DoctorRegulation;
 export declare const DoctorRegulation: DoctorRegulation;
 export declare function checkUnsuitableValues(setting: Partial<ObsidianLiveSyncSettings>, regulation?: DoctorRegulation): DoctorRegulation;
 export declare const RebuildOptions: {

package/dist/common/configForDoc.js

@@ -139,7 +139,16 @@ const DoctorRegulationV1_0_33 = {
     }
   }
 };
-const DoctorRegulation = DoctorRegulationV1_0_33;
+const DoctorRegulationV1_0_40 = {
+  // Only withdraw a recommendation. Retain the consultation version so users
+  // who dismissed 1.0.33 are not prompted again for unchanged recommendations.
+  version: DoctorRegulationV1_0_33.version,
+  rules: {
+    ...DoctorRegulationV1_0_33.rules,
+    customChunkSize: void 0
+  }
+};
+const DoctorRegulation = DoctorRegulationV1_0_40;
 function checkUnsuitableValues(setting, regulation = DoctorRegulation) {
   const result = {
     version: regulation.version,
@@ -339,6 +348,7 @@ export {
   DoctorRegulationV0_25_27,
   DoctorRegulationV1_0_0,
   DoctorRegulationV1_0_33,
+  DoctorRegulationV1_0_40,
   RebuildOptions,
   RuleLevel,
   checkUnsuitableValues,

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

@@ -20,6 +20,7 @@ export interface DeviceInfo {
      */
     plugin_version: string;
     progress: string;
+    platform?: string;
 }
 export interface NodeData extends DeviceInfo {
     /**

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

@@ -40,6 +40,7 @@ const SETTINGS_SCHEMA_DEFAULTS = {
   couchDB_PASSWORD: "",
   couchDB_DBNAME: "",
   liveSync: false,
+  batchSaveInLiveSync: false,
   syncOnSave: false,
   syncOnStart: false,
   savingDelay: 200,

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

@@ -1,6 +1,7 @@
 import { E2EEAlgorithms } from "./setting.const.js";
 const PREFERRED_BASE = {
   syncMaxSizeInMB: 50,
+  customChunkSize: 0,
   chunkSplitterVersion: "v3-rabin-karp",
   usePluginSyncV2: true,
   handleFilenameCaseSensitive: false,
@@ -8,21 +9,18 @@ const PREFERRED_BASE = {
 };
 const PREFERRED_SETTING_CLOUDANT = {
   ...PREFERRED_BASE,
-  customChunkSize: 0,
   sendChunksBulkMaxSize: 1,
   concurrencyOfReadChunksOnline: 100,
   minimumIntervalOfReadChunksOnline: 333
 };
 const PREFERRED_SETTING_SELF_HOSTED = {
   ...PREFERRED_BASE,
-  customChunkSize: 60,
   sendChunksBulkMaxSize: 1,
   concurrencyOfReadChunksOnline: 30,
   minimumIntervalOfReadChunksOnline: 25
 };
 const PREFERRED_JOURNAL_SYNC = {
   ...PREFERRED_BASE,
-  customChunkSize: 10,
   concurrencyOfReadChunksOnline: 30,
   minimumIntervalOfReadChunksOnline: 25
 };

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

@@ -181,6 +181,7 @@ const KeyIndexOfSettings = {
   idDerivationVersion: 166,
   idDerivationKey: 167,
   pathNormalizationVersion: 168,
+  batchSaveInLiveSync: 169,
   encryptedIdDerivationKey: -1
 };
 export {

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

@@ -53,6 +53,10 @@ export declare const SETTINGS_PROPERTY_POLICY: {
         readonly markdown: "include";
         readonly persistence: "include";
     };
+    readonly batchSaveInLiveSync: {
+        readonly markdown: "include";
+        readonly persistence: "include";
+    };
     readonly syncOnSave: {
         readonly markdown: "include";
         readonly persistence: "include";

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

@@ -14,6 +14,7 @@ const SettingPolicies = {
 };
 const SETTINGS_PROPERTY_POLICY = {
   liveSync: SettingPolicies.Default,
+  batchSaveInLiveSync: SettingPolicies.Default,
   syncOnSave: SettingPolicies.Default,
   syncOnStart: SettingPolicies.Default,
   syncOnFileOpen: SettingPolicies.Default,

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

@@ -80,6 +80,8 @@ interface SyncMethodSettings {
      * Synchronise in Live. This is an exclusive setting against other sync methods.
      */
     liveSync: boolean;
+    /** Explicitly enable batched local database updates in LiveSync mode; an absent value is false. */
+    batchSaveInLiveSync?: boolean;
     /**
      * automatically run sync on save.
      * File modification will trigger the sync, even if the file is not changed on the editor.

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

@@ -10,6 +10,24 @@ export declare const DatabaseConnectingStatuses: {
     readonly JOURNAL_RECEIVE: "JOURNAL_RECEIVE";
 };
 export type DatabaseConnectingStatus = (typeof DatabaseConnectingStatuses)[keyof typeof DatabaseConnectingStatuses];
+/** The transfer stage; entering continuous replication does not imply Vault reflection is complete. */
+export type CouchDBReplicationPhase = "idle" | "one-shot" | "catch-up" | "continuous";
+export type ReplicationCheckpointProgress = {
+    /** Changes-feed entries presented for revision comparison, including repeated entries on retries. */
+    readonly checkedChanges: number;
+    /** Batches which reached PouchDB's checkpoint notification, including batches without transfers. */
+    readonly completedBatches: number;
+    /** Opaque processed position, not a remaining-document count or proof of durable checkpoint storage. */
+    readonly lastSeq?: string | number;
+    /** Revision comparison is progressing; this does not establish that network transfer has not begun. */
+    readonly checking: boolean;
+};
+/** Counters reset for each underlying PouchDB attempt, including the transition from catch-up to continuous. */
+export type CouchDBReplicationProgress = {
+    readonly phase: CouchDBReplicationPhase;
+    readonly pull?: ReplicationCheckpointProgress;
+    readonly push?: ReplicationCheckpointProgress;
+};
 export type ReplicationStatics = {
     sent: number;
     arrived: number;
@@ -18,5 +36,7 @@ export type ReplicationStatics = {
     lastSyncPullSeq: number;
     lastSyncPushSeq: number;
     syncStatus: DatabaseConnectingStatus;
+    /** Present only when the provider supplies CouchDB checkpoint observations. */
+    couchDB?: CouchDBReplicationProgress;
 };
 export declare const DEFAULT_REPLICATION_STATICS: ReplicationStatics;

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

@@ -142,6 +142,7 @@ export declare const TweakValuesTemplate: {
     enableCompression: boolean;
     handleFilenameCaseSensitive: boolean;
     liveSync?: boolean;
+    batchSaveInLiveSync?: boolean;
     syncOnSave?: boolean;
     syncOnStart?: boolean;
     syncOnFileOpen?: boolean;

package/dist/common/settingConstants.d.ts

@@ -30,6 +30,7 @@ export declare const AllSettingDefault: {
     dummy: number;
     deviceAndVaultName: string;
     liveSync: boolean;
+    batchSaveInLiveSync?: boolean;
     syncOnSave: boolean;
     syncOnStart: boolean;
     syncOnFileOpen: boolean;

package/dist/common/settingConstants.js

@@ -144,6 +144,10 @@ const SettingInformation = {
     name: "Batch database update",
     desc: "Reducing the frequency with which on-disk changes are reflected into the DB"
   },
+  batchSaveInLiveSync: {
+    name: "Batch database updates in LiveSync mode",
+    desc: "Wait for a bounded local quiet period before processing file updates in LiveSync mode, reducing intermediate database updates while delaying their reflection to remote devices."
+  },
   readChunksOnline: {
     name: "Fetch chunks on demand",
     desc: "(ex. Read chunks online) If this option is enabled, LiveSync reads chunks online directly instead of replicating them locally. Increasing Custom chunk size is recommended."
@@ -313,11 +317,11 @@ const SettingInformation = {
   },
   batchSaveMinimumDelay: {
     name: "Minimum delay for batch database updating",
-    desc: "Seconds. Saving to the local database will be delayed until this value after we stop typing or saving."
+    desc: "Seconds. The quiet period after the latest pending update before local database processing becomes due."
   },
   batchSaveMaximumDelay: {
     name: "Maximum delay for batch database updating",
-    desc: "Saving will be performed forcefully after this number of seconds."
+    desc: "Seconds. The maximum intentional wait from the first pending update before local database processing becomes due. This does not guarantee when database processing, network delivery, or reflection to another device will complete."
   },
   notifyThresholdOfRemoteStorageSize: {
     name: "Notify when the estimated remote storage size exceeds on start up",

package/dist/interfaces/FileHandler.d.ts

@@ -1,5 +1,9 @@
 import type { FilePath, FilePathWithPrefix, MetaEntry } from "../common/models/db.type.js";
 import type { UXFileInfo, UXFileInfoStub, UXInternalFileInfoStub } from "../common/models/fileaccess.type.js";
+export interface StoreFileOptions {
+    /** Recheck storage and provenance, with bounded retries for recovery scans. */
+    revalidateStorage?: boolean;
+}
 export interface IFileHandler {
     readFileFromStub(file: UXFileInfoStub | UXFileInfo): Promise<UXFileInfo>;
     /**
@@ -8,7 +12,7 @@ export interface IFileHandler {
      * operation never stores a document revision or writes to storage.
      */
     tryRecordUntrackedFileRevision(info: UXFileInfoStub | UXFileInfo, expectedRevision: string): Promise<boolean>;
-    storeFileToDB(info: UXFileInfoStub | UXFileInfo | UXInternalFileInfoStub | FilePathWithPrefix, force?: boolean, onlyChunks?: boolean): Promise<boolean>;
+    storeFileToDB(info: UXFileInfoStub | UXFileInfo | UXInternalFileInfoStub | FilePathWithPrefix, force?: boolean, onlyChunks?: boolean, options?: StoreFileOptions): Promise<boolean>;
     /**
      * Store the current storage content as a child of an exact live database revision.
      *

package/dist/interfaces/StorageEventManager.d.ts

@@ -13,4 +13,9 @@ export declare abstract class StorageEventManager {
     abstract isWaiting(filename: FilePath): boolean;
     abstract waitForIdle(): Promise<void>;
     abstract restoreState(): Promise<void>;
+    /**
+     * Complete accepted work before its storage closes. Custom hosts must stop
+     * their watcher admission before invoking this default implementation.
+     */
+    stopWatching?(): Promise<void>;
 }

package/dist/interfaces/StorageEventManager.js

@@ -1,4 +1,11 @@
 class StorageEventManager {
+  /**
+   * Complete accepted work before its storage closes. Custom hosts must stop
+   * their watcher admission before invoking this default implementation.
+   */
+  stopWatching() {
+    return this.waitForIdle();
+  }
 }
 export {
   StorageEventManager

package/dist/managers/EntryManager/EntryManagerImpls.js

@@ -206,7 +206,8 @@ async function putDBEntryInternal(host, managers, note, onlyChunks, revisionTarg
 }
 function isTargetFile(host, filenameSrc) {
   const settings = host.services.setting.currentSettings();
-  const file = filenameSrc.startsWith(ICHeader) ? filenameSrc.substring(ICHeader.length) : filenameSrc;
+  const isInternalFile = filenameSrc.startsWith(ICHeader);
+  const file = isInternalFile ? filenameSrc.substring(ICHeader.length) : filenameSrc;
   if (file.startsWith(ICXHeader)) return true;
   if (file.startsWith(PSCHeader)) return true;
   if (file.startsWith(IDPrefixes.Chunk) || file.startsWith(IDPrefixes.Obfuscated)) {
@@ -217,7 +218,7 @@ function isTargetFile(host, filenameSrc) {
       return false;
     }
   }
-  if (settings.syncOnlyRegEx) {
+  if (!isInternalFile && settings.syncOnlyRegEx) {
     const syncOnly = getFileRegExp(settings, "syncOnlyRegEx");
     if (syncOnly.length > 0 && !syncOnly.some((e) => e.test(file))) return false;
   }

package/dist/managers/StorageEventManager.d.ts

@@ -71,26 +71,35 @@ export declare abstract class StorageEventManagerBase<TAdapter extends IStorageE
      * Restore and complete the previous storage-event snapshot when it exists.
      */
     restoreState(): Promise<void>;
+    private acceptingEvents;
+    private admissions;
     appendQueue(params: FileEvent[], ctx?: unknown): Promise<void>;
+    private appendQueueInternal;
     protected bufferedQueuedItems: (FileEventItem | FileEventItemSentinel)[];
+    private pendingSnapshot;
+    private operations;
+    private latestByPath;
+    private nextSequence;
+    private snapshotTail;
+    private dispatching;
+    private retainEvent;
+    private reportOperationFailure;
+    private failOperation;
     enqueue(newItem: FileEventItem): void;
-    /**
-     * Immediately take snapshot.
-     */
     private _triggerTakeSnapshot;
-    /**
-     * Trigger taking snapshot after throttled period.
-     */
     triggerTakeSnapshot: import("octagonal-wheels/function").ThrottledFunction<() => void>;
     protected concurrentProcessing: import("octagonal-wheels/concurrency/semaphore_v2").SemaphoreObject;
     protected _waitingMap: Map<string, WaitInfo>;
-    private _waitForIdle;
+    private pendingOperations;
+    private releaseOperations;
+    private waitForOperations;
     /**
-     * Wait until all queued events are processed.
-     * Subsequent new events will not be waited, but new events will not be added.
-     * @returns
+     * Complete the finite set of operations accepted before this call.
+     * Later edits cannot replace or extend that set while it is being flushed.
      */
     waitForIdle(): Promise<void>;
+    /** Stop watcher admission before draining or preserving accepted work. */
+    stopWatching(): Promise<void>;
     /**
      * Proceed waiting for the given key immediately.
      */