@vrtmrz/livesync-commonlib 0.1.0-rc.2 → 0.1.0-rc.4

package/docs/development.md

@@ -121,6 +121,14 @@ Resolve these questions before describing the corresponding behaviour as stable:
 
 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.
 
+After the reviewed Self-hosted LiveSync revision changes, inspect its current compatibility imports with:
+
+```bash
+npm run update:downstream-import-inventory -- --downstream /path/to/obsidian-livesync
+```
+
+The command recognises both the former `@lib/*` source aliases and current `@vrtmrz/livesync-commonlib/compat/*` package imports. It ignores focused package entries. Review the resulting paths and recorded downstream commit before accepting them. Regenerate the export map only for a new package version: do not change the contents represented by an immutable published version.
+
 TODO: classify and document compatibility paths whose purpose is still unclear before stabilising the first public release. Remove obsolete paths rather than documenting accidental layout as API.
 
 Release preparation and staged-publication checks are documented in [the maintainer runbook](releasing.md).

package/docs/proven-in-use.md

@@ -8,31 +8,33 @@ The source links below identify the exact reviewed Self-hosted LiveSync revision
 
 ## Obsidian plug-in
 
-The plug-in extends the neutral `ServiceContext` with Obsidian-owned capabilities in [`ObsidianServiceContext.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/6cc06bf20fc044c70408ef3d92fe0bbc0874479d/src/modules/services/ObsidianServiceContext.ts). One context instance carries the host translator and event hub through the Service Hub rather than placing those dependencies in Commonlib globals.
+The plug-in extends the neutral `ServiceContext` with Obsidian-owned capabilities in [`ObsidianServiceContext.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/src/modules/services/ObsidianServiceContext.ts). One context instance carries the host translator and event hub through the Service Hub rather than placing those dependencies in Commonlib globals.
 
-The consumer's [service-context contract](https://github.com/vrtmrz/obsidian-livesync/blob/6cc06bf20fc044c70408ef3d92fe0bbc0874479d/test/contracts/serviceContext.ts) checks shared result semantics and exact context identity across the composed services. The [real-Obsidian suite](https://github.com/vrtmrz/obsidian-livesync/blob/6cc06bf20fc044c70408ef3d92fe0bbc0874479d/test/e2e-obsidian/README.md) then covers plug-in loading, representative Svelte dialogue mounts, Vault reflection, CouchDB and Object Storage synchronisation, two-Vault behaviour, and other Obsidian-owned boundaries.
+The consumer's [service-context contract](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/test/contracts/serviceContext.ts) checks shared result semantics and exact context identity across the composed services. The [real-Obsidian suite](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/test/e2e-obsidian/README.md) then covers plug-in loading, representative Svelte dialogue mounts, Vault reflection, CouchDB and Object Storage synchronisation, two-Vault behaviour, and other Obsidian-owned boundaries.
 
 Most replication and storage services used by the plug-in still enter through explicit `compat/*` paths. Those imports prove that the published compatibility boundary supports the current migration; they are not examples of a finished high-level client API.
 
 The plug-in's manual onboarding and Remote Databases pane use the focused `/remote-configurations` entry to create opaque profile IDs, retain user-visible names, and select main and P2P remotes. Commonlib owns the in-memory profile result contract; Self-hosted LiveSync adds dialogue, Setup URI classification, Fetch or Rebuild scheduling, persistence, restart ordering, and real-Obsidian presentation checks.
 
+Commonlib's confirmation contract can also convey a host-neutral vertical action-layout request for long, safety-sensitive choices. Self-hosted LiveSync maps that request to Fancy Kit at its Obsidian boundary. Focused tests check the mapping, and the consumer's real-Obsidian suite checks the resulting controls and mobile touch targets; Commonlib does not own the rendering or CSS.
+
 ## CLI
 
-The CLI extends the same neutral context with its database path and injected `StandardIo` in [`NodeServiceContext.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/6cc06bf20fc044c70408ef3d92fe0bbc0874479d/src/apps/cli/services/NodeServiceContext.ts). Its entry point creates the Node standard-I/O adapter once and passes it to command composition, while unit tests provide stream-independent fakes for parsing, prompts, standard output, and standard error.
+The CLI extends the same neutral context with its database path and injected `StandardIo` in [`NodeServiceContext.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/src/apps/cli/services/NodeServiceContext.ts). Its entry point creates the Node standard-I/O adapter once and passes it to command composition, while unit tests provide stream-independent fakes for parsing, prompts, standard output, and standard error.
 
-The CLI filesystem composition receives a configured base directory and constructs the rooted Node storage adapter in [`NodeFileSystemAdapter.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/6cc06bf20fc044c70408ef3d92fe0bbc0874479d/src/apps/cli/adapters/NodeFileSystemAdapter.ts). Commonlib's shared storage result table checks the focused root contract; the consumer adds its file cache, Vault-shaped operations, case handling, and command policy.
+The CLI filesystem composition receives a configured base directory and constructs the rooted Node storage adapter in [`NodeFileSystemAdapter.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/src/apps/cli/adapters/NodeFileSystemAdapter.ts). Commonlib's shared storage result table checks the focused root contract; the consumer adds its file cache, Vault-shaped operations, case handling, and command policy.
 
