@vrtmrz/livesync-commonlib 0.2.1 → 0.2.3

package/README.md

@@ -32,6 +32,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 +48,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.
+The unreleased Self-hosted LiveSync integration removes its purge-based cleanup
+recovery and uses the standard locked-remote recovery dialogue. 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 +66,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
+
+The unreleased Blob extraction 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. This unreleased Commonlib integration now 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:
@@ -276,3 +313,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.
+
+The unreleased extraction 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.
+
+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/processSetting.d.ts

@@ -62,6 +62,7 @@ export declare function decodeSettingsFromSetupURI(uri: string, passphrase: stri
     batchSaveInLiveSync?: boolean;
     syncOnSave: boolean;
     syncOnStart: boolean;
+    strictContentCheckOnStartup?: boolean;
     syncOnFileOpen: boolean;
     syncOnEditorSave: boolean;
     keepReplicationActiveInBackground: boolean;

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 {

package/dist/ContentSplitter/ContentSplitterV2.js

@@ -8,25 +8,15 @@ class ContentSplitterV2 extends ContentSplitterBase {
     return settings.chunkSplitterVersion === ChunkAlgorithms.V2 || settings.chunkSplitterVersion === ChunkAlgorithms.V2Segmenter;
   }
   async processSplit(options) {
-    if (options.useWorker) {
-      return (await splitPieces2WorkerV2(
-        options.blob,
-        options.pieceSize,
-        options.plainSplit,
-        options.minimumChunkSize,
-        options.path,
-        options.useSegmenter
-      ))();
-    } else {
-      return (await splitPieces2V2(
-        options.blob,
-        options.pieceSize,
-        options.plainSplit,
-        options.minimumChunkSize,
-        options.path,
-        options.useSegmenter
-      ))();
-    }
+    const split = options.useWorker ? splitPieces2WorkerV2 : splitPieces2V2;
+    return (await split(
+      options.blob,
+      options.pieceSize,
+      options.plainSplit,
+      options.minimumChunkSize,
+      options.path,
+      options.useSegmenter
+    ))();
   }
 }
 export {

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

@@ -43,6 +43,7 @@ const SETTINGS_SCHEMA_DEFAULTS = {
   batchSaveInLiveSync: false,
   syncOnSave: false,
   syncOnStart: false,
+  strictContentCheckOnStartup: false,
   savingDelay: 200,
   lessInformationInLog: false,
   gcDelay: 300,

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

@@ -51,6 +51,8 @@ const KeyIndexOfSettings = {
   liveSync: 49,
   syncOnSave: 50,
   syncOnStart: 51,
+  strictContentCheckOnStartup: -1,
+  // Installation-local preference; do not encode into the QR Code.
   syncOnFileOpen: 52,
   syncOnEditorSave: 53,
   keepReplicationActiveInBackground: -1,

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

@@ -65,6 +65,10 @@ export declare const SETTINGS_PROPERTY_POLICY: {
         readonly markdown: "include";
         readonly persistence: "include";
     };
+    readonly strictContentCheckOnStartup: {
+        readonly markdown: "omit";
+        readonly persistence: "include";
+    };
     readonly syncOnFileOpen: {
         readonly markdown: "include";
         readonly persistence: "include";

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

@@ -17,6 +17,7 @@ const SETTINGS_PROPERTY_POLICY = {
   batchSaveInLiveSync: SettingPolicies.Default,
   syncOnSave: SettingPolicies.Default,
   syncOnStart: SettingPolicies.Default,
+  strictContentCheckOnStartup: SettingPolicies.LocalOnly,
   syncOnFileOpen: SettingPolicies.Default,
   syncOnEditorSave: SettingPolicies.Default,
   keepReplicationActiveInBackground: SettingPolicies.Default,

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

@@ -91,6 +91,10 @@ interface SyncMethodSettings {
      * automatically run sync on starting the plug-in.
      */
     syncOnStart: boolean;
+    /**
+     * Compare file contents during startup checks when modification time and size match.
+     */
+    strictContentCheckOnStartup?: boolean;
     /**
      * automatically run sync on opening a file.
      */

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

@@ -145,6 +145,7 @@ export declare const TweakValuesTemplate: {
     batchSaveInLiveSync?: boolean;
     syncOnSave?: boolean;
     syncOnStart?: boolean;
+    strictContentCheckOnStartup?: boolean;
     syncOnFileOpen?: boolean;
     syncOnEditorSave?: boolean;
     keepReplicationActiveInBackground?: boolean;

package/dist/common/settingConstants.d.ts

@@ -33,6 +33,7 @@ export declare const AllSettingDefault: {
     batchSaveInLiveSync?: boolean;
     syncOnSave: boolean;
     syncOnStart: boolean;
+    strictContentCheckOnStartup?: boolean;
     syncOnFileOpen: boolean;
     syncOnEditorSave: boolean;
     keepReplicationActiveInBackground: boolean;

package/dist/common/settingConstants.js

@@ -104,6 +104,10 @@ const SettingInformation = {
     name: "Sync on Startup",
     desc: "Automatically Sync all files when opening Obsidian."
   },
+  strictContentCheckOnStartup: {
+    name: "Strict content check on startup",
+    desc: "Compare file contents even when modification time and size match. This can slow startup in large vaults."
+  },
   syncAfterMerge: {
     name: "Sync after merging file",
     desc: "Sync automatically after merging files"

package/dist/common/utils.d.ts

@@ -3,6 +3,8 @@ import { replaceAll, replaceAllPairs } from "octagonal-wheels/string";
 export { replaceAll, replaceAllPairs };
 import { concatUInt8Array } from "octagonal-wheels/binary";
 export { concatUInt8Array };
+import { createBinaryBlob, createTextBlob } from "octagonal-wheels/binary/blob";
+export { createBinaryBlob, createTextBlob };
 import { delay, fireAndForget } from "octagonal-wheels/promises";
 export { delay, fireAndForget };
 import { arrayToChunkedArray, unique } from "octagonal-wheels/collection";
@@ -28,12 +30,40 @@ export declare function getDocData(doc: string | string[]): string;
 export declare function getDocDataAsArray(doc: string | string[]): string[];
 export declare function getDocDataAsArrayBuffer(doc: string | string[] | ArrayBuffer): Uint8Array<ArrayBuffer>;
 export declare function isTextBlob(blob: Blob): boolean;
-export declare function createTextBlob(data: string | string[]): Blob;
-export declare function createBinaryBlob(data: Uint8Array<ArrayBuffer> | ArrayBuffer): Blob;
+/**
+ * Normalises content to a Blob through the legacy Commonlib entry point.
+ *
+ * @param data - Text, ordered text parts, binary bytes, or an existing Blob.
+ * @returns The original Blob, or a new text or binary Blob for other inputs.
+ * @remarks
+ * This compatibility wrapper retains the `createBlob` name and delegates to
+ * `toBlob` from `octagonal-wheels/binary/blob`. Existing Blob instances retain
+ * their identity and MIME type. Text retains transparent line endings; binary
+ * views contribute only their visible bytes. Calls use the current realm's
+ * Blob constructor. Document classification and decoding remain in
+ * {@link readAsBlob}; importing this legacy module retains its existing
+ * environment initialisation.
+ */
 export declare function createBlob(data: string | string[] | Uint8Array<ArrayBuffer> | ArrayBuffer | Blob): Blob;
 export declare function isTextDocument(doc: LoadedEntry): boolean;
 export declare function readAsBlob(doc: LoadedEntry): Blob;
 export declare function readContent(doc: LoadedEntry): string | ArrayBuffer;
+/**
+ * Tests whether legacy document-content inputs represent equal bytes.
+ *
+ * @param docA - Text, ordered text parts, a Blob, or binary bytes.
+ * @param docB - The second content value in any supported representation.
+ * @returns Whether the normalised inputs contain equal bytes, ignoring MIME types.
+ * @remarks
+ * Inputs are normalised with {@link createBlob}. Different sizes return false
+ * without reading content. IndexedDB comparison availability is selected at
+ * module import; that path resolves the current method and receiver before
+ * reading both complete Blobs sequentially, including empty inputs.
+ * Otherwise, `isBlobContentEqual` from `octagonal-wheels/binary/blob` reads
+ * pairs of parts of at most 10,000 bytes, using Commonlib's Base64 encoder and
+ * its existing host Buffer fallback. Empty inputs on this path return true
+ * without reads. Read and comparison failures propagate unchanged.
+ */
 export declare function isDocContentSame(docA: string | string[] | Blob | ArrayBuffer, docB: string | string[] | Blob | ArrayBuffer): Promise<boolean>;
 export declare function isObfuscatedEntry(doc: DatabaseEntry): doc is AnyEntry;
 export declare function isEncryptedChunkEntry(doc: DatabaseEntry): doc is EntryLeaf;
@@ -66,7 +96,7 @@ export declare function runWithInterval<T>(key: string, interval: number, task:
  * @remarks This function is not designed to be concurrent.
  */
 export declare function runWithStartInterval<T>(key: string, interval: number, task: () => Promise<T>): Promise<T>;
-export declare const globalConcurrencyController: import("octagonal-wheels/concurrency/semaphore_v2").SemaphoreObject;
+export declare const globalConcurrencyController: import("octagonal-wheels/concurrency/semaphore").SemaphoreObject;
 export declare function determineTypeFromBlob(data: Blob): "newnote" | "plain";
 /**
  * Whether remediation mode is active.

package/dist/common/utils.js

@@ -9,8 +9,10 @@ import {
 } from "./types.js";
 import { normaliseP2PConnectionPath, normaliseP2PMaxWirePayloadBytes } from "./models/setting.p2p.js";
 import { isErrorOfMissingDoc } from "../pouchdb/utils_couchdb.js";
-import { replaceAll, replaceAllPairs } from "octagonal-wheels/string";
+import { joinDelimitedList, replaceAll, replaceAllPairs, splitDelimitedList } from "octagonal-wheels/string";
+import { formatDuration } from "octagonal-wheels/notation/duration";
 import { concatUInt8Array } from "octagonal-wheels/binary";
+import { createBinaryBlob, createTextBlob, isBlobContentEqual, toBlob } from "octagonal-wheels/binary/blob";
 import { delay, fireAndForget } from "octagonal-wheels/promises";
 import { arrayToChunkedArray, unique } from "octagonal-wheels/collection";
 import { extractObject, isObjectDifferent } from "octagonal-wheels/object";
@@ -55,17 +57,8 @@ function getDocDataAsArrayBuffer(doc) {
 function isTextBlob(blob) {
   return blob.type === "text/plain";
 }
-function createTextBlob(data) {
-  const d = Array.isArray(data) ? data : [data];
-  return new Blob(d, { endings: "transparent", type: "text/plain" });
-}
-function createBinaryBlob(data) {
-  return new Blob([data], { endings: "transparent", type: "application/octet-stream" });
-}
 function createBlob(data) {
-  if (data instanceof Blob) return data;
-  if (data instanceof Uint8Array || data instanceof ArrayBuffer) return createBinaryBlob(data);
-  return createTextBlob(data);
+  return toBlob(data);
 }
 function isTextDocument(doc) {
   if (doc.type == "plain") return true;
@@ -88,23 +81,17 @@ function readContent(doc) {
   }
 }
 const isIndexDBCmpExist = typeof compatGlobal?.indexedDB?.cmp !== "undefined";
+async function isArrayBufferContentEqual(left, right) {
+  return await arrayBufferToBase64Single(left) === await arrayBufferToBase64Single(right);
+}
 async function isDocContentSame(docA, docB) {
   const blob1 = createBlob(docA);
   const blob2 = createBlob(docB);
-  if (blob1.size != blob2.size) return false;
   if (isIndexDBCmpExist) {
+    if (blob1.size != blob2.size) return false;
     return compatGlobal.indexedDB.cmp(await blob1.arrayBuffer(), await blob2.arrayBuffer()) === 0;
   }
-  const checkQuantum = 1e4;
-  const length = blob1.size;
-  let i = 0;
-  while (i < length) {
-    const ab1 = await blob1.slice(i, i + checkQuantum).arrayBuffer();
-    const ab2 = await blob2.slice(i, i + checkQuantum).arrayBuffer();
-    i += checkQuantum;
-    if (await arrayBufferToBase64Single(ab1) != await arrayBufferToBase64Single(ab2)) return false;
-  }
-  return true;
+  return isBlobContentEqual(blob1, blob2, isArrayBufferContentEqual);
 }
 function isObfuscatedEntry(doc) {
   if (doc._id.startsWith(PREFIX_OBFUSCATED)) {
@@ -267,24 +254,7 @@ function escapeMarkdownValue(value) {
   }
 }
 function timeDeltaToHumanReadable(delta) {
-  const sec = delta / 1e3;
-  if (sec < 60) {
-    return `${sec.toFixed(2)}s`;
-  }
-  const min = sec / 60;
-  if (min < 60) {
-    return `${min.toFixed(2)}m`;
-  }
-  const hour = min / 60;
-  if (hour < 24) {
-    return `${hour.toFixed(2)}h`;
-  }
-  const day = hour / 24;
-  if (day < 365) {
-    return `${day.toFixed(2)}d`;
-  }
-  const year = day / 365;
-  return `${year.toFixed(2)}y`;
+  return formatDuration(delta);
 }
 async function wrapException(func) {
   try {
@@ -378,12 +348,10 @@ function parseCustomRegExpList(list, flags, delimiter) {
   return items.map((e) => new CustomRegExp(e, flags));
 }
 function constructCustomRegExpList(items, delimiter) {
-  return items.map((e) => `${e}`).join(`${delimiter}`);
+  return joinDelimitedList(items.map((e) => `${e}`), `${delimiter}`);
 }
 function splitCustomRegExpList(list, delimiter) {
-  const d = delimiter;
-  const source = `${list ?? ""}`;
-  return source.split(d).filter((e) => e);
+  return splitDelimitedList(`${list ?? ""}`, delimiter);
 }
 class CustomRegExp {
   regexp;

package/dist/common/utils.object.js

@@ -1,6 +1,7 @@
 import { LiveSyncError } from "./LSError.js";
+import { cloneViaJSON } from "octagonal-wheels/encoding/json";
 function asCopy(obj) {
-  return JSON.parse(JSON.stringify(obj));
+  return cloneViaJSON(obj);
 }
 function ensureError(error) {
   if (error instanceof Error) {

package/dist/concurrency/keyedPendingWork.d.ts

@@ -0,0 +1,13 @@
+/** An unclaimed value; its identity distinguishes replacements for the same key. */
+export interface PendingWork<K, T> {
+    readonly key: K;
+    readonly value: T;
+}
+/** Keep only the latest unclaimed value for each key, in replacement order. */
+export declare function createKeyedPendingWork<K, T>(keyOf: (value: T) => K): {
+    add(value: T): void;
+    peek(): PendingWork<K, T> | undefined;
+    claim(entry: PendingWork<K, T>): boolean;
+    values(): readonly T[];
+    readonly size: number;
+};

package/dist/concurrency/keyedPendingWork.js

@@ -0,0 +1,27 @@
+function createKeyedPendingWork(keyOf) {
+  const pending = /* @__PURE__ */ new Map();
+  return {
+    add(value) {
+      const key = keyOf(value);
+      pending.delete(key);
+      pending.set(key, { key, value });
+    },
+    peek() {
+      return pending.values().next().value;
+    },
+    claim(entry) {
+      if (pending.get(entry.key) !== entry) return false;
+      pending.delete(entry.key);
+      return true;
+    },
+    values() {
+      return Array.from(pending.values(), (entry) => entry.value);
+    },
+    get size() {
+      return pending.size;
+    }
+  };
+}
+export {
+  createKeyedPendingWork
+};

package/dist/conflicts/conflictCheckQueue.d.ts

@@ -0,0 +1,45 @@
+import type { FilePathWithPrefix } from "../common/types.js";
+import { type Awaitable, type Scope } from "octagonal-wheels/resource/scope";
+/** Host-owned conflict processing and observation for one queue. */
+export interface ConflictCheckQueueOptions {
+    /** Process one admitted path. Deferred cleanup occupies the same execution slot. */
+    readonly process: (path: FilePathWithPrefix, scope: Scope<undefined>) => Awaitable<unknown>;
+    /** Positive safe integer; defaults to ten. Pending paths have no fixed capacity. */
+    readonly concurrency?: number;
+    /** Observe pending plus active checks. A thrown error stops the queue after active work settles. */
+    readonly onProgress?: (remaining: number) => void;
+}
+/** One queue owns pending checks; the host owns conflict decisions and recovery policy. */
+export interface ConflictCheckQueue {
+    /** Accept a path without waiting for its check; a pending duplicate moves to the tail. */
+    enqueue(path: FilePathWithPrefix): void;
+    /** Wait for quiescence, including requeues and cleanup; false means the queue was aborted. Do not await from its processor. */
+    waitForIdle(): Promise<boolean>;
+    /** Stop admission and drain accepted work. A processor must not await its own queue's closure. */
+    close(): Promise<boolean>;
+    /** Stop admission and dispatch, join active cleanup, and return the retained, unstarted paths. */
+    abort(): Promise<readonly FilePathWithPrefix[]>;
+    /** Snapshot of unstarted paths; retained after abort or failure for the host to inspect. */
+    readonly pending: readonly FilePathWithPrefix[];
+    /** Pending and active checks, including item cleanup. */
+    readonly remaining: number;
+}
+/**
+ * Compose keyed pending checks with bounded scoped execution.
+ *
+ * Input is accepted synchronously without a fixed pending-count limit. Each
+ * execution consumes a synchronous iterable which ends when no pending path
+ * remains; later arrivals join it or start the next execution. An empty queue has no input read,
+ * timer, or worker waiting in the background.
+ *
+ * Replacement affects unclaimed entries only. A running check may enqueue its
+ * own path without waiting for an execution slot. It is not cancelled or replaced
+ * by that later input. The host remains responsible for serialising any shared
+ * resource or interaction inside the processor.
+ *
+ * Unhandled processing, cleanup, or observation errors stop further dispatch.
+ * Started work and cleanup settle before completion waiters reject; unstarted
+ * paths remain inspectable. Catch an item error inside process when the host's
+ * explicit policy is to log and continue. There is no implicit retry or logging.
+ */
+export declare function createConflictCheckQueue(options: ConflictCheckQueueOptions): ConflictCheckQueue;

package/dist/conflicts/conflictCheckQueue.js

@@ -0,0 +1,108 @@
+import { createKeyedPendingWork } from "../concurrency/keyedPendingWork.js";
+import { createNotifier } from "octagonal-wheels/concurrency/notifier";
+import { forEachInScope } from "octagonal-wheels/concurrency/scoped.iteration";
+import { withScope } from "octagonal-wheels/resource/scope";
+function createConflictCheckQueue(options) {
+  const concurrency = options.concurrency ?? 10;
+  if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+    throw new RangeError("Conflict check concurrency must be a positive safe integer.");
+  }
+  const pending = createKeyedPendingWork((path) => path);
+  const changed = createNotifier();
+  const failures = [];
+  let accepting = true;
+  let aborted = false;
+  let stoppingAfterFailure = false;
+  let active = 0;
+  let running;
+  const remaining = () => pending.size + active;
+  const canDispatch = () => !aborted && !stoppingAfterFailure && failures.length === 0;
+  const recordFailure = (error) => {
+    accepting = false;
+    stoppingAfterFailure = true;
+    failures.push(error);
+    changed.notify();
+  };
+  const reportProgress = () => {
+    if (failures.length === 0) {
+      try {
+        options.onProgress?.(remaining());
+      } catch (error) {
+        recordFailure(error);
+      }
+    }
+    changed.notify();
+  };
+  function* availableWork() {
+    while (canDispatch()) {
+      const entry = pending.peek();
+      if (!entry) return;
+      yield entry;
+    }
+  }
+  function schedule() {
+    if (running || !canDispatch() || pending.size === 0) return;
+    running = Promise.resolve().then(
+      () => withScope(
+        void 0,
+        (parent) => forEachInScope(parent, availableWork(), { concurrency }, async (entry, child) => {
+          if (!canDispatch() || !pending.claim(entry)) return;
+          active++;
+          child.defer(() => {
+            active--;
+            reportProgress();
+          });
+          reportProgress();
+          try {
+            await options.process(entry.value, child);
+          } catch (error) {
+            accepting = false;
+            stoppingAfterFailure = true;
+            throw error;
+          }
+        })
+      )
+    ).then(() => void 0, recordFailure).finally(() => {
+      running = void 0;
+      schedule();
+      changed.notify();
+    });
+  }
+  async function waitForIdle() {
+    schedule();
+    while (running) await changed.wait();
+    if (failures.length === 1) throw failures[0];
+    if (failures.length > 1) throw new AggregateError(failures, "Conflict checks failed.");
+    return !aborted;
+  }
+  return {
+    enqueue(path) {
+      if (!accepting) throw new Error("The conflict check queue is closed.");
+      pending.add(path);
+      reportProgress();
+      schedule();
+    },
+    waitForIdle,
+    close() {
+      accepting = false;
+      schedule();
+      return waitForIdle();
+    },
+    async abort() {
+      accepting = false;
+      aborted = true;
+      changed.notify();
+      await waitForIdle();
+      return pending.values();
+    },
+    get pending() {
+      return pending.values();
+    },
+    get remaining() {
+      return remaining();
+    }
+  };
+}
+export {
+  createConflictCheckQueue
+};

package/dist/conflicts.d.ts

@@ -0,0 +1,3 @@
+export { createConflictCheckQueue } from "./conflicts/conflictCheckQueue.js";
+export type { ConflictCheckQueue, ConflictCheckQueueOptions } from "./conflicts/conflictCheckQueue.js";
+export type { FilePathWithPrefix } from "./common/types.js";

package/dist/conflicts.js

@@ -0,0 +1,4 @@
+import { createConflictCheckQueue } from "./conflicts/conflictCheckQueue.js";
+export {
+  createConflictCheckQueue
+};