@vrtmrz/livesync-commonlib 0.2.2 → 0.2.3

package/docs/conflict-resolution.md

@@ -72,6 +72,36 @@ Each duplicate collapse, conservative merge, or host-directed manual choice is c
 
 A host must not apply a dialogue result after either compared revision has ceased to be the current pair. It should discard that stale result, refresh its warning or dialogue state, and queue the path again when conflicts remain.
 
+## Scheduling conflict checks
+
+The unreleased `@vrtmrz/livesync-commonlib/conflicts` entry exports
+`createConflictCheckQueue`. The host supplies a `process(path, scope)` callback
+and may observe pending plus active checks through `onProgress`. Concurrency
+defaults to ten and includes each item's deferred cleanup. The host continues
+to own active-file filtering, optional conflict handlers, revision decisions,
+and serialisation of shared user interactions.
+
+`enqueue(path)` accepts work synchronously. A duplicate pending path replaces
+its earlier entry and moves to the tail; an executing check is unchanged.
+An executing check may enqueue its path again, including while every execution
+slot is occupied. Pending paths have no fixed capacity, and there is no delay
+or batching policy.
+
+`waitForIdle()` waits until accepted work, new arrivals, requeued checks, and
+cleanup have finished. It leaves admission open for later checks and returns
+`true` on quiescence. `close()` stops admission and drains accepted work.
+`abort()` stops admission and further dispatch, waits for started work and
+cleanup, and returns a snapshot of the unstarted paths. It does not forcibly
+cancel a running callback; `waitForIdle()` returns `false` after abort.
+A processor must not await its own queue's completion, closure, or abort.
+
+An unhandled processing, cleanup, or progress-observer error stops dispatch.
+Completion methods reject only after started work and cleanup settle, while
+`pending` retains the unstarted paths for inspection. Catch and report an item
+error inside `process` when the host deliberately intends to continue with
+later items. The queue performs no implicit retry, logging, persistence, or
+recovery. Enqueueing after close, abort, or failure throws.
+
 ## File-reflection provenance
 
 The compatibility implementation accepts an injected, device-local `FileReflectionProvenance` capability owned by the database-to-storage composition rather than by a filesystem adapter. Maintained hosts persist:

package/docs/development.md

@@ -7,6 +7,7 @@ This document is for Commonlib developers. Package consumers should begin with t
 The source tree is larger than the supported package surface. Consumers may import only paths in the generated package export map:
 
 - `src/index.ts`, `src/context.ts`, `src/settings.ts`, `src/remoteConfigurations.ts`, `src/p2p/index.ts`, `src/platform/browser/index.ts`, and `src/platform/node/index.ts` define the focused entries;
+- `src/conflicts.ts` defines the host-owned conflict-check queue contract; `src/concurrency/keyedPendingWork.ts` remains package-private;
 - `src/replication/index.ts` defines the focused provider-capability and interaction contract for hosts which compose replication;
 - `src/diagnostics/index.ts` defines read-only Usage and integrity inspection, report projection, and formatting; hosts own the run dialogue and output destination;
 - `src/rpc/index.ts` defines a transitional entry for the existing LiveSync P2P composition, not a stable Commonlib 1.0 contract;
@@ -37,6 +38,10 @@ Commonlib uses four related forms of composition. Choose between them by ownersh
 - A **ServiceModule** is a long-lived stateful or resource-owning object constructed by the host and shared through the typed `ServiceModules` record. Use one when several consumers need the same operational capability or lifecycle, such as storage access, file handling, or database rebuilding. State alone does not make a ServiceModule necessary.
 - An **AbstractModule** is the legacy application module layer. Existing modules may continue to own application behaviour, but new composition should not acquire the broad core merely to gain lifecycle access or shared dependencies.
 
