@vrtmrz/livesync-commonlib 0.1.23 → 0.1.24

package/docs/proven-in-use.md

@@ -24,6 +24,8 @@ Commonlib's injected remote-service tests verify that an owning operation can ab
 
 Commonlib's remote-preference result contract distinguishes available synchronisation settings, a remote which has not stored those settings yet, a failed read, and a remote type which does not support central preferences. Focused CouchDB and Object Storage tests cover absent milestone data separately from transport failures, while Self-hosted LiveSync owns the initialisation choices, cancellation policy, and user-facing explanation.
 
+The focused `/settings` entry also supplies the immutable tweak assessment used by central compatibility checks and host-owned mismatch resolution. Commonlib preserves the exact assessment from a failed CouchDB or Object Storage attempt in its recovery hint, derives directional setting changes and reconstruction impact from one rule table, and keeps P2P's warning policy separate from central rejection. Self-hosted LiveSync consumes the supplied assessment for its two resolution interfaces, compatible chunk-setting auto-acceptance, and Red Flag Fetch setting adoption. The host remains responsible for user choice, settings persistence, Fetch or Rebuild execution, and verifying that the active publication and settings still match before applying a choice.
+
 Commonlib's full offline scanner distinguishes completed, deliberately skipped, and failed storage/database pairs. Before pair construction, it withholds Metadata whose actual document ID disagrees with its recorded path, without reflection, deletion, or last-seen side effects. A consistently addressed entry for the same logical path continues through the established path-based flow; only a path without such an entry also withholds storage processing. The read-only actual-ID Inspector and separately invoked one-entry repair retain ambiguous states for review, revalidate an exact source revision, verify a target-first copy, and preserve the source on failure. Snapshot-restoration tests additionally verify that restored inclusions use current storage content, stale deletions are suppressed, rename halves are admitted from their current path states, and an inspection failure does not become evidence of absence. The following full scan remains the final reconciliation step.
 
 The strict aggregate remains the default for Fast Setup, Fetch, Rebuild, direct scans, and CLI mirror or daemon paths. Self-hosted LiveSync opts only ordinary Obsidian start-up into continuing after individual pair failures. Commonlib returns the distinct `completed-with-file-failures` result, retains each failed result and retry state, records each affected path at verbose level, and leaves any user-facing notice to the host. Focused Commonlib tests cover the default and an explicitly continuing scan; downstream type checks, unit tests, and builds exercise the exact packed implementation and host call. Android-specific storage behaviour remains real-device and reporter-environment evidence rather than a Commonlib guarantee.

package/docs/settings-lifecycle.md

@@ -72,6 +72,25 @@ 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.
 
+## Assessing synchronisation tweaks
+
+Use `assessTweakCompatibility(current, preferred)` from the focused `/settings` entry when comparing the synchronisation settings advertised by two sides. The result contains immutable, whitelisted snapshots, one entry for each compared setting, and directional `adoptPreferred` and `adoptCurrent` change sets. Each entry keeps the raw value and key-presence state separately from the effective value.
+
+```ts
+import { assessTweakCompatibility } from "@vrtmrz/livesync-commonlib/settings";
+
+const assessment = assessTweakCompatibility(localTweaks, remoteTweaks);
+if (assessment.alignment === "mismatched") {
+    host.requestTweakResolution(assessment);
+}
+```
+
+An absent or `undefined` `handleFilenameCaseSensitive` value has the established effective value `false`. It is therefore equal to an explicit `false` value, while an explicit `true` value is mismatched. The historical defaults in `TweakValuesDefault` receive the same treatment. A missing value without a proven historical default is reported as `unadvertised` and does not by itself make `alignment` mismatched. Explicit `false`, `0`, and empty-string values remain advertised values.
+
+The transition change sets never contain `undefined`. They can fill a missing target from an advertised source, and can use a proven effective default when that changes the target's effective value. Each transition reports `none`, `recommended`, or `required` reconstruction impact and identifies the settings which contribute that impact. Commonlib does not apply the transition, save settings, start Fetch or Rebuild, or grant permission to retry an operation.
+
+`representationDiffers` reports raw value or key-presence differences among the compared settings. The maintained P2P transport uses this to preserve its warning for representational differences while continuing replication after ordinary tweak differences; passphrase authentication remains a separate rejection check.
+
 ## Review and downgrade boundary
 
 A migration may report `requiresSyncReview` when automatic synchronisation should wait for a human decision. Commonlib reports that requirement but does not disable synchronisation settings, persist an acknowledgement, display a dialogue, or decide whether replication may proceed. Those are host-local responsibilities because one device must not acknowledge a safety review for another device through synchronised settings.
@@ -82,6 +101,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 file-name case normalisation, 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, legacy file-name case normalisation, legacy review state, future-schema downgrade protection, and the distinction between new-Vault recommendations and stored-setting fallbacks. Tweak-assessment tests cover effective defaults, unadvertised values, directional change sets, reconstruction impact, raw representation differences, immutable snapshots, and document-ID case behaviour. 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.23",
+  "version": "0.1.24",
   "description": "Shared data, storage, and replication primitives for Self-hosted LiveSync clients.",
   "type": "module",
   "types": "./dist/index.d.ts",