mirror of
https://github.com/vrtmrz/obsidian-livesync.git
synced 2026-09-09 12:17:07 +00:00
94 lines
4.9 KiB
Markdown
94 lines
4.9 KiB
Markdown
---
|
|
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.
|