@vrtmrz/livesync-commonlib 0.1.44 → 0.2.0

package/docs/development.md

@@ -18,6 +18,16 @@ The source tree is larger than the supported package surface. Consumers may impo
 
 Files elsewhere under `src` are implementation details unless a focused entry re-exports them or the compatibility inventory names them. Do not use the source layout, TypeScript path aliases, or the presence of generated declarations as evidence of a supported consumer import.
 
+## Module filenames
+
+For new or renamed TypeScript and JavaScript source modules, start the filename
+with an upper-case letter when the file contains a class with the same name,
+such as `ServiceHub.ts`. Use a lower-case initial when the module primarily
+exports functions, such as `fastForward.ts`. Follow the surrounding filename
+style for the rest of the basename. Corresponding test files use the same
+basename, such as `fastForward.unit.spec.ts`. Retain established names for
+unrelated files and separate conventions for components or other file types.
+
 ## Service composition and state ownership
 
 Commonlib uses four related forms of composition. Choose between them by ownership and dependency direction, not merely by whether an implementation has mutable state.
@@ -29,6 +39,8 @@ Commonlib uses four related forms of composition. Choose between them by ownersh
 
 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.
+
 Existing features illustrate this direction:
 
 - `targetFilter.ts` keeps each cache or readiness gate inside the factory which owns the corresponding predicate. `useTargetFilters` composes those predicates and registers them in the required order.
@@ -127,15 +139,15 @@ The compatibility event bridge delegates lifecycle and status requests to the st
 
 The physical room, WebRTC peer, and relay-socket boundaries are documented in [P2P transport lifecycle](p2p-transport-lifecycle.md). In particular, normal shutdown leaves the Trystero room without closing raw peer connections directly.
 
-Self-hosted LiveSync remains the principal downstream consumer. A Commonlib change is not ready for publication until the exact packed artefact has also passed the applicable LiveSync type checks, unit and integration tests, application builds, CLI E2E, and focused real-Obsidian E2E.
+Self-hosted LiveSync remains a principal maintained consumer. Commonlib's normal publication gate is its own type, unit, integration, and packed-boundary checks, as described in [the release runbook](releasing.md). Run targeted downstream or real-runtime checks against the exact packed artefact when a named host-specific risk is not established by those owner tests; consumer adoption and downstream test completion are not general release prerequisites.
 
 Commonlib owner tests exercise the real implementation behind each focused result and lifecycle contract. A consumer-owned unit test may inject the smallest structural capability it uses and provide its own fake or spy when that current test needs isolation. Do not publish Vitest-specific mocks, expose private service constructors, or refactor a production boundary merely to create possible future test infrastructure. Mock and spy helpers are not a prerequisite for the LiveSync 1.0 package-boundary work; add them only with the consumer test which requires them, or after that release work.
 
-Prefer an object or callback injected at the host composition boundary over replacing an ESM module namespace. If a proposed focused API would require global mutation, import-order coupling, hidden construction, or private nominal types to substitute later, stop and review the production design before stabilising it. Exact-package downstream checks and focused real-runtime E2E remain responsible for proving the real package and host composition together.
+Prefer an object or callback injected at the host composition boundary over replacing an ESM module namespace. If a proposed focused API would require global mutation, import-order coupling, hidden construction, or private nominal types to substitute later, stop and review the production design before stabilising it. Use exact-package downstream checks and focused real-runtime E2E for named host-specific risks which the owner tests cannot establish.
 
 Commonlib publishes the typed English messages which it owns and uses them when a host does not provide a translator. A host may inject a translator through `ServiceContext`; the full multilingual catalogue and language-selection state belong to that host and are not part of the Commonlib package.
 
-Keep [the maintained-host evidence](proven-in-use.md) aligned with the downstream source and gates. If a host no longer consumes a focused entry, a test is retired, or a compatibility path receives a reviewed replacement, update the consumer-facing account as part of the same maintenance rather than leaving historical adoption as a current support claim.
+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.
 
 ## Integration tests
 

package/docs/proven-in-use.md

