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:
vorotamoroz committed 2026-10-26 13:35:14 +00:00
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. |
+43
View File
@@ -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.