+`NecessaryServices<T, U, THub>` selects dependencies from a chosen Service Hub source, defaulting to `ServiceHub`, and retains `context` only when that source exposes it. Declare additional collaborators in the feature's own dependency type. `createServiceFeature()` preserves the supplied function's complete signature and result, but does not infer dependency keys from its body; annotate the host parameter when a narrow dependency contract is intended. Unannotated legacy callbacks retain the default `ServiceHub` contract for compatibility.
+
+Keep operation host types focused on the dependencies the operation uses, and let the composer add the Services required for logging, lifecycle access, or handler registration. Where an exported compatibility host must remain broad, use narrower private host types for the implementation. The examples in [Service feature composition](service-feature-composition.md) show these separate boundaries.
+
 When a feature needs state, separate the component which owns that state, its transitions, and its invariants from the code which connects it to application lifecycle events and downstream effects. Give the stateful component narrow collaborators or callbacks rather than the complete Service Hub or application core. Keep application-level handler registration and host-specific presentation in the surrounding serviceFeature. A handler or effect which is part of the state contract, such as querying unresolved errors or reporting their first occurrence, may remain inside the stateful component when its input and output ports are explicit and bounded.
 
 Settings storage follows the same ownership boundary. Each host selects one exact-key asynchronous `ValueStore & ValueDeleter` at its composition root and supplies it as the setting service's required `deviceValues` dependency. `setting.deviceValues` is that root; `setting.config` wraps it with the existing Vault and database-suffix scope, and the Service Hub `config` property aliases the same view. Commonlib does not discover browser globals or provide a module-global fallback. Keep existing local keys on the exact-key root, preserve configuration key names, and await Value Store operations. See [Settings lifecycle](settings-lifecycle.md#host-storage-for-device-values-and-configuration) for the key mapping and host example.
@@ -149,6 +154,37 @@ Commonlib publishes the typed English messages which it owns and uses them when
 
 The [maintained-host examples and evidence](proven-in-use.md) are optional context, not a support entitlement or release or adoption gate. When that page is updated, distinguish current use, historical use, Commonlib-owned results, downstream tests, and real-runtime observations, and keep each claim within the evidence.
 
+### Testing an unpublished Octagonal Wheels dependency
+
+The current integration pins the published Octagonal Wheels 0.1.56 release and
+uses the ordinary package gate. The override below is for future unpublished
+dependency changes.
+
+Keep the repository dependency declaration and lockfile separate from a local
+candidate check. After building and packing Octagonal Wheels, install that
+exact tarball for source checks without saving it to either manifest:
+
+```bash
+npm ci
+npm install --no-save --ignore-scripts /path/to/octagonal-wheels-candidate.tgz
+npm run check:types
+npm test -- --maxWorkers=1 --fileParallelism=false
+npm run test:package -- --octagonal-wheels-tarball /path/to/octagonal-wheels-candidate.tgz
+```
+
+The package checker adds the selected tarball and an explicit npm override
+only to its disposable consumer fixture. It reports the tarball's SHA-256 and
+checks that Commonlib resolves that same installed package. The generated
+Commonlib package retains its original dependency declaration. The option
+does not publish a package or select a future release version.
+
+The Blob migration's source tests cover legacy construction and Commonlib's
+document interpretation. Its packed fixtures compile the old imports and
+exercise the generated runtime. A passing candidate check qualifies that
+combination of artefacts; before publication, update the declared dependency
+to a released version containing the new entry, regenerate the lockfile, and
+run the ordinary package gate without the candidate override.
+
 ## Integration tests
 
 The integration suite owns Commonlib's direct CouchDB and S3-compatible storage checks. Run it with managed, disposable CouchDB and RustFS containers:
@@ -200,6 +236,8 @@ The platform and RPC ownership decisions are accepted:
 
 The package build records each compatibility path explicitly. Do not add a wildcard export. A new compatibility path requires a real downstream import, a packed-consumer or downstream test, and a migration plan towards a focused public entry or the owning package.
 
