mirror of
https://github.com/vrtmrz/obsidian-livesync.git
synced 2026-10-29 04:23:20 +00:00
Prepare 1.0.41 notes, dependencies, and recovery coverage
Align release metadata and audited development dependencies, and consolidate release notes with contributor acknowledgements. Cover upgrades, start-up integrity, text reflection, and interrupted saves in real Obsidian. Document the accepted provenance persistence interval: identical replayed content converges, safe merge retains the later remote content and ancestry, and overlapping edits remain available for review.
This commit is contained in:
1 parent
935511c69b
commit
b449dfd2bb
16 files changed
+1583
-292
No files matched your search
@@ -143,9 +143,30 @@ policy-approved skip before the manager can acknowledge either safely.
|
||||
|
||||
A crash after the database write but before snapshot removal can replay an
|
||||
operation. Replay must check current storage and revision provenance, retain
|
||||
the existing protection against stale restored events, and avoid duplicate
|
||||
revisions or deletion of a newer same-path file. It must be safe to interrupt
|
||||
replay again. Existing saved snapshots remain readable.
|
||||
the existing protection against stale restored events, and never delete a
|
||||
newer same-path file. Once both the database write and provenance write have
|
||||
completed, replay must not add another revision. If the database write
|
||||
succeeded before provenance was recorded, replay may first create an identical
|
||||
sibling even when no remote descendant has arrived. In the tested case
|
||||
without a remote edit, replay creates that sibling. Duplicate handling then
|
||||
tombstones one of the identical branches and converges to one live leaf with
|
||||
the exact saved content.
|
||||
Another restart must add no revision. Replay must remain safe to interrupt;
|
||||
existing saved snapshots remain readable.
|
||||
|
||||
The database write and the device-local provenance write are separate,
|
||||
sequential operations. A stop between them can leave the previous provenance
|
||||
record in place. This pre-provenance gap is the known exception to the
|
||||
no-extra-revision result after both writes complete: replay can first create a
|
||||
duplicate sibling; one of the identical branches is then tombstoned while
|
||||
one live leaf retains the saved bytes when no remote descendant has arrived. If continuous
|
||||
replication advances the local database during the gap, replay can instead
|
||||
expose the local content as a sibling of that descendant. The [conflict
|
||||
resolution specification](../specs_conflict_resolution.md#known-potentially-problematic-behaviour)
|
||||
records the required mergeable and manual-resolution outcomes. The per-file
|
||||
lock does not fence replication writes. The interruption window is expected
|
||||
to be very rare, but its field frequency is unmeasured; this decision adds no
|
||||
transaction or second journal to close the interval.
|
||||
|
||||
Boolean failure, an exception, and an unavailable comparison are not successful
|
||||
completion. Keep unresolved work recoverable and report the failure through the
|
||||
@@ -202,6 +223,14 @@ outcomes through the ordinary non-forced file handler and its provenance rules:
|
||||
| Vault content has no provable origin and matches no current live leaf | Preserve it according to the existing independent-branch rules. Do not attach it to an arbitrary database winner. |
|
||||
| Required content or provenance cannot be read, or state changes during comparison | Retain unresolved work and report or re-evaluate it. Do not mark it reconciled merely because the timestamp comparison is `EVEN`. |
|
||||
|
||||
The table describes stable-state reconciliation, not atomic database and
|
||||
provenance persistence. Replay in the pre-provenance gap may create an
|
||||
identical sibling; with no remote descendant, one of the identical branches
|
||||
is tombstoned, leaving one live leaf with the exact saved content. If replication has
|
||||
already added a descendant, preserve its exact content through an existing
|
||||
safe merge, or retain both branches for manual resolution. See [Known
|
||||
potentially problematic behaviour](../specs_conflict_resolution.md#known-potentially-problematic-behaviour).
|
||||
|
||||
Revalidate the relevant file and database state before acting on a comparison.
|
||||
Reuse the existing content and provenance checks; avoid a separate conflict
|
||||
algorithm in the scanner. Metadata continues to reference Chunks containing the
|
||||
@@ -333,7 +362,9 @@ matrix is:
|
||||
| Scenario | Required observation |
|
||||
| -------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Stop after dequeue, timer release, or during a database write | Pending work remains recoverable; restart eventually represents the saved Vault edit. |
|
||||
| Database write succeeds before snapshot cleanup; restart twice | Replay creates no duplicate revision and preserves later edits. |
|
||||
| Database and provenance writes are complete before replay; restart twice | Replay adds no extra revision. |
|
||||
| Stop after the database write but before provenance; no remote descendant; replay twice | The tested replay creates an identical sibling and tombstones one of the two branches; one live leaf retains exact saved content, and the second restart adds no revision. |
|
||||
| A remote descendant arrives during the pre-provenance gap | The mergeable case preserves its exact content and ancestry; the overlapping case retains both bodies for manual resolution. |
|
||||
| Old and new events share a path; snapshot writes overlap | Completing old work cannot remove new work or regress the durable snapshot. |
|
||||
| Handler returns false, throws, or snapshot persistence fails | Flush reports failure; pending work is retained; unrelated recoverable work can continue. |
|
||||
| Buffered or in-progress work exists with no waiting timer | Flush still waits for actual completion. |
|
||||
|
||||
@@ -166,6 +166,49 @@ For ordinary saves and incoming reflection, a missing or unreadable recorded bas
|
||||
|
||||
Provenance keys follow the selected [Unicode path identity](design_docs/unicode_path_identity.md#state-which-follows-the-selected-identity). In NFC mode, equivalent path spellings address the same record; the content evidence continues to describe file bytes, independently of that path spelling.
|
||||
|
||||
## Known potentially problematic behaviour
|
||||
|
||||
Saving a local file writes its revision to the local database, then writes
|
||||
device-local provenance in a separate operation. The writes are not atomic.
|
||||
If the process stops between them, provenance can still identify the revision
|
||||
which preceded the local edit. Continuous replication which was already
|
||||
running can add a remote descendant to the local database during this
|
||||
interval. The per-file lock covers file handling and Vault reflection; it
|
||||
does not block raw replication writes to the database.
|
||||
|
||||
For example, local content `2-B` may have been saved as a child of
|
||||
displayed revision `1`, while provenance still identifies `1`.
|
||||
On restart, replay of the pending save can treat `2-B` as an edit of
|
||||
`1` and write sibling `2-D`. The tested case demonstrates that this
|
||||
pre-provenance gap alone can produce the duplicate. Without a remote
|
||||
descendant, replay creates this sibling; duplicate handling tombstones one
|
||||
of the identical branches and converges to one live leaf whose exact content
|
||||
matches the saved local file. A second restart must add no revision.
|
||||
|
||||
If replication has already added descendant `3-C` during the gap, replay
|
||||
can expose an additional branch. When the revisions have a complete shared
|
||||
base and their text changes can be combined unambiguously, sensible merge can retain the
|
||||
exact content of the incoming descendant. In the tested fixture, merge
|
||||
produced revision `4` as a child of `3-C`; its file bytes were exactly
|
||||
those of `3-C`, `3-C` remained in its ancestry, and sibling
|
||||
`2-D` was tombstoned. The acceptance condition is retaining
|
||||
`3-C`'s exact content; it need not remain the current leaf. Both Vaults
|
||||
converged to those bytes. This observed outcome is limited to that mergeable
|
||||
fixture and is not a universal no-data-loss guarantee.
|
||||
|
||||
When changes cannot be combined safely, as in the tested competing whole-line
|
||||
replacements, sensible merge does not combine the bodies. Both versions remain available for the existing
|
||||
manual conflict dialogue, even when sensible merge is enabled.
|
||||
|
||||
An interruption in the database/provenance interval is expected to be very
|
||||
rare, especially when combined with a remote descendant arriving in that
|
||||
interval; the field frequency is unmeasured. Start-up replays restored work,
|
||||
scans, and commits pending local file work before marking the plug-in ready;
|
||||
ordinary replication proceeds after that ready boundary. This does not claim
|
||||
remote synchronisation before start-up readiness. The accepted design adds no
|
||||
cross-store transaction, second journal, or new persistent state to close the
|
||||
interval.
|
||||
|
||||
## Operations while a conflict exists
|
||||
|
||||
- Editing a file writes a child of its recorded or uniquely reconstructed displayed revision.
|
||||
|
||||
Reference in new issue
Block a user