Fix synchronisation setting compatibility recovery

docs/design_docs/tweak_compatibility.md

@@ -0,0 +1,93 @@
+---
+date: 2026-09-08
+commonlib-version: "0.1.24"
+self-hosted-livesync-version: "1.0.26"
+status: unreleased
+---
+
+# Tweak compatibility and recovery
+
+This document describes the integration of Commonlib 0.1.24 with
+Self-hosted LiveSync 1.0.26. Commonlib owns the interpretation of synchronisation
+settings; LiveSync owns the dialogues and operations which consume that result.
+
+## Shared assessment
+
+`assessTweakCompatibility`, exported by Commonlib's `settings` entry point,
+compares one snapshot of current settings with one snapshot of preferred settings.
+The result contains the original values, effective values, differences, and
+reconstruction consequences for each direction of adoption. It performs no
+settings writes, translation, network requests, or database operations.
+
+The interpretation of a missing value is specific to its setting. A missing
+`handleFilenameCaseSensitive` means `false`, matching legacy conversion from paths to
+document IDs. An explicitly enabled value is therefore different from either an
+explicitly disabled value or a missing value. Settings whose historical missing
+value has not been established remain unadvertised; the evaluator does not
+invent defaults or turn every falsy value into an absent value.
+
+The central replication gate, mismatch dialogues, and RedFlag Fetch preparation
+consume the same effective differences. The P2P transport retains its separate
+policy: ordinary representation differences warn without rejecting transfer,
+while its existing passphrase and peer checks still apply. Sharing assessment
+does not make the central replication policy appropriate for every transport.
+
+## Host responsibilities
+
+`ModuleResolvingMismatchedTweaks` renders the assessment supplied by the failed
+attempt. A legacy recovery hint without an assessment is adapted through the
+same Commonlib function. The remote profile review uses the trial settings as
+its current snapshot, including when deciding whether compatible chunk settings
+can be accepted automatically.
+
+Each adoption direction has its own reconstruction consequence. The remote
+values becoming local values can require local Fetch; the local values becoming
+preferred remote values can require remote Rebuild. The host must not infer the
+second consequence from the first. Existing explicit Fetch choices and manual
+acceptance controls remain host decisions.
+
+The common assessment identifies whether every known difference qualifies for
+automatic alignment. LiveSync retains the opt-out and modification-time policy
+which chooses a side. An unadvertised setting does not expand automatic
+alignment to a case whose effect cannot be assessed.
+
+Only defined, permitted settings are applied. A partial preferred configuration
+must not erase a local value with `undefined`. Recommended settings outside the
+set of settings which must match retain their existing adoption behaviour; RedFlag Fetch
+continues to apply only the set of settings which must match. RedFlag Rebuild remains
+authoritative from this device and does not adopt the remote configuration.
+
+## Decision lifetime
+
+An assessment describes one pair of inputs; it does not authorise a later
+write. LiveSync checks the settings and active publication again after waiting
+for a decision and before applying it. A changed target or changed settings
+discard that decision. The signature used for this check can contain sensitive
+configuration and must not be logged, persisted, or included in diagnostics.
+
+The active publication reservation is not held while waiting for the dialogue.
+Remote writes use the failed attempt's publication guard. Fetch and Rebuild use
+their existing owners and propagate failure without claiming a successful
+retry. A subsequent attempt must use fresh settings and respect publication
+replacement rather than reusing the rejected attempt's settings snapshot.
+
+Ordinary typed OneShot replication retains the failed outcome after its recovery
+dialogue; the next synchronisation request is a separate attempt. Directional
+replication can retry once after `CHECKAGAIN`, using freshly captured settings
+and the same publication guard. Setting adoption does not turn the original
+failed transfer into a completed transfer.
+
+## Verification boundaries
+
+Commonlib tests protect missing-value interpretation, representation differences,
+directional consequences, immutable results, central admission, and P2P policy.
+LiveSync unit tests protect ordinary versus reconstruction choices, trial-setting
+selection, partial-setting adoption, and invalidated decisions. RedFlag tests
+protect the distinction between adopting settings for Fetch and retaining local
+settings for Rebuild.
+
+Real-runtime verification must separately cover setting adoption, actual
+replication, explicit Fetch, and replication after restart. A unit test which
+mocks Fetch does not establish those behaviours, and a corrected mismatch
+dialogue alone does not establish the cause of a reported persistent automatic
+synchronisation failure.

docs/troubleshooting.md

@@ -88,6 +88,8 @@ Some settings must match across devices. LiveSync pauses synchronisation when th
 
 Current releases automatically align compatible settings which control how new chunks are created, by default and where possible. This applies to the chunk hash algorithm, chunk size, and splitter version. Existing content remains readable across these choices, although using different choices can reduce chunk reuse and increase storage or transfer work. An explicit opt-out retains the manual review. A mismatch involving encryption, path obfuscation, file-name case handling, or any combination which includes one of those settings always remains a manual decision.
 
+A missing legacy file-name case setting means case-insensitive handling. It matches an explicit disabled setting and does not require a rebuild for that difference. An explicitly enabled setting can use different document IDs and still requires a compatibility decision against either value. Other configuration differences shown in the dialogue must still be resolved.
+
 The `Sync now` command keeps routine replication progress quiet so that it is convenient to assign to a keyboard shortcut; assign one in Obsidian if that suits your workflow. A quiet command may still open this dialogue when a mismatch or another decision requires your attention.
 
 The available actions depend on when the mismatch is found: