@vrtmrz/livesync-commonlib 0.2.3 → 0.3.0

package/docs/conflict-resolution.md

@@ -74,7 +74,7 @@ A host must not apply a dialogue result after either compared revision has cease
 
 ## Scheduling conflict checks
 
-The unreleased `@vrtmrz/livesync-commonlib/conflicts` entry exports
+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

package/docs/development.md

@@ -111,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.

package/docs/proven-in-use.md

@@ -6,9 +6,23 @@ 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
+## Published shared-runtime integration
 
-The unreleased Blob extraction delegates construction to
+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
@@ -31,13 +45,12 @@ absence on the native path. The
 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.
+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
 
@@ -254,7 +267,9 @@ Use the named consumer paths as integration examples, while retaining the owners
 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
+<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
@@ -264,16 +279,18 @@ 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
+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.
 
 
-## Shared multi-key locking: candidate integration
+<a id="shared-multi-key-locking-candidate-integration"></a>
+
+## Shared multi-key locking: published integration
 
-The unreleased candidate imports `withLocks` directly from
+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.

package/docs/releasing.md

@@ -40,6 +40,8 @@ The Commonlib 0.2 policy begins with 0.2.0 and does not retroactively change com
 
 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

@@ -2,11 +2,17 @@
 date: 2026-10-25
 commonlib-version: "0.2.0"
 self-hosted-livesync-version: "1.0.40"
-status: unreleased
+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.

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.3",
+  "version": "0.3.0",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -1019,7 +1019,7 @@
     "fflate": "^0.8.2",
     "idb": "^8.0.3",
     "markdown-it": "^14.3.3",
-    "minimatch": "^10.2.6",
+    "minimatch": "^11.0.3",
     "octagonal-wheels": "0.1.56",
     "pouchdb-adapter-http": "^9.0.0",
     "pouchdb-adapter-idb": "^9.0.0",