Add explicit stopped-Journal recovery to Obsidian and CLI

Offer a confirmation in Maintenance and the journal-skip command to skip
only the current stopped Journal and resume receipt. Keep Commonlib notices
visible on stderr during ordinary CLI use.

Document the missing-content risk and replay procedure, and cover
cancellation, stale failures, subsequent failures, and receipt with unit
and plain and encrypted CLI and Obsidian end-to-end tests.

Requires the Commonlib stopped-Journal recovery API. Adopt its exact
published package version before integrating this consumer change.
This commit is contained in:
vorotamoroz committed 2026-11-04 15:25:30 +00:00
1 parent bf2241e5ee
commit a94c3fef90
18 files changed
+1321 -234

No files matched your search

+10
View File
@@ -1,5 +1,15 @@
## The design document of the Journal Replicator 2nd Edition
Implementation note: the receive-failure correction and single-Journal skip
action are unreleased. Their owning contract is Commonlib's
[Journal receive failures and recovery](https://github.com/vrtmrz/livesync-commonlib/blob/main/docs/journal-receive-recovery.md).
The receiver acknowledges successful processing, stops on failure by default,
and retries from that Journal with the same database. Explicit skipping does
not establish Vault reflection success. The host action names one stopped
Journal and its failure stage, requires confirmation, and resumes receipt after
skipping that Journal; the next failure still stops. The [settings reference](settings.md#skip-stopped-journal-and-resume)
describes the host control and replay operation.
### Goal
- Build a robust and memory-efficient replication foundation that decouples the physical storage layer by leveraging the Web Streams API.
- Maintain strict compliance with the data consistency and replication protocols of CouchDB/PouchDB.
+19 -1
View File
@@ -1273,9 +1273,27 @@ Disables all synchronisation and restart.
Explicitly resend all locally available chunks to the remote. This is a recovery and maintenance operation; ordinary replication does not pre-send every chunk.
#### Skip stopped Journal and resume
Object Storage only. If a stopped Journal is not available, restart replication
normally with the same local database so the receive failure identifies its key
and stage. Confirming this action skips only that Journal and resumes receipt;
it does not skip the rest of the remote history. The next Journal failure still
stops replication.
Skipping may leave content or history missing. Normal replication does not
retry a Journal which has been explicitly skipped. After correcting the cause,
use **Reset journal received history** to replay retained remote Journals,
except those sent by this device. It cannot restore Journals which are no
longer available remotely. This action does not add a persistent ignore setting.
#### Reset journal received history
Initialise journal received history. On the next sync, every item except this device sent will be downloaded again.
Clear this device's received Journal history and known-document transfer
records. The next sync downloads the retained remote Journals again, except
those sent by this device. The local database, Vault files, and sent history
are retained. Recovery requires intact remote data and a working local
database; resetting history does not recreate missing remote content.
#### Reset journal sent history
+23
View File
@@ -47,6 +47,29 @@ Do not switch to P2P or reset the database as the first response. Check:
If the remote is healthy but one device's local database is not, use [Reset Synchronisation on This Device](recovery.md#reset-synchronisation-on-this-device) only after backing up unsynchronised local files.
## Object Storage stops at a Journal receive failure
The receiver stops when a Journal cannot be processed or its records cannot be
saved. Correct the reported cause, then retry replication with the same local
database; the failed Journal is retried. If the stopped Journal is no longer
available to the active replicator, run normal replication again to identify
the current failure.
If the Journal cannot be recovered and missing content or history is
acceptable, open **Maintenance → Syncing → Skip stopped Journal and resume**.
The confirmation names the exact Journal key and failure stage. Confirming
skips only that Journal and resumes receipt; the next Journal failure stops
replication again. Use this only when the missing content or history is
acceptable. See the [setting reference](settings.md#skip-stopped-journal-and-resume).
**Reset journal received history** replays remote Journals that are still
available, except those sent by this device. It retains local data and this
device's sent history, and cannot restore remote Journals which are missing.
Check the resulting file contents and retained history; a completed receive
after skipping does not prove that every Vault file is readable. CLI Fetch
replaces its local database and has separate [interrupted reconstruction
rules](../src/apps/cli/README.md#interrupted-reconstruction-and-older-runtime-state).
## An unchanged file appears as a conflict after restart
If the log says `Preserved unsynchronised local changes as a conflict`, keep both versions available until you have checked their contents. The message means that LiveSync could not prove that the Vault file was unchanged; it does not establish that you edited the file. Use **Inspect conflicts and file/database differences** in Hatch to review the current branches before selecting a version.