@@ -1,13 +1,43 @@
-# Proven in maintained hosts
+# Maintained-host examples and evidence
 
 Commonlib is extracted from the implementation shared by [Self-hosted LiveSync](https://github.com/vrtmrz/obsidian-livesync) and its host applications. The package is therefore exercised by a substantial maintained consumer, but it does not yet claim a separate ecosystem of independent applications or a stable end-to-end SDK.
 
 The useful evidence is host- and contract-specific. Focused Commonlib tests establish reusable result semantics; Self-hosted LiveSync tests establish how those contracts compose into the Obsidian plug-in, CLI, WebApp, and WebPeer. The Obsidian plug-in and CLI retain the strongest device and long-running synchronisation evidence. The browser applications add focused adapter and runtime tests, browser smoke tests, a cross-application P2P scenario ending at the production CLI, and public Pages smoke validation.
 
-The code paths below identify the maintained Self-hosted LiveSync composition points used to establish this package boundary. The exact 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. The integration descriptions must still be reviewed when the maintained downstream changes.
+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.
 
 ## Obsidian plug-in
 
+The unreleased V3 Rabin–Karp correction uses proportional binary thresholds,
+including at values 0 and 1. Regression tests cover natural boundaries, suffix
+reuse, forced caps, explicit minima, EOF tails, and large UTF-8 text. The packed
+old/new CLI matrix verifies 810 file-stage digests over CouchDB, Journal, and
+P2P in both directions. Separate revision tests retain conflict coverage.
+The Linux Obsidian manual-setup workflow verifies value 0, eight 32 KiB binary
+pieces, unchanged Metadata revision and complete local Chunk inventory after
+restart, exact binary reception through Fast Fetch, and a bidirectional note
+round-trip. These checks use the unpublished local candidate with LiveSync
+1.0.39; they do not establish mobile or Cloudant-service behaviour.
+
+Unreleased Fast Fetch tests verify all current conflict leaves, including deleted
+leaves, before advancing the durable stream cursor. CouchDB 3.5.0 integration
+tests exercise revision ancestry retrieval and a fresh-import handoff to the
+ordinary PouchDB checkpoints, followed by a batch-size change and receipt of a
+new revision in LiveSync mode. Unit tests cover unimported local writes, missing
+or replaced checkpoint guards, partial publication, and exclusion of persisted
+resume cursors. A controlled connection delay also verifies that disposing the
+resource during preparation closes the connection when it arrives. Rebuilder
+tests also delay and reject device-local checkpoint
+writes, verifying that handoff, completion, and checkpoint removal wait for
+successful persistence. The handoff requires an empty local database, suspended local
+writers, and a remote database which is not replaced during the operation.
+These package-owned tests do not establish arbitrary-time fast-forwarding,
+On Demand repair, or real Obsidian runtime behaviour.
+
+The unreleased joined-device resource and UI-command work adds instance-owned typed UI handlers, legacy-compatible device projections, and device-record removal. Focused unit tests cover missing records, preservation of other devices and unknown fields, self-removal rejection, conflict retries, unsupported writes, verification failures, and handler disposal. CouchDB 3.5.0 integration tests verify that reading or forgetting never creates a missing database, and verify removal and preservation while retaining a fixture which demonstrates that local documents accept stale revisions. Object Storage integration tests against RustFS verify conditional removal and rejection of stale ETags. These checks do not make concurrent CouchDB updates atomic.
+
+Before integration with Commonlib 0.2.0, a local packed candidate based on 0.1.44 passed Self-hosted LiveSync 1.0.39 checks, unit tests, and production build. Its focused real-Obsidian 1.12.7 scenario on Linux verifies the settings entry, self-first and locked-out records, current metadata, manual refresh, confirmed removal, and preservation of other records and remote state. Mobile emulation verifies the command-palette entry, scrolling, viewport and safe-area bounds, and touch targets. Self-hosted LiveSync owns the dialogue and advisory version Notices. These results establish the tested build's behaviour; publication and native iOS and Android behaviour remain unverified.
+
 Unreleased remote-inspection tests compare individual and bulk reads against CouchDB 3.5.0. A fixture with 65 Metadata documents and 130 Chunks produces identical integrity reports while reducing HTTP requests from 198 to 8. Encrypted bulk reads preserve current conflicts, exact revision access, missing-document evidence, and unchanged database and Security Seed state. Unit tests cover bounded GET batches, encoded URL limits, per-document failures, cancellation, and explicitly excluded remote coverage. These counts describe the fixture; they do not establish large-Vault elapsed-time improvements.
 
 Unreleased [database diagnostics](database-diagnostics.md) tests cover preserved Usage accounting, normal-file identity classification, current conflict branches, byte comparisons, embedded Chunks, missing and unreadable content, cancellation, concurrent changes, and consistent pseudonyms. Real in-memory PouchDB tests verify pagination and conflict revision reads while retaining the original database handle. A CouchDB 3.5.0 integration test verifies GET-only access, encrypted Metadata and Chunk reads with an existing Security Seed, missing-seed failure without initialisation, and unchanged database update sequences and Seed documents. Focused tests also reject ciphertext which remains undecoded after an ID mismatch. Commonlib owns the result contract and compact Integrity Markdown formatter; Self-hosted LiveSync owns the serviceFeature, run-time name choice, dialogue lifecycle, and report copy and download controls. Its real Obsidian 1.12.7 test on Linux verifies cancellation before a run, both name modes, the nine-column Usage report, copy and download payloads, local integrity findings when CouchDB is unavailable, and unchanged settings, database update sequences, and Vault file names. Mobile emulation verifies the choice dialogue's viewport, safe-area, and touch-target layout; native iOS and Android behaviour remains unverified.
@@ -28,10 +58,14 @@ The CouchDB connection fix bypasses browser HTTP caching so encrypted replicatio
 
 Unreleased settings tests verify that Object Storage-only credentials, JWT values, and authentication headers reach the host persistence handler only after connection encryption, and that unavailable or failed required encryption preserves the previous persisted settings. The focused `/settings` entry also supplies conditional whole-profile Markdown preparation and import preservation. A clean packed consumer checks the exhaustive property policy and prepared output types with an ES2018 compile fixture. Commonlib owns these result and type contracts; Self-hosted LiveSync owns Markdown file writes, its settings interface, and restoration through a real Obsidian restart.
 
+The setting-service tests also cover the injected device-value boundary: exact local keys remain unchanged, the existing Vault and database-suffix configuration key layout is preserved, and separately injected stores remain isolated. These are Commonlib-owned asynchronous store contracts. Each host owns selecting its persistent adapter and verifying host storage across restart; this evidence does not claim additional real-runtime coverage.
+
 Unreleased colon-path regression tests establish that Commonlib preserves ordinary file paths through Metadata storage, Chunk retrieval, and storage reflection, with path obfuscation enabled or disabled. They use real PouchDB with injected storage. This result does not establish which filenames a host's file-creation API accepts; that boundary requires host runtime verification.
 
 Commonlib's encryption tests verify that an obfuscated Metadata document retains its document ID while its HKDF-encrypted path and file properties round-trip, that V1-obfuscated paths remain readable through the fallback, and that PouchDB replication presents a decoded path to both local storage and change events. The Fast Fetch test verifies decryption before storage and checkpointing. On 26th September 2026, a local packed candidate of this fix passed LiveSync 1.0.31's `npm run check` and unit tests, as well as real Obsidian two-Vault synchronisation, encrypted CLI-to-Obsidian transfer, and encrypted Metadata retrieval through Fast Fetch during manual CouchDB onboarding.
 
+The EntryManager selection tests distinguish Hidden File Sync documents by their original `i:` prefix. They check that the normal-file allow-list applies to ordinary paths while prefixed hidden documents remain eligible, that the normal-file ignore-list still excludes matching hidden documents, and that hidden-file disablement and the Customisation Sync exceptions retain their behaviour. Hidden File Sync owns its additional target and ignore patterns in Self-hosted LiveSync; storage reflection and native Obsidian behaviour remain downstream verification boundaries.
+
 The unreleased 0.1.30 packed candidate adds encryption of Hidden File Sync and Customisation Sync Metadata when CouchDB, E2EE V2, and Property Encryption are active. Focused Commonlib tests cover the `i:f:`, `ix:f:`, and legacy `ps:f:` representations, legacy and new setting defaults, feature declaration, concurrent version updates, and unknown-feature rejection. With that packed candidate in LiveSync, two real-Obsidian scenarios checked the raw CouchDB Metadata marker, zeroed times and size, empty public Chunk-reference list, and generation 13 feature declaration before restoring the files in a second Vault. The Hidden File Sync scenario also rebuilt the remote and verified the accepted writer's feature declaration and encrypted Metadata before the second Vault fetched them. The CLI-to-Obsidian encrypted note scenario also passed with matching effective settings. A separate real-Obsidian scenario kept continuous CouchDB replication active whilst the remote version document acquired an unknown feature; the local document was observed, the active Replicator retired, another replication was refused, and previously accepted Vault content remained intact. After restarting the Vault, both finite replication and the actual continuous connection attempt were refused by the remote declaration, without a KV feature history. These runs establish the tested local package and host build; they do not validate a published registry artefact or recovery under a future compatible client.
 
 Additional real-CouchDB integration tests exercise Fast Fetch admission before local reset, generation 12 acceptance, and generation 13 retrieval with plaintext and encrypted internal Metadata together. A real-Obsidian migration scenario enables the preference through the settings UI without Rebuild, verifies that unchanged Metadata retains its original revision while rewritten entries are encrypted with stable IDs, and checks a second device's mismatch rejection and restoration after alignment. After turning the preference OFF, Fast Fetch still retrieves both representations and their Chunks with matching content; the remote feature declaration remains. These checks use the local packed candidate with LiveSync 1.0.32.
@@ -182,6 +216,6 @@ A new integration should start with the focused entries, not by reproducing Self
 
 Use the named consumer paths as integration examples, while retaining the ownership and limitations stated in the [root README](../readme.md), [storage guide](platform-storage.md), [standard-I/O guide](platform-standard-io.md), and [remote configuration profile guide](remote-configurations.md).
 
-## Maintenance rule
+## Scope and maintenance
 
-This page records current evidence rather than historical adoption. When a host stops using an entry point, a verification path is retired, or a compatibility import moves to a focused contract, update the description and links instead of retaining a stronger claim than the maintained consumer establishes.
+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.

package/docs/releasing.md

@@ -2,16 +2,19 @@
 
 This document is the developer and maintainer runbook for preparing and publishing `@vrtmrz/livesync-commonlib`. Package-consumer guidance belongs in the root README.
 
-## Release gate
+## Commonlib-owned release checks
 
-Run the complete owner gate from a clean checkout:
+Run the normal owner checks from a clean checkout:
 
 ```bash
 npm ci
 npm run verify:package
+npm run test:integration:managed
 ```
 
-The gate type-checks Commonlib, runs its complete unit suite, verifies the source boundary, builds the distributable package, installs its exact tarball into a clean consumer, and bundles representative browser and Node entry points. The source `package.json` remains private to prevent publishing the repository root. Only the generated `.package` directory is publishable, and its manifest defaults to public publication on the `next` dist-tag.
+Together these checks type-check Commonlib, run its unit and integration suites, verify the source boundary, build the distributable package, install its exact tarball into a clean consumer, and bundle representative browser and Node entry points. These Commonlib-owned checks are the normal publication criteria. The source `package.json` remains private to prevent publishing the repository root. Only the generated `.package` directory is publishable, and its manifest defaults to public publication on the `next` dist-tag.
+
+Downstream or real-runtime checks are appropriate when a named host-specific risk is not established by the owner tests; run those checks against the exact packed artefact and record the risk and result. LiveSync adoption and downstream validation are not general publication prerequisites. The [maintained-host examples and evidence](proven-in-use.md) page is optional context, not a release or update gate.
 
 The package builder normalises generated directories to `0755`, ordinary files to `0644`, and declared `bin` targets to `0755` before validation. `test:package` uses a restrictive umask and verifies the packed modes, so local and hosted builds do not differ only because their caller environments use different umasks.
 
@@ -29,13 +32,17 @@ npm run verify:package
 
 Inspect the lockfile diff before committing it. A dependency-only maintenance change must not alter the source package version, and lockfile normalisation must not be described as a package upgrade when resolved versions and integrity values are unchanged. When the workflow selects a newer reviewed npm CLI, update this example in the same change.
 
-Before publication, run the downstream workflow against an exact Self-hosted LiveSync ref which already consumes the package. The workflow installs the tarball produced from the selected Commonlib commit, then runs LiveSync type checks, unit tests, plug-in and application builds, and CLI E2E. Real Obsidian E2E remains local-only and is required when the changed boundary affects actual plug-in composition, storage, UI, or platform behaviour.
+When a named host-specific risk is not established by the Commonlib owner checks, run the relevant downstream workflow against an exact Self-hosted LiveSync ref which consumes the package. It installs the tarball produced from the selected Commonlib commit and runs LiveSync type checks, unit tests, plug-in and application builds, and CLI E2E. Real Obsidian E2E remains local-only and is appropriate when the named risk concerns actual plug-in composition, storage, UI, or platform behaviour. These checks are conditional on the risk; LiveSync adoption is not a general release prerequisite.
+
+## Version compatibility policy
+
+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.
 
 ## Preparing a release
 
-Choose the version explicitly. Prefer a `-next.N` prerelease, such as `0.1.32-next.0`, when registry installation must be validated before the stable version. Reserve `-rc.N` for an explicitly chosen release candidate. Package-proof versions are local artefacts and cannot be staged.
+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.
 
-Prepare both stable releases and pre-releases on a reviewed pull request based on `main`. A pre-release may be staged from the exact reviewed pull-request branch commit so that the registry artefact can be validated in Self-hosted LiveSync before the Commonlib change is merged. A stable release must be staged only after its exact reviewed release commit is present on `main`.
+Prepare stable releases and any optional prereleases on a reviewed pull request based on `main`. An optional prerelease may be staged from the exact reviewed pull-request branch commit. A stable release must be staged only after its exact reviewed release commit is present on `main`.
 
 ```bash
 npm ci
@@ -44,7 +51,7 @@ npm run verify:package
 npm publish --dry-run .package --tag next --access public
 ```
 
-Review `package.json`, `package-lock.json`, the generated manifest, the tarball contents, the test results, and the downstream evidence. Commit only the source manifest and lockfile for the version change; `.package`, `.package-consumer`, and `artifacts` are generated and ignored. Push and open a release pull request only after the usual user checkpoint. Keep a pre-release pull request in draft while its exact registry artefact is validated in Self-hosted LiveSync. Merge and stable publication remain separate later checkpoints.
+Review `package.json`, `package-lock.json`, the generated manifest, the tarball contents, and the Commonlib-owned test results. Add downstream evidence when a named host-specific risk requires it. Commit only the source manifest and lockfile for the version change; `.package`, `.package-consumer`, and `artifacts` are generated and ignored. Push and open a release pull request only after the usual user checkpoint. Keep a pull request in draft while a specifically planned downstream check is in progress; that check is not required when no such risk remains. Merge and publication remain separate later checkpoints.
 
 ## Historical initial npm bootstrap
 
@@ -58,9 +65,9 @@ npm run verify:package
 npm publish .package --tag next --access public
 ```
 
-Confirm the authenticated npm account, `@vrtmrz` scope ownership, package name, version, tarball checksum, packed contents, source commit, and target tag immediately before publication. Treat bootstrap publication as a separate user-authorised operation. npm may assign `latest` to the first published version even when `next` is requested; leave the immutable version in place and replace `latest` only after a stable release has passed consumer validation.
+Confirm the authenticated npm account, `@vrtmrz` scope ownership, package name, version, tarball checksum, packed contents, source commit, and target tag immediately before publication. Treat bootstrap publication as a separate user-authorised operation. npm may assign `latest` to the first published version even when `next` is requested; leave the immutable version in place and replace `latest` only after a stable release has passed the Commonlib owner checks and any applicable targeted host checks.
 
-Bootstrap publication was the one historical exception which used direct `npm publish`. Do not repeat that operation for routine releases. Current pre-releases use protected staged publishing and may select an exact reviewed branch commit; stable releases use an exact `main` commit. If validation fails, leave the published version immutable and prepare a new pre-release version.
+Bootstrap publication was the one historical exception which used direct `npm publish`. Do not repeat that operation for routine releases. Optional prereleases use protected staged publishing and may select an exact reviewed branch commit; stable releases use an exact `main` commit. If the owner checks or an applicable targeted host check fails, leave the published version immutable and prepare a new version.
 
 ## Trusted staged publishing
 
@@ -73,9 +80,9 @@ After bootstrap, configure the npm Trusted Publisher for:
 
 Protect the GitHub `npm` environment with a required reviewer and permit only `main`. The trusted workflow definition always runs from `main`. A pre-release may package an exact commit from a reviewed draft branch, while a stable release also requires the package source and workflow-triggering commit to be the exact current `main` commit. The workflow confirms that the selected source branch still points to the requested full commit SHA, checks out that SHA, runs `verify:package`, validates the requested version and confirmation text, packs the reviewed output, records its checksum, and passes the same tarball to the protected staging job.
 
-npm's automatic provenance identifies the `main` commit which triggered the trusted workflow. For a pre-release selected from a draft branch, this identifies the trusted workflow source rather than the packaged source commit. Record and verify the separate `source_ref`, exact package SHA, and tarball checksum before approving the staged version. This provenance distinction is accepted for an immutable pre-release used to validate the consumer before merge. A stable release requires the workflow and package source to be the same exact `main` commit.
+npm's automatic provenance identifies the `main` commit which triggered the trusted workflow. For an optional prerelease selected from a draft branch, this identifies the trusted workflow source rather than the packaged source commit. Record and verify the separate `source_ref`, exact package SHA, and tarball checksum before approving the staged version. This provenance distinction is accepted for an immutable prerelease when a consumer check is planned before merge. A stable release requires the workflow and package source to be the same exact `main` commit.
 
-Dispatch a pre-release from its exact reviewed draft branch commit:
+When using an optional pre-release, dispatch it from its exact reviewed draft branch commit:
 
 ```bash
 source_ref=separate-setting-lifecycle
@@ -91,11 +98,11 @@ gh workflow run publish-npm.yml \
 
 For a stable release, use `source_ref=main`. The workflow rejects a stable release selected from another branch, rejects a stable release without its trusted workflow commit, and requires the workflow-triggering SHA to equal the packaged `main` SHA. The workflow dispatch itself uses `--ref main` for every release, so an unmerged branch cannot change the trusted publication job or acquire access to the `npm` environment.
 
-The workflow always stages to `next`. Inspect the staged package name, version, access, dist-tag, provenance, checksum, files, selected source branch, and source commit before approving it through npm. Approval and later promotion to `latest` are separate user-authorised operations. Keep the Commonlib and Self-hosted LiveSync consumer pull requests in draft while validating the exact registry pre-release. If validation fails, leave that published version immutable and prepare a new pre-release. After successful consumer validation, merge Commonlib only through its separate maintainer gate. Validate a stable release in Self-hosted LiveSync before promoting it to `latest`.
+The workflow always stages to `next`. Inspect the staged package name, version, access, dist-tag, provenance, checksum, files, selected source branch, and source commit before approving publication to npm. After approval publishes the version, fetch that exact registry version and compare its SHA-256, package name and version, and provenance with the reviewed staged artefact and source revision; confirm that `next` points to that version. Install the fetched registry artefact in a clean consumer and run the relevant package checks before requesting promotion. Stage approval and later promotion to `latest` are separate user-authorised operations. Promote the same version only after those registry checks pass and any applicable targeted host checks are complete. If a check fails, leave the published version immutable and prepare a new version. Keep consumer pull requests in draft only while a specifically planned host check is in progress; consumer adoption is not a precondition for Commonlib merge or release.
 
 ## Publishing a GitHub Release
 
-Create a GitHub Release for each stable Commonlib release after the exact registry artefact has passed downstream validation and the version has been promoted to `latest`. Target the exact `main` commit used to build the published package.
+Create a GitHub Release for each stable Commonlib release after the exact registry artefact has passed the Commonlib owner checks and the version has been promoted to `latest`. Complete any applicable targeted host checks before release. Target the exact `main` commit used to build the published package.
 
 Protect the GitHub `github-release` environment with a required reviewer and permit only `main`. The manually dispatched workflow first verifies the release with read-only repository access. Only its protected publication job receives `contents: write` access.
 

package/docs/settings-lifecycle.md

@@ -18,7 +18,7 @@ import { createNewVaultSettings } from "@vrtmrz/livesync-commonlib/settings";
 const initialSettings = createNewVaultSettings();
 ```
 
-The recommended base currently selects a 50 MB maximum synchronised file size, Rabin–Karp chunk splitting, Plug-in Sync V2, case-insensitive file-name handling, and E2EE V2. Chunk revisions are always derived from their content; the obsolete `doNotUseFixedRevisionForChunks` stored key is retained only for compatibility and is not a recommendation or tweak. The recommended base does not enable synchronisation or encryption on behalf of the user.
+The recommended base currently selects a 50 MB maximum synchronised file size, a `customChunkSize` value of 0, Rabin–Karp chunk splitting, Plug-in Sync V2, case-insensitive file-name handling, and E2EE V2. Chunk revisions are always derived from their content; the obsolete `doNotUseFixedRevisionForChunks` stored key is retained only for compatibility and is not a recommendation or tweak. The recommended base does not enable synchronisation or encryption on behalf of the user.
 
 Compared with the conservative stored-setting fallbacks, the current new-Vault object has exactly two semantic differences:
 
@@ -27,15 +27,23 @@ Compared with the conservative stored-setting fallbacks, the current new-Vault o
 | `usePluginSyncV2` | `false` | `true` |
 | `handleFilenameCaseSensitive` | normalised from the legacy absent value to `false` | `false` |
 
-The other headline recommendations are already the conservative fallbacks: `syncMaxSizeInMB` is 50, `chunkSplitterVersion` is `v3-rabin-karp`, and `E2EEAlgorithm` is `v2`. Data Compression, Eden, V1 dynamic iteration, the legacy IndexedDB adapter, Hidden File Sync, and automatic synchronisation remain disabled when their stored values are absent. Explicit stored values take precedence.
+The other headline recommendations are already the conservative fallbacks: `syncMaxSizeInMB` is 50, `customChunkSize` is 0, `chunkSplitterVersion` is `v3-rabin-karp`, and `E2EEAlgorithm` is `v2`. Data Compression, Eden, V1 dynamic iteration, the legacy IndexedDB adapter, Hidden File Sync, and automatic synchronisation remain disabled when their stored values are absent. Explicit stored values take precedence.
 
-Apply a remote-specific preferred object only while configuring that remote. Do not merge it into an existing stored configuration merely because the remote type can be inferred. The self-hosted CouchDB profile uses a chunk-size coefficient of 60, matching the Doctor check for Rabin–Karp databases; Cloudant retains its service-specific value of 0.
+Apply a remote-specific preferred object only while configuring that remote. Do not merge it into an existing stored configuration merely because the remote type can be inferred. Cloudant, self-hosted CouchDB, and Journal Sync setup all use the common `customChunkSize` value of 0. Their unrelated request and bulk settings remain service-specific. The current Doctor regulation no longer recommends changing the value to 60 universally, and existing explicit values remain valid.
+
+The new Doctor rule set inherits 1.0.33 and withdraws the Chunk-size rule with
+`customChunkSize: undefined`. Historical regulations keep their original rules.
+This removes the recommendation, rather than deleting a stored setting or
+forcing it to 0. Its consultation version deliberately remains 1.0.33: removing
+a recommendation does not require users to review unchanged recommendations
+again. Existing dismissals remain effective; an explicit forced rescan still
+checks the remaining rules.
 
 | Explicitly selected remote | `customChunkSize` | `concurrencyOfReadChunksOnline` | `minimumIntervalOfReadChunksOnline` |
 | --- | ---: | ---: | ---: |
 | Cloudant | 0 | 100 | 333 |
-| Self-hosted CouchDB | 60 | 30 | 25 |
-| Object Storage | 10 | 30 | 25 |
+| Self-hosted CouchDB | 0 | 30 | 25 |
+| Journal Sync (Object Storage) | 0 | 30 | 25 |
 
 These are setup-time recommendations, not upgrade migrations. Selecting or detecting a remote does not apply them to an existing configuration unless the person is actively configuring that remote.
 
@@ -72,6 +80,30 @@ Two other values deliberately remain unset until their owning lifecycle supplies
 
 The standard Commonlib `SettingService` performs this preparation automatically. Hosts which use that service can inspect `getSettingsMigrationState()` after `loadSettings()` instead of calling the function themselves.
 
+## Host storage for device values and configuration
+
+The host selects an asynchronous `ValueStore & ValueDeleter` for each application instance and injects it into the setting service as `deviceValues`. Commonlib does not discover `globalThis.localStorage`, create module-global storage, or fall back to another store. `setting.deviceValues` exposes the injected exact-key root. `setting.config` is an asynchronous view over the same root, scoped to the current Vault name and `additionalSuffixOfDatabaseName`; the Service Hub `config` property refers to that same view.
+
+For an existing Web Storage layout, pass the selected storage object explicitly and use an empty adapter prefix so the service can address existing raw keys:
+
+```ts
+import { createWebStorageValueStore } from "@vrtmrz/value-store/web-storage";
+
+const deviceValues = createWebStorageValueStore(window.localStorage, { prefix: "" });
+// Supply deviceValues as the setting service's required composition dependency.
+```
+
+Use `deviceValues` for exact device-local keys, including existing keys such as `ls-setting-passphrase`. Use `config` for logical configuration keys; the service retains the established Vault and database-suffix key format. For example, the `checkpoint` key for Vault `notes` remains `notes--checkpoint` with an empty suffix and `notes-team-checkpoint` with suffix `team`. Keep the existing key names and await every read, write, and deletion:
+
+```ts
+const passphrase = await setting.deviceValues.getValue("ls-setting-passphrase");
+const checkpoint = await setting.config.getValue("checkpoint");
+await setting.config.setValue("checkpoint", "revision-42");
+await setting.config.delete("checkpoint");
+```
+
+`getValue` returns `null` when a key is absent. Use `getObject` and `setObject` for values stored as JSON; Commonlib does not automatically reinterpret old strings or migrate entries between the exact-key root and the scoped view.
+
 ## Preparing settings for persistence and Markdown
 
 The existing `SettingService` provides `changeConfigurationEncryption(store, passphrase?)` for hosts which edit the configuration encryption mode or device-local custom key. Await it before marking those edits as saved. It prepares one wrapper key for connection credentials, the E2EE passphrase, remote profile URIs, and the independent ID key, and serialises the change with ordinary settings saves. It rejects empty keys and unreadable existing protected items. A failed write attempts to restore the previous device key and does not send a success event. The device key and settings document use separate host writes, so this is not a guarantee of rollback after process termination or an uncertain persistence error.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.44",
+  "version": "0.2.0",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",
@@ -92,6 +92,11 @@
       "import": "./dist/setupUri.js",
       "default": "./dist/setupUri.js"
     },
+    "./ui-commands": {
+      "types": "./dist/uiCommands.d.ts",
+      "import": "./dist/uiCommands.js",
+      "default": "./dist/uiCommands.js"
+    },
     "./compat/API/processSetting": {
       "types": "./dist/API/processSetting.d.ts",
       "import": "./dist/API/processSetting.js",
@@ -457,11 +462,6 @@
       "import": "./dist/services/base/AppLifecycleService.js",
       "default": "./dist/services/base/AppLifecycleService.js"
     },
-    "./compat/services/base/ConfigService": {
-      "types": "./dist/services/base/ConfigService.d.ts",
-      "import": "./dist/services/base/ConfigService.js",
-      "default": "./dist/services/base/ConfigService.js"
-    },
     "./compat/services/base/ControlService": {
       "types": "./dist/services/base/ControlService.d.ts",
       "import": "./dist/services/base/ControlService.js",
@@ -522,11 +522,6 @@
       "import": "./dist/services/implements/base/UIService.js",
       "default": "./dist/services/implements/base/UIService.js"
     },
-    "./compat/services/implements/browser/ConfigServiceBrowserCompat": {
-      "types": "./dist/services/implements/browser/ConfigServiceBrowserCompat.d.ts",
-      "import": "./dist/services/implements/browser/ConfigServiceBrowserCompat.js",
-      "default": "./dist/services/implements/browser/ConfigServiceBrowserCompat.js"
-    },
     "./compat/services/implements/headless/HeadlessAPIService": {
       "types": "./dist/services/implements/headless/HeadlessAPIService.d.ts",
       "import": "./dist/services/implements/headless/HeadlessAPIService.js",
@@ -675,6 +670,9 @@
       "setup-uri": [
         "dist/setupUri.d.ts"
       ],
+      "ui-commands": [
+        "dist/uiCommands.d.ts"
+      ],
       "compat/API/processSetting": [
         "dist/API/processSetting.d.ts"
       ],
@@ -894,9 +892,6 @@
       "compat/services/base/AppLifecycleService": [
         "dist/services/base/AppLifecycleService.d.ts"
       ],
-      "compat/services/base/ConfigService": [
-        "dist/services/base/ConfigService.d.ts"
-      ],
       "compat/services/base/ControlService": [
         "dist/services/base/ControlService.d.ts"
       ],
@@ -933,9 +928,6 @@
       "compat/services/implements/base/UIService": [
         "dist/services/implements/base/UIService.d.ts"
       ],
-      "compat/services/implements/browser/ConfigServiceBrowserCompat": [
-        "dist/services/implements/browser/ConfigServiceBrowserCompat.d.ts"
-      ],
       "compat/services/implements/headless/HeadlessAPIService": [
         "dist/services/implements/headless/HeadlessAPIService.d.ts"
       ],
@@ -1013,6 +1005,7 @@
     "@smithy/types": "^4.14.3",
     "@smithy/util-retry": "^4.4.5",
     "@trystero-p2p/nostr": "0.25.3",
+    "@vrtmrz/value-store": "0.1.0",
     "diff-match-patch": "^1.0.5",
     "events": "^3.3.0",
     "fflate": "^0.8.2",
@@ -1024,9 +1017,11 @@
     "pouchdb-adapter-idb": "^9.0.0",
     "pouchdb-adapter-indexeddb": "^9.0.0",
     "pouchdb-adapter-memory": "^9.0.0",
+    "pouchdb-checkpointer": "9.0.0",
     "pouchdb-core": "^9.0.0",
     "pouchdb-errors": "^9.0.0",
     "pouchdb-find": "^9.0.0",
+    "pouchdb-generate-replication-id": "9.0.0",
     "pouchdb-mapreduce": "^9.0.0",
     "pouchdb-merge": "^9.0.0",
     "pouchdb-replication": "^9.0.0",

package/dist/services/base/ConfigService.d.ts

@@ -1,7 +0,0 @@
-import type { IConfigService } from "./IService.js";
-import { ServiceBase, type ServiceContext } from "./ServiceBase.js";
-export declare abstract class ConfigService<T extends ServiceContext = ServiceContext> extends ServiceBase<T> implements IConfigService {
-    abstract getSmallConfig(key: string): string | null;
-    abstract setSmallConfig(key: string, value: string): void;
-    abstract deleteSmallConfig(key: string): void;
-}

package/dist/services/base/ConfigService.js

@@ -1,6 +0,0 @@
-import { ServiceBase } from "./ServiceBase.js";
-class ConfigService extends ServiceBase {
-}
-export {
-  ConfigService
-};

package/dist/services/implements/browser/ConfigServiceBrowserCompat.d.ts

@@ -1,16 +0,0 @@
-import { ConfigService } from "../../base/ConfigService.js";
-import type { IAPIService, ISettingService } from "../../base/IService.js";
-import type { ServiceContext } from "../../base/ServiceBase.js";
-import { createInstanceLogFunction } from "../../lib/logUtils.js";
-export interface ConfigServiceBrowserCompatDependencies {
-    settingService: ISettingService;
-    APIService: IAPIService;
-}
-export declare class ConfigServiceBrowserCompat<T extends ServiceContext = ServiceContext> extends ConfigService<T> {
-    private _settingService;
-    _log: ReturnType<typeof createInstanceLogFunction>;
-    constructor(context: T, dependencies: ConfigServiceBrowserCompatDependencies);
-    getSmallConfig(key: string): string;
-    setSmallConfig(key: string, value: string): void;
-    deleteSmallConfig(key: string): void;
-}

package/dist/services/implements/browser/ConfigServiceBrowserCompat.js

@@ -1,23 +0,0 @@
-import { ConfigService } from "../../base/ConfigService.js";
-import { createInstanceLogFunction } from "../../lib/logUtils.js";
-class ConfigServiceBrowserCompat extends ConfigService {
-  _settingService;
-  _log;
-  constructor(context, dependencies) {
-    super(context);
-    this._settingService = dependencies.settingService;
-    this._log = createInstanceLogFunction("ConfigService", dependencies.APIService);
-  }
-  getSmallConfig(key) {
-    return this._settingService.getSmallConfig(key);
-  }
-  setSmallConfig(key, value) {
-    return this._settingService.setSmallConfig(key, value);
-  }
-  deleteSmallConfig(key) {
-    return this._settingService.deleteSmallConfig(key);
-  }
-}
-export {
-  ConfigServiceBrowserCompat
-};