+The existing `compat/services/lib` helpers `bindableFunction` and `lazyBindableFunction` return an `UnregisterFunction` from `setHandler()`. It removes only the assignment made by that registration while it remains current; a stale remover, including after an override with the same callback, and repeated removals are no-ops. Existing callers may ignore the return value, but implementations and test doubles of the handler interfaces must return a remover. Keep this contract within the existing compatibility boundary rather than presenting it as a general SDK pattern.
+
 After the reviewed Self-hosted LiveSync revision changes, inspect its current compatibility imports with:
 
 ```bash
@@ -211,3 +249,11 @@ The command recognises both the former `@lib/*` source aliases and current `@vrt
 The classification in `docs/migration/compatibility-classification.json` is accepted for LiveSync 1.0 planning. A destination still requires its own result and lifecycle contract before it becomes a stable public entry. Remove obsolete paths rather than documenting accidental layout as API.
 
 Release preparation and staged-publication checks are documented in [the maintainer runbook](releasing.md).
+
+
+The shared value extraction uses the declared Octagonal Wheels dependency. Its
+`utils.runtime-tools.unit.spec.ts` tests preserve the legacy adapter contracts;
+`runtime-tools-types.ts` and `runtime-tools-runtime.mjs` check the installed
+package's public duration and delimiter helpers; source tests cover the
+internal JSON copy adapter. When testing a future unpublished dependency, keep
+these checks tied to the same Octagonal Wheels tarball used by the downstream consumer.

package/docs/proven-in-use.md

@@ -6,6 +6,39 @@ The useful evidence is host- and contract-specific. Focused Commonlib tests esta
 
 The code paths below identify maintained Self-hosted LiveSync composition points as examples. The reviewed downstream revision and compatibility imports are recorded in [`migration/downstream-imports.json`](migration/downstream-imports.json), which is regenerated by the package-boundary tooling rather than copied into prose links. These snapshots may become historical as the maintained downstream changes; this page is optional context, not a support entitlement or release or adoption gate.
 
+## Blob construction and comparison: candidate integration
+
+The unreleased Blob extraction delegates construction to
+`octagonal-wheels/binary/blob`. Commonlib retains the old creation imports and
+wraps `toBlob` as `createBlob`, while document classification, binary decoding,
+and content-comparison policy remain in Commonlib. The legacy
+`isDocContentSame` delegates its sliced fallback to `isBlobContentEqual`,
+passing the existing Commonlib encoder as the equality predicate. Its native
+IndexedDB path remains in Commonlib.
+
+The [legacy result tests](../src/common/utils.blob.unit.spec.ts) establish the
+same behaviour before and after delegation: Blob identity and MIME, text
+parts and line endings, binary view bounds and snapshots, stored-document
+decoding, and representation-independent byte comparison. The
+[comparison contract tests](../src/common/utils.blob-comparison.unit.spec.ts)
+cover size and MIME handling, sequential bounded reads, early termination,
+IndexedDB availability timing, method and receiver selection, Buffer fallback,
+and unchanged failures. [Composition tests](../src/common/utils.blob-delegation.unit.spec.ts)
+spy on the real shared comparison to verify fallback delegation and its
+absence on the native path. The
+[packed type fixture](../_tools/fixtures/blob-compatibility-types.ts) and
+[runtime fixture](../_tools/fixtures/blob-compatibility-runtime.mjs) exercise
+the existing Commonlib imports after packaging.
+
+Earlier candidate checks explicitly installed the selected unpublished Octagonal
+Wheels tarball in the disposable consumer. The current unreleased Commonlib
+integration pins the published Octagonal Wheels 0.1.56 dependency and uses the
+ordinary package gate without a candidate override. Self-hosted LiveSync tests its hidden-file
+loading and revision handling through the legacy entry with matching
+candidate tarballs. Those consumer checks are distinct from Commonlib-owned
+compatibility contracts; real-Obsidian and mobile validation of this extraction
+remain pending.
+
 ## Obsidian plug-in
 
 The unreleased V3 Rabin–Karp correction uses proportional binary thresholds,
@@ -219,3 +252,33 @@ Use the named consumer paths as integration examples, while retaining the owners
 ## Scope and maintenance
 
 This optional page preserves examples, current integration evidence, and history. It does not define supported behaviour or create a release or adoption gate; package guarantees are described by the published contracts and release policy. When this page is updated, distinguish current use, historical use, Commonlib-owned tests, downstream tests, and real-runtime observations, and keep each claim within its evidence.
+
+
+## Shared value helpers: candidate integration
+
+The [runtime helper tests](../src/common/utils.runtime-tools.unit.spec.ts)
+characterise duration thresholds, delimiter empty parts, and JSON conversion
+before and after delegation. Commonlib owns the tagged list adapter and
+internal `asCopy<T>` signature. Replication services use that internal adapter
+to detach settings before an operation. The shared package owns the value
+operations. The packed [type fixture](../_tools/fixtures/runtime-tools-types.ts) and
+[runtime fixture](../_tools/fixtures/runtime-tools-runtime.mjs) exercise those
+public duration and delimiter compatibility entries. The original checks used an
+unpublished dependency candidate; the current integration pins the published
+Octagonal Wheels 0.1.56 release. Source tests cover the internal copy adapter.
+LiveSync continues to use the existing compatibility entry points, including
+duration labels in ConfigSync and tagged lists in settings. Source and packed
+checks do not establish real-Obsidian rendering or device behaviour.
+
+
+## Shared multi-key locking: candidate integration
+
+The unreleased candidate imports `withLocks` directly from
+`octagonal-wheels/concurrency/lock` for offline Metadata repair and file-event
+processing. Commonlib retains the `processFileEvent-` namespace, unique sorted
+document IDs, and conflict hooks deferred until every lock has been released.
+The [file-handler tests](../src/serviceModules/ServiceFileHandlerBase.unit.spec.ts)
+exercise a rename alongside Metadata repair, including independent keys,
+reversed and repeated input IDs, and callback failure. These are Commonlib-owned
+composition checks using the selected dependency; Octagonal Wheels owns the
+primitive's lock acquisition, result propagation, and release contracts.

package/docs/releasing.md

@@ -38,6 +38,8 @@ When a named host-specific risk is not established by the Commonlib owner checks
 
 The Commonlib 0.2 policy begins with 0.2.0 and does not retroactively change compatibility expectations for published 0.1.x versions. Within 0.2.x, preserve published APIs, types, behaviour, supported persisted data, and exported `compat/*` paths. Intentional breaking changes belong in 0.3.0. Consumers may declare a range such as `^0.2.0`; lockfiles and `npm ci` remain the reproducible install path.
 
+For 0.2.3, the documented exceptions are the `HandlerFunction.setHandler` and `LazyHandlerFunction.setHandler` return types changing from `void` to `UnregisterFunction`, and `timeDeltaToHumanReadable(Infinity)` returning `∞y` instead of `Infinityy`. The setter types now describe the existing runtime return. Custom implementations and test doubles whose setters return `void` must provide an unregister function; ordinary callers may continue to ignore the result. These are the specific 0.2.3 exceptions to the policy.
+
 ## Preparing a release
 
 Choose the version explicitly. For the 0.2 line, start at 0.2.0. A stable candidate can use its final version on the `next` dist-tag, then be checked by exact source revision and tarball SHA-256 before the same version is promoted to `latest`. No `-next.N` or `-rc.N` version is required; use a separate prerelease version only when it is useful for a distinct candidate. Package-proof versions are local artefacts and cannot be staged.

package/docs/service-feature-composition.md

@@ -1,7 +1,7 @@
 ---
-date: 2026-09-04
-commonlib-version: "0.1.21"
-self-hosted-livesync-version: "1.0.24"
+date: 2026-10-25
+commonlib-version: "0.2.0"
+self-hosted-livesync-version: "1.0.40"
 status: unreleased
 ---
 
@@ -24,7 +24,7 @@ The choice is primarily about dependency direction and ownership. Mutable state
 
 ## Declare dependencies at the boundary
 
-Use `NecessaryServices` to state the exact Services and ServiceModules which a feature consumes:
+Use `NecessaryServices` to state the exact Services and ServiceModules which a feature consumes. Its type parameters select service keys, module keys, and the Service Hub source; the source defaults to `ServiceHub`. The selected Services retain `context` when that source exposes it. The `NecessaryServicesInterfaces` alias continues to use `IServiceHub` without adding an implicit context to that interface contract.
 
 ```typescript
 type IndexFeatureHost = NecessaryServices<"appLifecycle" | "API", "storageAccess">;
@@ -41,6 +41,20 @@ export const useIndexFeature = createServiceFeature((host: IndexFeatureHost) =>
 });
 ```
 
+Select a more specific host when a feature needs an injectable handler type or host-extended context. Collaborators outside the Service Hub and ServiceModules, such as a borrowed logger, belong in the feature's own dependency type:
+
+```typescript
+type FeatureHost = NecessaryServices<
+    "appLifecycle" | "conflict",
+    never,
+    InjectableServiceHub
+> & {
+    readonly log: LogFunction;
+};
+```
+
+`createServiceFeature()` returns the supplied function unchanged. Its declared host type, optional or additional arguments, generic or overloaded signature, and result type, including a `Promise` or focused view, remain available to callers. Dependency keys are not inferred from the callback body. An unannotated legacy callback retains the full default `ServiceHub` contract for compatibility, so annotate the host parameter when a narrow contract is intended. Existing `createServiceFeature<T, U, Result>(...)` calls remain supported. The `serviceFeature<T, U, THub>().create(...)` builder also selects a source and preserves the supplied function type. Its existing `.create<Result>(...)` call shape and `withContext()` behaviour are unchanged.
+
 This signature is both documentation and a compile-time boundary. Adding an unrelated Service to the host object does not make it available to the feature. If the operation needs another collaborator, add it deliberately to the declared contract.
 
 A serviceFeature is a composition function, not a runtime registry entry. Call it from the host composition after its dependencies exist:
@@ -65,13 +79,17 @@ When an operation has meaningful sequencing or failure behaviour, keep it indepe
 `prepareDatabaseForUse.ts` follows this split. Its operation accepts explicit collaborators and returns the application result:
 
 ```typescript
-type PrepareDatabaseHost = NecessaryServices<
-    "appLifecycle" | "setting" | "vault" | "path" | "database" | "databaseEvents" | "fileProcessing" | "replicator",
+type PrepareDatabaseOperationHost = NecessaryServices<
+    "appLifecycle" | "vault" | "database" | "databaseEvents" | "fileProcessing" | "replicator",
+    never
+>;
+type PrepareDatabaseFeatureHost = NecessaryServices<
+    "API" | "appLifecycle" | "vault" | "database" | "databaseEvents" | "fileProcessing" | "replicator",
     never
 >;
 
 export async function prepareDatabaseForUse(
-    host: PrepareDatabaseHost,
+    host: PrepareDatabaseOperationHost,
     log: LogFunction,
     errorManager: UnresolvedErrorManager,
     showingNotice = false,
@@ -83,10 +101,10 @@ export async function prepareDatabaseForUse(
 }
 ```
 
-The corresponding composition constructs the owned error manager and registers one adapter function:
+The operation does not need `setting` or `path`. The corresponding composition adds `API` to create the instance logger, constructs the owned error manager, and registers one adapter function:
 
 ```typescript
-export function usePrepareDatabaseForUse(host: PrepareDatabaseHost): void {
+export function usePrepareDatabaseForUse(host: PrepareDatabaseFeatureHost): void {
     const log = createInstanceLogFunction("SF:prepareDatabaseForUse", host.services.API);
     const errorManager = new UnresolvedErrorManager(host.services.appLifecycle, host.services.context.events);
 
@@ -107,6 +125,35 @@ export function usePrepareDatabaseForUse(host: PrepareDatabaseHost): void {
 
 Test the operation's sequencing and failure short-circuiting separately from the handler registration. This keeps a lifecycle rename from forcing every domain test through an application-shaped fixture.
 
+The offline scanner follows the same split. A full-scan operation uses only the file and database dependencies, while the composer adds `API` for its logger and `appLifecycle` for its error manager and handler registration:
+
+```typescript
+type FullScanHost = NecessaryServices<
+    "setting" | "vault" | "path" | "database" | "keyValueDB",
+    "storageAccess" | "fileHandler"
+>;
+
+type OfflineScannerFeatureHost = NecessaryServices<
+    "API" | "appLifecycle" | "setting" | "vault" | "path" | "database" | "keyValueDB",
+    "storageAccess" | "fileHandler"
+>;
+```
+
+`performFullScan` uses the full-scan host, and its scan operations declare their own narrower service sets; none requires `fileProcessing`. `useOfflineScanner` binds the `vault.scanVault` handler with the composer host. The scanner does not require `databaseEvents` or `replicator`.
+
+### Separate remote-configuration operation and composition hosts
+
+`RemoteConfigHost` remains the broad exported compatibility type for existing callers. The implementation uses private host types so each operation or composer declares only its required Services:
+
+| Implementation boundary | Private host type | Required Services |
+| --- | --- | --- |
+| Remote configuration migration operation | `RemoteConfigMigrationHost` | `setting`, `API` |
+| Migration feature composer | `RemoteConfigMigrationFeatureHost` | `setting`, `API`, `appLifecycle` |
+| Switch-connection command | `RemoteConfigSwitchHost` | `setting`, `UI`, `control`, `API` |
+| Replication command and feature composer | `RemoteConfigReplicationHost` | `setting`, `UI`, `replication`, `control`, `API` |
+
+Keep the broad export for compatibility and use the focused private types inside the implementation.
+
 Database preparation and full scanning remain strict by default. A host may set `continueOnFileFailure` only when its ordinary start-up policy deliberately permits readiness after individual file-pair failures. In that case, the operation returns `completed-with-file-failures` after all later initialisation steps succeed; it does not collapse the result into `true`. That option does not admit a failed scan precondition or a later initialisation step, and explicit recovery workflows retain the default.
 
 The `scanVault` and `initialiseDatabase` services use a failure-veto result aggregator for this contract. It preserves the first non-boolean continuation result but still invokes later handlers, so a later `false` result or exception rejects the operation. `firstResult` is not suitable here because it would return the partial result before those handlers can veto it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -42,6 +42,11 @@
       "import": "./dist/platform/browser/index.js",
       "default": "./dist/platform/browser/index.js"
     },
+    "./conflicts": {
+      "types": "./dist/conflicts.d.ts",
+      "import": "./dist/conflicts.js",
+      "default": "./dist/conflicts.js"
+    },
     "./context": {
       "types": "./dist/context.d.ts",
       "import": "./dist/context.js",
@@ -640,6 +645,9 @@
       "browser": [
         "dist/platform/browser/index.d.ts"
       ],
+      "conflicts": [
+        "dist/conflicts.d.ts"
+      ],
       "context": [
         "dist/context.d.ts"
       ],
@@ -1012,7 +1020,7 @@
     "idb": "^8.0.3",
     "markdown-it": "^14.3.3",
     "minimatch": "^10.2.6",
-    "octagonal-wheels": "^0.1.55",
+    "octagonal-wheels": "0.1.56",
     "pouchdb-adapter-http": "^9.0.0",
     "pouchdb-adapter-idb": "^9.0.0",
     "pouchdb-adapter-indexeddb": "^9.0.0",