@vrtmrz/livesync-commonlib 0.2.2 → 0.3.0

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 `@vrtmrz/livesync-commonlib/conflicts` entry, published in Commonlib 0.2.3, 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.
@@ -106,6 +111,10 @@ The revision-tree safety rules are documented in [Conflict resolution and file p
 
 `LiveSyncReplicator.unit.spec.ts` owns the CouchDB remote-chunk batch contract: a mixed `_all_docs` result must return each available document even when another keyed row reports an error. `ChunkFetcher.unit.spec.ts` owns the consumer behaviour: it writes valid returned chunks and emits `missingChunkRemote` only for requested IDs which are absent from the returned set. Extend both sides when changing remote chunk acquisition or missing-chunk delivery.
 
+Direct CouchDB hosts supply a database-bound `ChunkFetchSource` through the optional `LiveSyncLocalDB` runtime factory. `LiveSyncManagers` passes it to the shared `ChunkFetcher`; application hosts omit it and retain active-replicator retrieval and local persistence. The direct source reads the prepared database and accepts results without writing them back. Recreate it with each database instance so reopening cannot retain a closed connection. `ChunkFetcher.source.unit.spec.ts` covers direct retrieval, delayed availability without change notifications, bounded failure, and teardown. `DirectFileManipulatorV2.integration.spec.ts` covers encrypted arrival before and during an outstanding read, with assertions that the reader does not write Chunks back.
+
+`DirectFileWatchOwner` owns the direct watch lifecycle. Its per-client state retains unfinished reads, same-document delivery ownership, and pending checkpoint persistence across stop and restart. Each watch session separately owns its pending documents, connection generation, and timers. Named operations receive explicit contexts through Octagonal Wheels `bindContext`; per-file and per-delivery scopes release their bookkeeping after the operation settles. Feed cancellation and timer cancellation remain synchronous in `endWatch()`, independently of unfinished reads or host callbacks. The owner tests cover retries, safe checkpoint positions, replacement sessions, and failure handling; `DirectFileManipulatorV2.unit.spec.ts` retains the public state, database binding, and close-order checks.
+
 `RemoteService.connect()` returns an owned CouchDB connection as the existing flat `{ db, info }` result with an idempotent `close()` method. `close()` first aborts outstanding abort-capable requests in that connection, then closes the PouchDB handle. The owner must transfer or close the complete connection; passing only `db` loses the cancellation boundary. A skipped information request retains the established placeholder in `info` for compatibility. `OwnedCouchDBConnection`, its opening options, and the checked `CouchDBReplicationConnection` are Commonlib-owned types exported by the existing CouchDB replicator module. The legacy `_ensureConnection()` helper continues to return a raw PouchDB handle for source compatibility; new Commonlib code must retain and close the complete owned connection instead.
 
 The one-shot CouchDB connectivity preflight is the first bounded consumer. It applies an internal 60-second safety fuse to the complete preflight on the web-compatible fetch path, disables fallback into the non-abortable native request adapter, and clears the fuse before transferring the connection to replication. The fuse is a last-resort wall-clock bound on an owner which would otherwise remain pending indefinitely; it is not the expected completion time, a per-request inactivity timeout, a user setting, or the `useTimeouts` changes-feed setting. The explicitly selected native Request API retains its previous unbounded behaviour because its current host adapter cannot honour `AbortSignal`. Extend `RemoteService.unit.spec.ts` and the one-shot ownership table in `LiveSyncReplicator.unit.spec.ts` when changing this boundary. Do not use `Promise.race()` to report a mutating native request as cancelled while it can still complete remotely.
@@ -149,6 +158,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 +240,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 +253,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,52 @@ 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.
 
+## Published shared-runtime integration
+
+Commonlib [0.2.3](https://github.com/vrtmrz/livesync-commonlib/releases/tag/0.2.3)
+is published on npm through `latest` and `next`, with an exact dependency on
+Octagonal Wheels 0.1.56. Self-hosted LiveSync
+[1.0.44](https://github.com/vrtmrz/obsidian-livesync/releases/tag/1.0.44)
+adopts the published Commonlib package. Its
+[integration record](https://github.com/vrtmrz/obsidian-livesync/pull/1307)
+separates the final source checks from the focused browser, CLI, and real-Obsidian
+results for unchanged consumer boundaries. The earlier candidate measurements
+below remain historical evidence at their recorded versions.
+
+<a id="blob-construction-and-comparison-candidate-integration"></a>
+
+## Blob construction and comparison: published integration
+
+Commonlib 0.2.3 delegates Blob 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. Commonlib 0.2.3 pins the published
+Octagonal Wheels 0.1.56 dependency and uses the ordinary package gate without a
+candidate override. The subsequent Self-hosted LiveSync integration uses the
+exact published Commonlib package. Its recorded application builds and focused
+real-Obsidian conflict and catalogue checks complement the Commonlib-owned
+compatibility contracts; they do not establish physical mobile-device behaviour.
+
 ## Obsidian plug-in
 
 The unreleased V3 Rabin–Karp correction uses proportional binary thresholds,
@@ -219,3 +265,37 @@ 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.
+
+
+<a id="shared-value-helpers-candidate-integration"></a>
+
+## Shared value helpers: published 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; Commonlib 0.2.3 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.
+
+
+<a id="shared-multi-key-locking-candidate-integration"></a>
+
+## Shared multi-key locking: published integration
+
+Commonlib 0.2.3 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,10 @@ 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.
+
+Version 0.3.0 introduces a source compatibility change: the custom client passed to `LiveSyncJournalReplicator.ensureBucketIsCompatible` must provide `hasRemoteJournals(): Promise<boolean>`. The operation distinguishes an empty bucket from Journal files left without an identifying milestone. Keeping it required makes missing client capability a type error. The standard `JournalSyncCore` client already supplies it. This change uses the next minor version under the policy above.
+
 ## 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,12 +1,18 @@
 ---
-date: 2026-09-04
-commonlib-version: "0.1.21"
-self-hosted-livesync-version: "1.0.24"
-status: unreleased
+date: 2026-10-25
+commonlib-version: "0.2.0"
+self-hosted-livesync-version: "1.0.40"
+status: published
 ---
 
 # Service feature composition
 
+Publication update, 2nd November, 2026: the Service Hub source selection, narrowed
+host dependencies, and signature-preserving composition helpers are published
+in Commonlib [0.2.3](https://github.com/vrtmrz/livesync-commonlib/releases/tag/0.2.3)
+and used by Self-hosted LiveSync 1.0.44. The front matter retains the original
+review date and version baseline.
+
 This guide is for Commonlib and maintained-host developers who are adding behaviour to the Service Hub composition. It explains when to extend a Service, create a serviceFeature, share a ServiceModule, or introduce a class which owns a resource.
 
 The choice is primarily about dependency direction and ownership. Mutable state alone does not require a class or a ServiceModule.
@@ -24,7 +30,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 +47,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 +85,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 +107,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 +131,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/unicode-path-identity.md

@@ -14,7 +14,8 @@ does not alter the Metadata path or require physical files to be renamed.
 Unsupported values are rejected.
 
 NFC identity shipped in Commonlib `0.1.42` and Self-hosted LiveSync `1.0.38`.
-The deletion handling below is an unreleased refinement of reconstruction.
+The Journal and P2P extension described below is unreleased. The original
+CouchDB release remains the published baseline for this document.
 
 ## Package contract
 
@@ -25,6 +26,24 @@ implementation for Metadata IDs rather than add a host-specific normalisation
 rule. Host storage adapters remain responsible for mapping a logical path back
 to its existing physical entry.
 
+## Initial host settings
+
+Commonlib's shared new-Vault and stored-setting defaults retain version `0`.
+The maintained CLI and Obsidian hosts use version `1` for newly created
+synchronisation settings in the unreleased extension, while retaining `0` for
+old settings and Setup URIs which omit the field. This policy does not enable
+NFC for WebApp or WebPeer, and does not migrate existing databases.
+
+The focused replication entry exports `inspectDatabasePathIdentity` and
+`PathIdentityInspection`. The existing `RemoteConnectionProbe` may expose
+`inspectPathIdentity` for read-only initial setup. Inspection distinguishes a
+confirmed empty remote from an existing declaration; unavailable or unsupported
+state rejects. Hosts use the existing declaration before first participation,
+and keep source Rebuild and configured startup explicit. Journal inspection
+reads milestone evidence without writing a node, Security Seed, or checkpoint.
+A P2P signalling probe does not establish peer database identity; Setup URIs
+carry the selected mode, and manual configuration must match the source.
+
 ## Database compatibility
 
 Version `1` uses `nfc-path-identity-v1` in the existing generation-13
@@ -78,14 +97,56 @@ does not itself perform the required reconstruction.
 
 ## Supported hosts
 
-The initial support boundary is the maintained CLI and Obsidian with CouchDB.
+The maintained CLI and Obsidian support NFC identity with CouchDB, Journal,
+and P2P in this unreleased extension.
 `PathService` owns logical ID derivation. The CLI resolves NFC-equivalent names
 against directory entries while preserving the actual entry spelling; its
 generic Node storage contract remains exact-path access. Obsidian supplies its
 normalised storage paths and preserves an existing physical spelling when it
 is NFC-equivalent to the received path.
 
-Journal and P2P refuse version `1`. Direct file access refuses a remote which
+Journal uses compatibility range `4` for NFC identity, independently of
+encryption and path obfuscation. Legacy ranges remain unchanged. The existing
+stored node ranges and required Tweak reject a different identity even when
+ordinary mismatch warnings are disabled. Removing preferred Tweaks does not
+remove the range check or an existing document-ID agreement proof. The existing
+ID check is also reused before Fetch and ordinary milestone updates. A missing
+milestone over existing journals requires Rebuild in both legacy and NFC modes;
+it is not permission to declare a new identity. Older clients must be updated
+before migration; their explicit version-check override is outside this
+compatibility guarantee.
+
+The same read-only identity assessment runs before a Journal Fetch resets the
+local database and before ordinary milestone updates. It does not publish a
+node, create a Security Seed, or change a checkpoint. Rebuild first locks the
+existing milestone for the rebuilding node, retaining an existing compatibility
+range for that node and preserving the old identity evidence and Tweaks until
+the journals are deleted. Deletion lists the keys once, retaining skipped control
+document keys until all Journal pages have been processed. It then removes those
+control documents, including the milestone and Security Seed, in finite batches.
+A repeated or backwards listing cursor stops the reset before those control
+documents are removed. A partial failure or interrupted request during Journal
+deletion retains those control documents and the transfer checkpoint for a retry. Checkpoints reset only after control
+document deletion also succeeds. A missing milestone stays absent during this
+step. The replacement identity is declared after deletion succeeds, so a failed
+or interrupted deletion cannot label the old journals with the new identity.
+
+P2P uses its existing Tweak exchange and version document to check both peers
+before ordinary data replication. Missing path settings mean version `0`.
+Local Metadata without the matching feature requires Rebuild. A fresh database
+with only control documents may declare the existing NFC feature. Connection
+state is renewed when the selected identity changes. This adds no
+authentication protocol or persistent admission store; all participating peers
+must be updated and migrated.
+
+Journal migration rebuilds the source local database and remote journals. P2P
+Rebuild prepares only the source local database. Other devices replace their
+local databases through Fetch. The existing local reset destroys Journal KV
+checkpoints; the P2P source mark and target checkpoint handle database
+replacement. These operations do not rewrite IDs or merge histories in place.
+P2P retains its existing source selection during Fetch.
+
+Direct file access refuses a remote which
 declares the NFC feature. Other host adapters must establish physical path
 resolution before offering this setting. The regression tests cover ASCII,
 NFC, NFD, and mixed paths through in-memory PouchDB Metadata lookup, with and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "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"
       ],
@@ -1011,8 +1019,8 @@
     "fflate": "^0.8.2",
     "idb": "^8.0.3",
     "markdown-it": "^14.3.3",
-    "minimatch": "^10.2.6",
-    "octagonal-wheels": "^0.1.55",
+    "minimatch": "^11.0.3",
+    "octagonal-wheels": "0.1.56",
     "pouchdb-adapter-http": "^9.0.0",
     "pouchdb-adapter-idb": "^9.0.0",
     "pouchdb-adapter-indexeddb": "^9.0.0",