-The maintained CLI checks include unit tests, Deno-driven CLI E2E, Compose-based compatibility runs, and the [CLI-to-real-Obsidian synchronisation scenario](https://github.com/vrtmrz/obsidian-livesync/blob/6cc06bf20fc044c70408ef3d92fe0bbc0874479d/test/e2e-obsidian/scripts/cli-to-obsidian-sync.ts). The latter is the strongest current evidence that the CLI and plug-in compose compatible Commonlib behaviour across two hosts.
+The maintained CLI checks include unit tests, Deno-driven CLI E2E, Compose-based compatibility runs, and the [CLI-to-real-Obsidian synchronisation scenario](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/test/e2e-obsidian/scripts/cli-to-obsidian-sync.ts). The latter is the strongest current evidence that the CLI and plug-in compose compatible Commonlib behaviour across two hosts.
 
 ## Webapp
 
-The Webapp receives an already authorised `FileSystemDirectoryHandle` from its host and constructs `FileSystemAccessStorageAdapter` inside [`FSAPIFileSystemAdapter.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/6cc06bf20fc044c70408ef3d92fe0bbc0874479d/src/apps/webapp/adapters/FSAPIFileSystemAdapter.ts). The adapter does not call `showDirectoryPicker()`, choose a directory, or persist the handle. This is the maintained application example for the browser entry's root-ownership rule.
+The Webapp receives an already authorised `FileSystemDirectoryHandle` from its host and constructs `FileSystemAccessStorageAdapter` inside [`FSAPIFileSystemAdapter.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/src/apps/webapp/adapters/FSAPIFileSystemAdapter.ts). The adapter does not call `showDirectoryPicker()`, choose a directory, or persist the handle. This is the maintained application example for the browser entry's root-ownership rule.
 
 The browser and Node storage implementations run through the same Commonlib result contract, and the Webapp adapter has focused unit coverage. The Webapp is also type-checked and built by downstream verification. Its browser E2E has not been kept at the same level as the Obsidian and CLI suites, so the documentation does not treat Webapp integration as equivalent real-runtime evidence.
 
 ## WebPeer and browser service composition
 
-The browser service composition in [`createLiveSyncBrowserServiceHub.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/6cc06bf20fc044c70408ef3d92fe0bbc0874479d/src/apps/browser/createLiveSyncBrowserServiceHub.ts) supplies browser-owned API and UI services around a caller-supplied context. WebPeer and the browser applications exercise this compatibility surface through type checks and builds.
+The browser service composition in [`createLiveSyncBrowserServiceHub.ts`](https://github.com/vrtmrz/obsidian-livesync/blob/fa336574e6055bbd61557da859fa0c1c44ca7ec9/src/apps/browser/createLiveSyncBrowserServiceHub.ts) supplies browser-owned API and UI services around a caller-supplied context. WebPeer and the browser applications exercise this compatibility surface through type checks and builds.
 
 The Obsidian plug-in, CLI, and Webapp compose P2P ownership through `useP2PReplicatorFeature`. Commands and Obsidian views retain its live result object and resolve the current replicator when an action occurs. WebPeer still enters through the deprecated combined compatibility function, which now delegates the same ownership and lifecycle to the focused feature instead of maintaining a second implementation. Downstream Deno and Compose P2P E2E cover peer discovery and synchronisation; the Webapp and WebPeer UI surfaces themselves remain build- and type-check evidence rather than equivalent real-runtime gates.
 

package/docs/releasing.md

@@ -30,7 +30,9 @@ 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.
 
-## Initial npm bootstrap
+## Historical initial npm bootstrap
+
+The package and its Trusted Publisher are already configured. This section records the one-time bootstrap which created the package; do not use it for routine releases. Current releases use the staged-publishing workflow below.
 
 The npm package must exist before Trusted Publishing can be configured. Bootstrap the first reviewed release candidate once from the exact reviewed commit in the draft release pull request, using an interactive npm session with 2FA:
 

package/docs/settings-lifecycle.md

@@ -18,9 +18,9 @@ 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, fixed chunk revisions, Plug-in Sync V2, case-insensitive file-name handling, and E2EE V2. It does not enable synchronisation or encryption on behalf of the user.
+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.
 
-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.
+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.
 
 ## Loading existing settings
 
@@ -43,6 +43,8 @@ if (prepared.requiresSyncReview) {
 
 Explicit stored values take precedence over every fallback. A migration therefore preserves synchronisation switches and other user choices unless a migration step documents a deliberate transformation.
 
+An existing settings store without an explicit `handleFilenameCaseSensitive` value reports `filename-case-sensitivity-unresolved` and leaves the value unset. The host must keep synchronisation paused until the user makes an explicit compatibility decision. An explicit `true` or `false` value is preserved. New Vaults select case-insensitive handling (`false`).
+
 The standard Commonlib `SettingService` performs this preparation automatically. Hosts which use that service can inspect `getSettingsMigrationState()` after `loadSettings()` instead of calling the function themselves.
 
 ## Review and downgrade boundary
@@ -55,6 +57,6 @@ The settings schema version is independent of the package version and of any rem
 
 ## Tests owned by Commonlib
 
-The settings lifecycle unit tests cover blank stores, representative legacy choices, migration idempotence, legacy review state, future-schema downgrade protection, and the distinction between new-Vault recommendations and stored-setting fallbacks. The packed-package test imports the focused `/settings` entry from a clean consumer and checks its declarations and runtime exports.
+The settings lifecycle unit tests cover blank stores, representative legacy choices, migration idempotence, unresolved file-name case policy, legacy review state, future-schema downgrade protection, and the distinction between new-Vault recommendations and stored-setting fallbacks. The packed-package test imports the focused `/settings` entry from a clean consumer and checks its declarations and runtime exports.
 
 Hosts remain responsible for testing when setup is classified as new, how local review acknowledgement is stored, how replication is gated, and how their settings interface presents the result.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vrtmrz/livesync-commonlib",
-  "version": "0.1.0-rc.2",
+  "version": "0.1.0-rc.4",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "license": "MIT",