@vrtmrz/livesync-commonlib 0.2.1 → 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/offline-scanner.md

@@ -1,6 +1,6 @@
 ---
-date: 2026-10-25
-commonlib-version: "0.2.0"
+date: 2026-10-26
+commonlib-version: "0.2.1"
 self-hosted-livesync-version: "1.0.40"
 status: unreleased
 ---
@@ -29,6 +29,14 @@ The tables below cover only paths which remain after identity validation, the ho
 6. after the first permitted invocation reaches its aggregate-result boundary, record `initialized = true`; and
 7. return the aggregate pair result under the caller's selected handling of file failures.
 
+### Startup content checking
+
+`VaultScanOptions.strictContentCheck` is optional. `initialiseDatabase` accepts `VaultScanOptions` as its optional fifth argument, and `scanVault` accepts it as its optional fourth argument and forwards it. `performFullScan` exposes the same option through `FullScanOptions`. Omitting the option, or setting it to `true`, retains strict content comparison. Only an explicit `false` permits the scanner to pass the `canSkipUnchangedFile` hint to the file handler. Commonlib does not read a host setting or global storage; a host may select this option from a per-installation startup preference.
+
+The hint is considered only when the normal freshness comparison reaches `EVEN`, replacing the additional body comparison at that point. It never bypasses `BASE_IS_NEW` or `TARGET_IS_NEW`; those branches retain their timestamp-directed reflection and last-seen bookkeeping. Inside `EVEN`, the hint is allowed only for a tracked file whose raw modification time exactly equals the recorded provenance mtime (not merely a value in the same platform comparison bucket), whose byte size matches the recorded value, whose tracked revision is the current live database revision, and which has no live conflicts or related queued, running, or failed file work. If tracking evidence is missing, or the host cannot establish pending-work state, the existing strict byte-comparison path remains. When the hint is accepted, the pair result is `SKIPPED`; it does not compare or claim equal bytes, write provenance, or introduce Commonlib persistent state. Incoming content, conflict handling, and logical-deletion protection retain their existing rules.
+
+A local edit which preserves the tracked modification time and byte size may be missed by a scan using explicit `false`. Existing same-stat edit checks exercise the omitted-option strict path.
+
 The `initialized` marker records that a full-scan invocation has reached its aggregate-result boundary and that later invocations may restore stored storage-event operations. It is not a successful-scan marker: the first invocation records it after an aggregate `false` result, `true`, or an accepted partial result. An exception before the aggregate result is produced does not reach that write.
 
 Storage-event restoration is a bounded start-up recovery step. Restored events bypass their former batch delay, but `restoreState()` waits for their actual handler outcomes and snapshot ordering before the file collections are compared. Saved events run first because a deletion or rename can carry operation intent which is no longer visible in the current storage listing. An individual restored operation failure remains in the pending snapshot and is logged; it does not prevent the scan from examining current state or independent paths. The following full scan then makes the final reconciliation decision.
@@ -140,7 +148,7 @@ Self-hosted LiveSync enables this policy only for ordinary Obsidian start-up, wh
 
 ## Files in the same timestamp bucket
 
-For a `both` pair which selects `NEWER_WINS` (`sync-newer`), equal raw modification times and distinct times within the platform tolerance do not establish that the storage file is unchanged. The scanner first asks the file handler to record provenance for the current database revision only when current storage and one unambiguous live revision have matching content. The handler checks the storage bytes and database revision under the document lock, then revalidates the storage snapshot, current revision, and absent provenance before writing the record. This check writes neither storage content nor a database revision. The existing selection, file-size, and conflict policies still apply, and the `DB_APPLY` action remains unchanged.
+For a `both` pair which selects `NEWER_WINS` (`sync-newer`), the normal freshness comparison can reach `EVEN` for equal raw modification times or distinct times within the platform tolerance; those timestamps alone do not establish that the storage file is unchanged. Under the omitted-option strict path, the scanner asks the file handler to record provenance for the current database revision only when current storage and one unambiguous live revision have matching content. The handler checks the storage bytes and database revision under the document lock, then revalidates the storage snapshot, current revision, and absent provenance before writing the record. This check writes neither storage content nor a database revision. With explicit `strictContentCheck: false`, the scanner may request `canSkipUnchangedFile` only in the `EVEN` branch, and only when the raw mtime exactly matches the recorded provenance mtime; a value merely in the same tolerance bucket does not qualify. The `BASE_IS_NEW` and `TARGET_IS_NEW` branches retain their existing timestamp-directed reflection and last-seen bookkeeping. The existing selection, file-size, and conflict policies still apply, and the `DB_APPLY` action remains unchanged.
 
 The result of `tryRecordUntrackedFileRevision()` is not an edit predicate. Its `false` can mean that provenance already exists, content differs, history conflicts, required content or provenance is unavailable, or state changed during verification. When it returns `false`, the scanner uses the ordinary, non-forced `storeFileToDB` path with bounded storage revalidation; it does not force the Vault file into the current database winner. The file handler retains a known branch when readable provenance identifies it, applies newer database state when the storage bytes match that recorded older revision, and saves a genuine edit on its recorded branch.
 
@@ -158,7 +166,7 @@ Focused two-pass coverage starts with a `DB_APPLY` reflection whose file handler
 
 Full-scan coverage also verifies that the strict default returns `false`, an ordinary-start-up scan which explicitly continues returns `completed-with-file-failures` while logging the affected path at verbose level, and a later clean scan returns `true`.
 
-The equal-time regression uses real in-memory PouchDB and the file handler. It checks missing and recorded provenance with unchanged files and genuine local edits at both identical raw timestamps and distinct raw timestamps within one comparison bucket. It verifies that edits are preserved during the scan, then advances the database and checks that an incoming revision retains the local branch. It also verifies that a matching saved hash remains useful after its database revision is pruned, while edited bytes with an unhashed pruned base and no matching live leaf are preserved independently. Focused scanner tests verify that a failed ordinary save returns a failed pair. Focused handler tests cover provenance read and write failures, unavailable recorded-base content, an existing conflict, and storage or database changes during verification.
+The equal-time regression uses real in-memory PouchDB and the file handler with `strictContentCheck` omitted, keeping its same-stat edit assertions on the strict default path. It checks missing and recorded provenance with unchanged files and genuine local edits at both identical raw timestamps and distinct raw timestamps within one comparison bucket. It verifies that edits are preserved during the scan, then advances the database and checks that an incoming revision retains the local branch. It also verifies that a matching saved hash remains useful after its database revision is pruned, while edited bytes with an unhashed pruned base and no matching live leaf are preserved independently. Focused scanner tests verify that a failed ordinary save returns a failed pair. Focused handler tests cover provenance read and write failures, unavailable recorded-base content, an existing conflict, and storage or database changes during verification.
 
 A second two-pass case starts with a `db-only` entry skipped by the size limit. It then removes that limit and verifies that the entry is reflected to storage rather than misclassified as an offline local deletion. Coverage for an existing storage file verifies that a failed `sync-newer` reflection retains the observed storage mtime, and full-scan coverage verifies that the aggregate failure reaches its caller after scanner initialisation completes.
 

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/docs/storage-events-and-reflection.md

@@ -1,6 +1,6 @@
 ---
-date: 2026-10-25
-commonlib-version: "0.2.0"
+date: 2026-10-26
+commonlib-version: "0.2.1"
 self-hosted-livesync-version: "1.0.40"
 status: unreleased
 ---
@@ -48,6 +48,10 @@ and unsynchronised storage content retain their existing reflection rules.
 The watcher guard does not intercept this path or general explicit database
 deletion operations.
 
+## Startup scans and pending operations
+
+The full scanner's optional `strictContentCheck: false` path is gated by the host's file-operation state. Any related queued, running, or failed operation blocks the `canSkipUnchangedFile` hint. The host must provide an available query before the scanner can establish that no related work exists; without that query or other required evidence, strict content comparison remains active. The hint is considered only after normal freshness comparison reaches `EVEN`, and requires the raw mtime to exactly match the recorded provenance value; a match within the platform comparison bucket is insufficient. `BASE_IS_NEW` and `TARGET_IS_NEW` retain their timestamp-directed reflection and last-seen bookkeeping. A pair returned as `SKIPPED` by this hint does not acknowledge or remove a saved event. Event work continues to follow the snapshot and handler-completion contract below. This option affects only the full-scan same-stat check; ordinary watcher `CREATE` and `CHANGED` handling, replicated writes, and logical-deletion protection retain their existing rules. See [Full offline scan](offline-scanner.md#startup-content-checking) for the full option and eligibility conditions.
+
 ## Pending operations and local completion
 
 Once admitted, a file operation remains pending while buffered, waiting for its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.2.1",
+  "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",