Merge main into fix/issue-102-format-version

Issue #101: catalog.log: cut a partial append back before retrying

crates/catalog/src/journal.rs

@@ -1,8 +1,9 @@
 //! Crash-safe catalog persistence: an append-only op log plus periodic snapshots.
 //!
 //! Files (in a [`Store`]):
-//! - `catalog.snap` — `{"format":"lightcraft-catalog","version":1,"seq":N,"catalog":{…}}`, the
-//!   state after op `N`; replaced atomically (temp + fsync + rename).
+//! - `catalog.snap` — `{"format":"lightcraft-catalog","version":V,"seq":N,"catalog":{…}}`, the
+//!   state after op `N` in catalog format `V` ([`VERSION`]); replaced atomically (temp + fsync +
+//!   rename).
 //! - `catalog.log` — JSON lines, one per op applied after the snapshot:
 //!   `{"seq":N,"crc":C,"op":{…}}` where `C` is the CRC-32 of the op's JSON text. Appends are
 //!   fsynced before [`Journal::append`] returns.
@@ -10,6 +11,12 @@
 //! Loading = snapshot + replay of the records with `seq > snapshot seq`. Recovery rules:
 //! - a **torn final record** (crash mid-append: truncated line or bad CRC at the end) is dropped
 //!   and the file is cut back to the last good record, so later appends start on a clean line;
+//! - a **failed append** (disk full, a dropped network share) may leave part of its batch in the
+//!   file: [`Journal::append`] cuts the log back to the last whole record before returning the
+//!   error (or, if that fails too, before the next append), so the retry — the same ops with the
+//!   same `seq`s — starts on a clean line. Logs written by builds without that cut-back hold the
+//!   fragment glued to the first retried record on one line; the loader recognises the whole,
+//!   CRC-valid record at the end of such a line and skips only the fragment;
 //! - records already covered by the snapshot (crash between writing the snapshot and resetting
 //!   the log) are skipped;
 //! - a bad record **followed by good ones** is real damage: replay stops there, the log is kept
@@ -27,6 +34,32 @@
 //!
 //! At most one snapshot is in flight; a synchronous [`Journal::snapshot`] and dropping the journal
 //! first wait for it, so an older snapshot can never replace a newer one.
+//!
+//! # Format versions
+//!
+//! The snapshot's `version` is the catalog format, and it covers the log beside it: the log has
+//! no header of its own, and is only ever appended to under a snapshot of this build's format.
+//!
+//! | Version | Written by | Adds |
+//! |---|---|---|
+//! | (none) | early builds: a log without a snapshot | |
+//! | 1 | up to v0.2.0 | |
+//! | 2 | after v0.2.0 | `Op::SetBrowsed`, `Catalog.browsed`, `Photo.local_baseline` |
+//!
+//! Rules:
+//! - **Bump [`VERSION`]** (and add a row above) in the change that adds an [`Op`] variant or a
+//!   serialized field to the catalog, a photo, an album, a stack or develop settings that an older
+//!   build would misread or silently drop. New fields must deserialize from older data
+//!   (`#[serde(default)]`), so newer builds keep reading every older format.
+//! - **Opening an older format upgrades it**: right after loading, [`Journal::open`] writes a
+//!   snapshot in this build's format (also for a new library), before anything is appended — so a
+//!   library is never a mix, and older builds refuse it from then on instead of reading part of it.
+//!   [`LoadReport::upgraded_from`] says when that happened.
+//! - **A newer format is refused, untouched**: a snapshot whose `version` is above [`VERSION`],
+//!   or a log record whose CRC matches (so it is exactly what was written) but whose op doesn't
+//!   parse, fails [`Journal::open`] with [`CatalogError::Newer`] before any file is modified — it
+//!   is never mistaken for a torn tail or damage. (Builds up to v0.2.0 refuse a v2 snapshot with
+//!   "unsupported format".)
 
 use crate::store::Store;
 use crate::{Catalog, CatalogError, Op, Result};
@@ -34,7 +67,9 @@ use crate::{Catalog, CatalogError, Op, Result};
 pub const SNAPSHOT: &str = "catalog.snap";
 pub const LOG: &str = "catalog.log";
 const FORMAT: &str = "lightcraft-catalog";
-const VERSION: u32 = 1;
+/// The catalog format this build writes (and the newest it reads). See the module docs →
+/// *Format versions*; bump it whenever an [`Op`] variant or a serialized field is added.
+pub const VERSION: u32 = 2;
 
 /// When [`Journal::wants_snapshot`] says it's time to compact the log.
 #[derive(Clone, Copy, Debug)]
@@ -62,10 +97,16 @@ pub struct LoadReport {
     pub failed: usize,
     /// Bytes of a torn final record that were dropped.
     pub torn_bytes: u64,
+    /// Partial records left mid-log by a failed append that was retried (written by builds that
+    /// didn't cut the log back after a failed write): skipped, the retried records were replayed.
+    pub torn_fragments: usize,
     /// The damaged log was preserved under this name.
     pub damaged: Option<String>,
     /// No catalog files existed (a new library).
     pub created: bool,
+    /// The library was in an older catalog format (`0` = before format versions: a log without a
+    /// snapshot) and was rewritten in this version's format ([`VERSION`]).
+    pub upgraded_from: Option<u32>,
 }
 
 /// Where persistence time goes (reported by `library.info` → `persistence`; printed to stderr
@@ -140,6 +181,9 @@ pub struct Journal {
     pending: Option<Pending>,
     /// After a failed background snapshot: don't retry before the log has this many records.
     retry_at_records: u64,
+    /// A failed append may have left part of its records after `log_bytes`, and cutting them off
+    /// failed too: the next append cuts the log back to `log_bytes` first.
+    tail_dirty: bool,
 }
 
 /// A background snapshot in flight.
@@ -168,18 +212,58 @@ pub fn encode_record(seq: u64, op: &Op) -> String {
     format!("{{\"seq\":{seq},\"crc\":{crc},\"op\":{body}}}")
 }
 
-/// Parse one log line (without the newline). `None` if it's malformed or the CRC doesn't match.
+/// Parse one log line (without the newline). `None` if it's malformed, the CRC doesn't match, or
+/// the op is one this version doesn't know (see [`Journal::open`]).
 pub fn decode_record(line: &str) -> Option<(u64, Op)> {
-    let rest = line.strip_prefix("{\"seq\":")?;
-    let (seq, rest) = rest.split_once(",\"crc\":")?;
-    let (crc, rest) = rest.split_once(",\"op\":")?;
-    let body = rest.strip_suffix('}')?;
-    let seq: u64 = seq.parse().ok()?;
-    let crc: u32 = crc.parse().ok()?;
-    if crc32fast::hash(body.as_bytes()) != crc {
-        return None;
+    match decode_line(line) {
+        Line::Record(seq, op) => Some((seq, op)),
+        Line::Newer(_) | Line::Bad => None,
     }
-    serde_json::from_str(body).ok().map(|op| (seq, op))
+}
+
+/// One log line, decoded.
+enum Line {
+    Record(u64, Op),
+    /// The CRC matches — the line is exactly what was written — but the op doesn't parse: it
+    /// was written by a newer LightCraft (an op or field this version doesn't know), not damaged.
+    Newer(u64),
+    /// Malformed or a CRC mismatch: torn or damaged.
+    Bad,
+}
+
+fn decode_line(line: &str) -> Line {
+    let parts = || {
+        let rest = line.strip_prefix("{\"seq\":")?;
+        let (seq, rest) = rest.split_once(",\"crc\":")?;
+        let (crc, rest) = rest.split_once(",\"op\":")?;
+        let body = rest.strip_suffix('}')?;
+        Some((seq.parse::<u64>().ok()?, crc.parse::<u32>().ok()?, body))
+    };
+    let Some((seq, crc, body)) = parts() else { return Line::Bad };
+    if crc32fast::hash(body.as_bytes()) != crc {
+        return Line::Bad;
+    }
+    match serde_json::from_str(body) {
+        Ok(op) => Line::Record(seq, op),
+        Err(_) => Line::Newer(seq),
+    }
+}
+
+/// The error for a library written by a newer LightCraft.
+fn newer(what: String) -> CatalogError {
+    CatalogError::Newer(format!("{what}; this version reads catalog format v{VERSION} and older"))
+}
+
+/// A line that doesn't decode but ends with a whole record: a fragment of a failed append followed
+/// by the record that retried it (the retry re-encodes the same ops with the same `seq`s). Returns
+/// the fragment's length and the record, if that record continues the log (`seq <= last + 1`).
+/// The record's CRC must match, so damage is never mistaken for it.
+fn resync(line: &[u8], last: u64) -> Option<(usize, (u64, Op))> {
+    const START: &[u8] = b"{\"seq\":";
+    (1..line.len().saturating_sub(START.len() - 1)).filter(|&i| line[i..].starts_with(START)).find_map(|i| {
+        let rec = std::str::from_utf8(&line[i..]).ok().map(|l| l.trim_end_matches('\r')).and_then(decode_record)?;
+        (rec.0 <= last + 1).then_some((i, rec))
+    })
 }
 
 /// Write `catalog.snap` for the state after op `seq`, streaming the JSON into the store (no
@@ -205,10 +289,16 @@ fn write_snapshot(store: &mut dyn Store, seq: u64, catalog: &Catalog) -> std::io
     Ok(SnapshotTiming { serialize_ms, write_sync_ms: (ms_since(t0) - serialize_ms).max(0.0), bytes, ..Default::default() })
 }
 
+/// Just the identification of `catalog.snap` (read before the catalog itself).
 #[derive(serde::Deserialize)]
-struct SnapFile {
+struct SnapHeader {
     format: String,
     version: u32,
+}
+
+/// The whole `catalog.snap` (after [`SnapHeader`] was checked; `format` and `version` are ignored).
+#[derive(serde::Deserialize)]
+struct SnapFile {
     seq: u64,
     catalog: Catalog,
 }
@@ -221,15 +311,20 @@ impl Journal {
         let snap = store.read(SNAPSHOT).map_err(io)?;
         let log = store.read(LOG).map_err(io)?;
         report.created = snap.is_none() && log.is_none();
-        let (mut catalog, snapshot_seq) = match snap {
+        let (mut catalog, snapshot_seq, snapshot_version) = match snap {
             Some(bytes) => {
-                let s: SnapFile = serde_json::from_slice(&bytes).map_err(|e| CatalogError::Corrupt(format!("{SNAPSHOT}: {e}")))?;
-                if s.format != FORMAT || s.version > VERSION {
-                    return Err(CatalogError::Corrupt(format!("{SNAPSHOT}: unsupported format {} v{}", s.format, s.version)));
+                // the header first: a newer snapshot may not parse as this version's catalog
+                let h: SnapHeader = serde_json::from_slice(&bytes).map_err(|e| CatalogError::Corrupt(format!("{SNAPSHOT}: {e}")))?;
+                if h.format != FORMAT {
+                    return Err(CatalogError::Corrupt(format!("{SNAPSHOT}: not a LightCraft catalog (format {:?})", h.format)));
                 }
-                (s.catalog, s.seq)
+                if h.version > VERSION {
+                    return Err(newer(format!("{SNAPSHOT} is catalog format v{}", h.version)));
+                }
+                let s: SnapFile = serde_json::from_slice(&bytes).map_err(|e| CatalogError::Corrupt(format!("{SNAPSHOT}: {e}")))?;
+                (s.catalog, s.seq, Some(h.version))
             }
-            None => (Catalog::new(), 0),
+            None => (Catalog::new(), 0, None),
         };
         report.snapshot_seq = snapshot_seq;
         let mut j = Journal {
@@ -242,6 +337,7 @@ impl Journal {
             stats: PersistStats::default(),
             pending: None,
             retry_at_records: 0,
+            tail_dirty: false,
         };
         let log = log.unwrap_or_default();
 
@@ -261,7 +357,22 @@ impl Journal {
                 good_end = next;
                 continue;
             }
-            match line.and_then(decode_record) {
+            let mut record = line.and_then(decode_record);
+            if record.is_none()
+                && let Some((at, r)) = resync(&log[pos..line_end], j.seq)
+            {
+                // the torn start of a failed append, then the retried records (older builds
+                // appended them right after the fragment)
+                log::warn!("catalog log: skipped a partial record ({at} bytes) left by a failed write");
+                report.torn_fragments += 1;
+                record = Some(r);
+            }
+            if record.is_none()
+                && let Some(Line::Newer(seq)) = line.map(decode_line)
+            {
+                return Err(newer(format!("{LOG} record {seq} holds a change this version doesn't know")));
+            }
+            match record {
                 Some((seq, op)) if seq <= j.seq => {
                     // already in the snapshot
                     let _ = op;
@@ -277,7 +388,15 @@ impl Journal {
                 }
                 _ => {
                     // bad record (or a gap): torn tail if nothing good follows, else damage
-                    let rest_has_good = log[next..].split(|b| *b == b'\n').any(|l| std::str::from_utf8(l).ok().and_then(decode_record).is_some());
+                    let mut rest_has_good = false;
+                    for l in log[next..].split(|b| *b == b'\n') {
+                        match std::str::from_utf8(l).map(|l| decode_line(l.trim_end_matches('\r'))) {
+                            Ok(Line::Record(..)) => rest_has_good = true,
+                            // refused before anything is modified
+                            Ok(Line::Newer(seq)) => return Err(newer(format!("{LOG} record {seq} holds a change this version doesn't know"))),
+                            Ok(Line::Bad) | Err(_) => {}
+                        }
+                    }
                     if rest_has_good {
                         damaged_at = Some(pos);
                     }
@@ -301,10 +420,34 @@ impl Journal {
                 report.torn_bytes = (log.len() - good_end) as u64;
                 log::warn!("catalog log: dropped a torn final record ({} bytes)", report.torn_bytes);
                 j.store.truncate(LOG, good_end as u64).map_err(io)?;
+                j.log_bytes = good_end as u64;
             } else if needs_newline {
                 j.store.append(LOG, b"\n").map_err(io)?;
+                j.log_bytes = good_end as u64 + 1;
+            } else {
+                j.log_bytes = good_end as u64;
+            }
+        }
+        // Bring an older (or new, or snapshot-less) library to this version's format before
+        // anything is appended: a snapshot in this format makes older builds refuse the library
+        // instead of misreading ops or dropping fields they don't know.
+        if report.created {
+            // tiny: written directly, not counted as a compaction
+            let empty = format!("{{\"format\":\"{FORMAT}\",\"version\":{VERSION},\"seq\":0,\"catalog\":{}}}\n", catalog.to_snapshot());
+            if let Err(e) = j.store.write_atomic(SNAPSHOT, empty.as_bytes()) {
+                log::warn!("catalog: can't write the new library's snapshot: {e}");
+            }
+        } else if report.damaged.is_none() && snapshot_version != Some(VERSION) {
+            report.upgraded_from = Some(snapshot_version.unwrap_or(0));
+            match j.snapshot(&catalog) {
+                Ok(()) => {
+                    if let Some(v) = report.upgraded_from {
+                        log::info!("catalog: upgraded from format v{v} to v{VERSION}");
+                    }
+                }
+                // nothing lost: the old files are intact and still load; retried on next open
+                Err(e) => log::warn!("catalog: can't write the format v{VERSION} snapshot: {e}"),
             }
-            j.log_bytes = good_end as u64;
         }
         catalog.revision = 0;
         Ok((j, catalog, report))
@@ -323,7 +466,20 @@ impl Journal {
             buf.push_str(&encode_record(seq, op));
             buf.push('\n');
         }
-        self.store.append(LOG, buf.as_bytes()).map_err(io)?;
+        if self.tail_dirty {
+            self.store.truncate(LOG, self.log_bytes).map_err(io)?;
+            self.tail_dirty = false;
+        }
+        if let Err(e) = self.store.append(LOG, buf.as_bytes()) {
+            // Part of the batch may be in the file. Cut it back to the last whole record, so the
+            // retry (same seqs) starts on a clean line instead of after a fragment that would
+            // read back as damage.
+            if let Err(t) = self.store.truncate(LOG, self.log_bytes) {
+                log::error!("catalog: can't cut the log back after a failed append: {t}");
+                self.tail_dirty = true;
+            }
+            return Err(io(e));
+        }
         if let Some(p) = self.pending.as_mut() {
             p.tail.extend_from_slice(buf.as_bytes());
             p.tail_records += ops.len() as u64;
@@ -343,12 +499,22 @@ impl Journal {
 
     /// Write a snapshot of `catalog` (which must reflect every appended op) and reset the log.
     pub fn snapshot(&mut self, catalog: &Catalog) -> Result<()> {
+        self.snapshot_with_unlogged(catalog, 0)
+    }
+
+    /// [`Journal::snapshot`] of a catalog that also reflects `unlogged` ops applied after the
+    /// last appended one but never written to the log (their append failed). The snapshot counts
+    /// them (it holds the state after op `seq + unlogged`), so they are saved and must not be
+    /// appended afterwards. Once the snapshot is durable [`Journal::seq`] includes them, even if
+    /// resetting the log then fails (the error is still returned).
+    pub fn snapshot_with_unlogged(&mut self, catalog: &Catalog, unlogged: u64) -> Result<()> {
         // never two snapshot writers; the one in flight is older, so it must land first
         if let Err(e) = self.wait() {
             log::warn!("catalog: background snapshot failed ({e}); writing one now");
         }
         let t0 = web_time::Instant::now();
-        let mut timing = match write_snapshot(self.store.as_mut(), self.seq, catalog) {
+        let seq = self.seq + unlogged;
+        let mut timing = match write_snapshot(self.store.as_mut(), seq, catalog) {
             Ok(t) => t,
             Err(e) => {
                 // nothing lost (the log is whole); don't retry on every append
@@ -357,6 +523,9 @@ impl Journal {
                 return Err(io(e));
             }
         };
+        // the snapshot is durable: it holds every op up to `seq`
+        self.seq = seq;
+        self.snapshot_seq = seq;
         let t2 = web_time::Instant::now();
         // A crash here leaves old records in the log; they are skipped by seq on load.
         self.store.write_atomic(LOG, b"").map_err(io)?;
@@ -365,10 +534,10 @@ impl Journal {
         timing.blocking_ms = timing.total_ms;
         timing.records = self.log_records;
         self.record_snapshot(timing);
-        self.snapshot_seq = self.seq;
         self.log_records = 0;
         self.log_bytes = 0;
         self.retry_at_records = 0;
+        self.tail_dirty = false;
         Ok(())
     }
 
@@ -459,6 +628,7 @@ impl Journal {
         self.log_records = p.tail_records;
         self.log_bytes = p.tail.len() as u64;
         self.retry_at_records = 0;
+        self.tail_dirty = false;
         Ok(())
     }
 

crates/catalog/src/lib.rs

@@ -5,6 +5,11 @@
 //!   snapshot — crash-safe and diff-friendly (see [`journal`]);
 //! - **undo/redo**: the engine keeps inverse ops;
 //! - **determinism**: replaying the log reproduces the state exactly (property-tested).
+//!
+//! **Catalog format version** ([`journal::VERSION`], see [`journal`] → *Format versions*): adding
+//! an [`Op`] variant or a serialized field means bumping it. Newer builds read every older format
+//! (and upgrade it on open); older builds refuse a newer library with [`CatalogError::Newer`]
+//! instead of reading part of it.
 #![forbid(unsafe_code)]
 #![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
 
@@ -47,6 +52,10 @@ pub enum CatalogError {
     Corrupt(String),
     #[error("catalog storage: {0}")]
     Io(String),
+    /// The library was written by a newer LightCraft (a newer catalog format, or a change this
+    /// version doesn't know). Nothing was read into the session and nothing was modified.
+    #[error("this library was written by a newer version of LightCraft ({0}); update LightCraft to open it. The library was left unchanged.")]
+    Newer(String),
 }
 
 pub type Result<T> = std::result::Result<T, CatalogError>;
@@ -644,6 +653,10 @@ mod tests;
 #[cfg(test)]
 mod tests_background;
 #[cfg(test)]
+mod tests_format_version;
+#[cfg(test)]
 mod tests_journal;
 #[cfg(test)]
 mod tests_local;
+#[cfg(test)]
+mod tests_torn_append;

crates/catalog/src/store.rs

@@ -28,9 +28,12 @@ pub trait Store: Send {
         self.write_atomic(name, &buf)?;
         Ok(buf.len() as u64)
     }
-    /// Append and make durable (fsync) before returning.
+    /// Append and make durable (fsync) before returning. On an error, part of `data` may have
+    /// been written (a full disk, a dropped network share): the journal cuts the file back to its
+    /// previous length with [`Store::truncate`] before appending again.
     fn append(&mut self, name: &str, data: &[u8]) -> io::Result<()>;
-    /// Cut a file to `len` bytes (drop a torn tail before appending again).
+    /// Cut a file to `len` bytes (drop a torn tail before appending again). A missing file is
+    /// left missing.
     fn truncate(&mut self, name: &str, len: u64) -> io::Result<()>;
     /// Human-readable location (diagnostics).
     fn describe(&self) -> String;
@@ -132,15 +135,26 @@ impl Store for FsStore {
             self.appender = Some((name.to_string(), f));
         }
         let Some((_, f)) = self.appender.as_mut() else { return Err(io::Error::other("appender not open")) };
-        f.write_all(data)?;
-        f.sync_data()
+        let written = f.write_all(data).and_then(|()| f.sync_data());
+        if written.is_err() {
+            // The handle may be dead (a network share that reconnected, a removed volume): the next
+            // attempt reopens the file. Part of `data` may be in the file; the caller cuts it back
+            // ([`Store::truncate`]) before appending again.
+            self.appender = None;
+        }
+        written
     }
 
     fn truncate(&mut self, name: &str, len: u64) -> io::Result<()> {
         if self.appender.as_ref().is_some_and(|(n, _)| n == name) {
             self.appender = None;
         }
-        let f = std::fs::OpenOptions::new().write(true).open(self.path(name))?;
+        let f = match std::fs::OpenOptions::new().write(true).open(self.path(name)) {
+            Ok(f) => f,
+            // nothing to cut (an append that failed before creating the file)
+            Err(e) if e.kind() == io::ErrorKind::NotFound => return Ok(()),
+            Err(e) => return Err(e),
+        };
         f.set_len(len)?;
         f.sync_all()
     }

crates/catalog/src/tests_background.rs

@@ -180,7 +180,8 @@ fn failed_background_snapshot_loses_nothing_and_retries_later() {
     wait_written(&j);
     assert!(j.poll().is_err());
     assert_eq!((j.snapshot_seq(), j.stats().failed_snapshots), (0, 1));
-    assert!(g.files.get(SNAPSHOT).is_none());
+    // still the (empty) snapshot written when the library was created
+    assert_eq!(g.snapshot_seq_on_disk(), Some(0));
     assert_recovers(&g, &live);
     // no retry storm: the next attempt waits for another `max_records` records
     assert!(!j.wants_snapshot());

crates/catalog/src/tests_format_version.rs

@@ -0,0 +1,186 @@
+//! Issue #102: catalog format versions. Older formats load and are upgraded; a newer format is
+//! refused with a clear error and left untouched (never read in part, truncated or set aside).
+
+use crate::journal::{LOG, SNAPSHOT, VERSION, encode_record};
+use crate::*;
+
+fn photo(c: &mut Catalog) -> Op {
+    let id = c.alloc_photo_id();
+    Op::AddPhoto { photo: Box::new(Photo::new(id, Source::File { path: format!("/p/{}.jpg", id.0) }, "p.jpg", "JPEG", 4, 3, "2026-01-01")) }
+}
+
+/// A catalog with two photos and the log line for a third op on top of it.
+fn legacy_parts() -> (Catalog, String, Catalog) {
+    let mut c = Catalog::new();
+    for _ in 0..2 {
+        let op = photo(&mut c);
+        c.apply(op).unwrap();
+    }
+    let base = c.clone();
+    let id = c.photos().next().unwrap().id;
+    let op = Op::SetRating { id, rating: 4 };
+    c.apply(op.clone()).unwrap();
+    (base, format!("{}\n", encode_record(3, &op)), c)
+}
+
+fn snapshot_version(m: &MemStore) -> u64 {
+    let v: serde_json::Value = serde_json::from_slice(&m.get(SNAPSHOT).unwrap()).unwrap();
+    v["version"].as_u64().unwrap()
+}
+
+#[test]
+fn v1_library_loads_and_is_upgraded() {
+    let (base, log, full) = legacy_parts();
+    let m = MemStore::new();
+    m.set(SNAPSHOT, format!("{{\"format\":\"lightcraft-catalog\",\"version\":1,\"seq\":2,\"catalog\":{}}}\n", base.to_snapshot()).into_bytes());
+    m.set(LOG, log.into_bytes());
+    let (mut j, c, r) = Journal::open(Box::new(m.clone())).unwrap();
+    assert_eq!(c.to_snapshot(), full.to_snapshot());
+    assert_eq!((r.replayed, r.upgraded_from), (1, Some(1)));
+    // rewritten in this format before anything is appended
+    assert_eq!(snapshot_version(&m), u64::from(VERSION));
+    assert!(m.get(LOG).unwrap().is_empty());
+    assert_eq!(j.seq(), 3);
+    j.append(&[Op::SetLabelName { label: ColorLabel::ALL[0], name: Some("x".into()) }]).unwrap();
+    drop(j);
+    let (_, _, r) = Journal::open(Box::new(m)).unwrap();
+    assert_eq!((r.replayed, r.upgraded_from), (1, None));
+}
+
+#[test]
+fn versionless_log_only_library_is_upgraded() {
+    let mut c = Catalog::new();
+    let op = photo(&mut c);
+    c.apply(op.clone()).unwrap();
+    let m = MemStore::new();
+    m.set(LOG, format!("{}\n", encode_record(1, &op)).into_bytes());
+    let (_, loaded, r) = Journal::open(Box::new(m.clone())).unwrap();
+    assert_eq!(loaded.to_snapshot(), c.to_snapshot());
+    assert_eq!(r.upgraded_from, Some(0));
+    assert_eq!(snapshot_version(&m), u64::from(VERSION));
+}
+
+/// A new library gets a snapshot in this format at once, so an older build never sees a bare log
+/// it would read in part.
+#[test]
+fn new_library_is_written_in_this_format() {
+    let m = MemStore::new();
+    let (_, _, r) = Journal::open(Box::new(m.clone())).unwrap();
+    assert!(r.created);
+    assert_eq!(r.upgraded_from, None);
+    assert_eq!(snapshot_version(&m), u64::from(VERSION));
+}
+
+fn assert_refused_untouched(m: &MemStore) {
+    let before = m.files.lock().unwrap().clone();
+    let e = Journal::open(Box::new(m.clone())).err().expect("refused");
+    assert!(matches!(e, CatalogError::Newer(_)), "{e:?}");
+    let msg = e.to_string();
+    assert!(msg.contains("newer version of LightCraft") && msg.contains("left unchanged"), "{msg}");
+    assert_eq!(*m.files.lock().unwrap(), before, "nothing modified, nothing renamed");
+}
+
+#[test]
+fn newer_snapshot_is_refused_untouched() {
+    let (base, log, _) = legacy_parts();
+    let m = MemStore::new();
+    m.set(
+        SNAPSHOT,
+        format!("{{\"format\":\"lightcraft-catalog\",\"version\":{},\"seq\":2,\"catalog\":{}}}\n", VERSION + 1, base.to_snapshot()).into_bytes(),
+    );
+    m.set(LOG, log.into_bytes());
+    assert_refused_untouched(&m);
+    // even when its catalog doesn't parse as this version's
+    let m = MemStore::new();
+    m.set(
+        SNAPSHOT,
+        format!("{{\"format\":\"lightcraft-catalog\",\"version\":{},\"seq\":2,\"catalog\":{{\"photos\":7}}}}\n", VERSION + 1).into_bytes(),
+    );
+    assert_refused_untouched(&m);
+    let e = Journal::open(Box::new(m)).err().unwrap().to_string();
+    assert!(e.contains(&format!("v{}", VERSION + 1)), "{e}");
+}
+
+/// A log record with a valid CRC whose op this version doesn't know: refused, not taken for a
+/// torn tail (truncated) or damage (renamed) — wherever it is in the log.
+#[test]
+fn unknown_op_in_the_log_is_refused_untouched() {
+    let (base, log, _) = legacy_parts();
+    let future = |seq: u64| {
+        let body = r#"{"op":"fromTheFuture","id":1,"what":"something new"}"#;
+        format!("{{\"seq\":{seq},\"crc\":{},\"op\":{body}}}\n", crc32fast::hash(body.as_bytes()))
+    };
+    let snap = format!("{{\"format\":\"lightcraft-catalog\",\"version\":{VERSION},\"seq\":2,\"catalog\":{}}}\n", base.to_snapshot());
+    let id = base.photos().next().unwrap().id;
+    let after = format!("{}\n", encode_record(5, &Op::SetRating { id, rating: 1 }));
+    for log in [format!("{log}{}", future(4)), format!("{log}{}{after}", future(4)), format!("{}{log}", future(3))] {
+        let m = MemStore::new();
+        m.set(SNAPSHOT, snap.clone().into_bytes());
+        m.set(LOG, log.into_bytes());
+        assert_refused_untouched(&m);
+    }
+    // a known op with a field of an unknown shape is "newer" too
+    let body = r#"{"op":"setRating","id":1,"rating":"five stars"}"#;
+    let m = MemStore::new();
+    m.set(SNAPSHOT, snap.into_bytes());
+    m.set(LOG, format!("{log}{{\"seq\":4,\"crc\":{},\"op\":{body}}}\n", crc32fast::hash(body.as_bytes())).into_bytes());
+    assert_refused_untouched(&m);
+}
+
+/// A CRC mismatch is still damage / a torn tail (not "newer").
+#[test]
+fn bad_crc_is_still_a_torn_tail() {
+    let (base, log, _) = legacy_parts();
+    let m = MemStore::new();
+    m.set(
+        SNAPSHOT,
+        format!("{{\"format\":\"lightcraft-catalog\",\"version\":{VERSION},\"seq\":2,\"catalog\":{}}}\n", base.to_snapshot()).into_bytes(),
+    );
+    let body = r#"{"op":"fromTheFuture"}"#;
+    m.set(LOG, format!("{log}{{\"seq\":4,\"crc\":1,\"op\":{body}}}\n").into_bytes());
+    let (_, _, r) = Journal::open(Box::new(m)).unwrap();
+    assert!(r.torn_bytes > 0 && r.damaged.is_none(), "{r:?}");
+}
+
+/// Guard for the version rule (see `journal` → *Format versions*): adding an [`Op`] variant breaks
+/// this match. When it does, bump `journal::VERSION`, add a row to the format table, and add the
+/// variant here under the new version.
+#[test]
+fn op_variants_are_versioned() {
+    fn since(op: &Op) -> u32 {
+        match op {
+            Op::AddPhoto { .. }
+            | Op::RemovePhoto { .. }
+            | Op::SetRating { .. }
+            | Op::SetFlag { .. }
+            | Op::SetLabel { .. }
+            | Op::SetDevelop { .. }
+            | Op::SetMeta { .. }
+            | Op::SetDeleted { .. }
+            | Op::SetLocal { .. }
+            | Op::SetVersions { .. }
+            | Op::SetHistory { .. }
+            | Op::PushHistory { .. }
+            | Op::AddAlbum { .. }
+            | Op::RemoveAlbum { .. }
+            | Op::RenameAlbum { .. }
+            | Op::MoveAlbum { .. }
+            | Op::SetAlbumPhotos { .. }
+            | Op::SetAlbumCover { .. }
+            | Op::SetAlbumRules { .. }
+            | Op::AddStack { .. }
+            | Op::RemoveStack { .. }
+            | Op::SetStack { .. }
+            | Op::SetCaptured { .. }
+            | Op::SetAnalysis { .. }
+            | Op::SetFile { .. }
+            | Op::Relink { .. }
+            | Op::SetContent { .. }
+            | Op::SetLabelName { .. }
+            | Op::Batch { .. } => 1,
+            Op::SetBrowsed { .. } => 2,
+        }
+    }
+    let newest = since(&Op::SetBrowsed { folder: String::new(), at: None });
+    assert_eq!(newest, VERSION, "the newest op's version must be the current format version");
+}

crates/catalog/src/tests_journal.rs

@@ -283,7 +283,12 @@ fn streamed_snapshot_keeps_the_on_disk_format() {
     let (mut j, c, _) = open(&m);
     assert_eq!(c.to_snapshot(), full.to_snapshot());
     j.snapshot(&c).unwrap();
-    let legacy = format!("{{\"format\":\"lightcraft-catalog\",\"version\":1,\"seq\":{},\"catalog\":{}}}\n", j.seq(), c.to_snapshot());
+    let legacy = format!(
+        "{{\"format\":\"lightcraft-catalog\",\"version\":{},\"seq\":{},\"catalog\":{}}}\n",
+        crate::journal::VERSION,
+        j.seq(),
+        c.to_snapshot()
+    );
     assert_eq!(String::from_utf8(m.get(SNAPSHOT).unwrap()).unwrap(), legacy);
     assert_eq!(j.stats().last_snapshot.bytes, legacy.len() as u64);
 

crates/catalog/src/tests_torn_append.rs

@@ -0,0 +1,223 @@
+//! Issue #101: an append that fails part-way (disk full, a dropped network share) and is then
+//! retried must not read back as log damage, and must lose nothing.
+
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::{Arc, Mutex};
+
+use crate::journal::LOG;
+use crate::*;
+
+/// A store whose next append writes only a prefix of its data, then fails.
+#[derive(Clone, Default)]
+struct Torn {
+    files: MemStore,
+    /// The next append writes this many bytes, then returns an error.
+    torn_at: Arc<Mutex<Option<usize>>>,
+    /// `truncate` fails (the cut-back after a failed append can't be done right away).
+    truncate_fails: Arc<AtomicBool>,
+}
+
+impl Torn {
+    fn tear_next_append(&self, bytes: usize) {
+        *self.torn_at.lock().unwrap() = Some(bytes);
+    }
+}
+
+impl Store for Torn {
+    fn read(&mut self, name: &str) -> std::io::Result<Option<Vec<u8>>> {
+        self.files.read(name)
+    }
+    fn write_atomic(&mut self, name: &str, data: &[u8]) -> std::io::Result<()> {
+        self.files.write_atomic(name, data)
+    }
+    fn append(&mut self, name: &str, data: &[u8]) -> std::io::Result<()> {
+        if let Some(n) = self.torn_at.lock().unwrap().take() {
+            self.files.append(name, &data[..n.min(data.len())])?;
+            return Err(std::io::Error::other("disk full"));
+        }
+        self.files.append(name, data)
+    }
+    fn truncate(&mut self, name: &str, len: u64) -> std::io::Result<()> {
+        if self.truncate_fails.load(Ordering::SeqCst) {
+            return Err(std::io::Error::other("share unavailable"));
+        }
+        self.files.truncate(name, len)
+    }
+    fn describe(&self) -> String {
+        "torn".into()
+    }
+}
+
+fn add_photo(c: &mut Catalog) -> Op {
+    let id = c.alloc_photo_id();
+    Op::AddPhoto { photo: Box::new(Photo::new(id, Source::File { path: format!("/p/{}.jpg", id.0) }, "p.jpg", "JPEG", 4, 3, "2026-01-01")) }
+}
+
+/// Apply `ops` to the live catalog (like a command) and return them for the journal.
+fn apply(c: &mut Catalog, ops: Vec<Op>) -> Vec<Op> {
+    for op in &ops {
+        c.apply(op.clone()).unwrap();
+    }
+    ops
+}
+
+/// Every tear position of a batch, then the retry (same ops, same seqs, like the engine's queue)
+/// and more appends: reloading replays everything, reports no damage and no torn bytes.
+#[test]
+fn partial_append_then_retry_loads_cleanly() {
+    let probe = MemStore::new();
+    let (mut j, mut c, _) = Journal::open(Box::new(probe.clone())).unwrap();
+    let add = add_photo(&mut c);
+    let first = apply(&mut c, vec![add]);
+    j.append(&first).unwrap();
+    let id = c.photos().next().unwrap().id;
+    let batch = apply(&mut c, vec![Op::SetRating { id, rating: 3 }, Op::SetFlag { id, flag: Flag::Pick }, Op::SetRating { id, rating: 4 }]);
+    let before = probe.get(LOG).unwrap().len();
+    j.append(&batch).unwrap();
+    let batch_len = probe.get(LOG).unwrap().len() - before;
+
+    for tear in 1..batch_len {
+        let t = Torn::default();
+        let (mut j, mut c, _) = Journal::open(Box::new(t.clone())).unwrap();
+        let add = add_photo(&mut c);
+        let first = apply(&mut c, vec![add]);
+        j.append(&first).unwrap();
+        let good_len = t.files.get(LOG).unwrap().len();
+        let batch = apply(&mut c, vec![Op::SetRating { id, rating: 3 }, Op::SetFlag { id, flag: Flag::Pick }, Op::SetRating { id, rating: 4 }]);
+        t.tear_next_append(tear);
+        assert!(j.append(&batch).is_err(), "tear at {tear}");
+        // cut back to the last whole record
+        assert_eq!(t.files.get(LOG).unwrap().len(), good_len, "tear at {tear}");
+        j.append(&batch).unwrap();
+        let more = apply(&mut c, vec![Op::SetLabel { id, label: Some(ColorLabel::ALL[0]) }]);
+        j.append(&more).unwrap();
+        drop(j);
+
+        let (_, loaded, r) = Journal::open(Box::new(t.clone())).unwrap();
+        assert!(r.damaged.is_none(), "tear at {tear}: {r:?}");
+        assert_eq!((r.torn_bytes, r.torn_fragments, r.replayed), (0, 0, 5), "tear at {tear}");
+        assert_eq!(loaded.to_snapshot(), c.to_snapshot(), "tear at {tear}");
+    }
+}
+
+/// When cutting back fails too (the share is gone), the next append cuts back first; until that
+/// works nothing more is appended after the fragment.
+#[test]
+fn failed_cut_back_is_done_before_the_next_append() {
+    let t = Torn::default();
+    let (mut j, mut c, _) = Journal::open(Box::new(t.clone())).unwrap();
+    let add = add_photo(&mut c);
+    let first = apply(&mut c, vec![add]);
+    j.append(&first).unwrap();
+    let good_len = t.files.get(LOG).unwrap().len();
+    let id = c.photos().next().unwrap().id;
+    let batch = apply(&mut c, vec![Op::SetRating { id, rating: 2 }, Op::SetRating { id, rating: 5 }]);
+    t.truncate_fails.store(true, Ordering::SeqCst);
+    t.tear_next_append(30);
+    assert!(j.append(&batch).is_err());
+    assert_eq!(t.files.get(LOG).unwrap().len(), good_len + 30, "the fragment is still there");
+    // still unreachable: the retry fails without writing anything after the fragment
+    assert!(j.append(&batch).is_err());
+    assert_eq!(t.files.get(LOG).unwrap().len(), good_len + 30);
+    t.truncate_fails.store(false, Ordering::SeqCst);
+    j.append(&batch).unwrap();
+    drop(j);
+    let (_, loaded, r) = Journal::open(Box::new(t.clone())).unwrap();
+    assert!(r.damaged.is_none(), "{r:?}");
+    assert_eq!(r.replayed, 3);
+    assert_eq!(loaded.to_snapshot(), c.to_snapshot());
+}
+
+/// Logs written before the fix: the fragment of the failed append is glued to the first retried
+/// record on one line, followed by the rest of the retry. They load in full (the fragment is
+/// skipped), instead of stopping at the fragment and setting the later records aside as damage.
+#[test]
+fn legacy_fragment_glued_to_the_retry_is_skipped() {
+    let m = MemStore::new();
+    let (mut j, mut c, _) = Journal::open(Box::new(m.clone())).unwrap();
+    let add = add_photo(&mut c);
+    let first = apply(&mut c, vec![add]);
+    j.append(&first).unwrap();
+    let good = m.get(LOG).unwrap();
+    let id = c.photos().next().unwrap().id;
+    let batch = apply(
+        &mut c,
+        vec![
+            Op::SetRating { id, rating: 3 },
+            Op::SetFlag { id, flag: Flag::Pick },
+            Op::SetLabelName { label: ColorLabel::ALL[1], name: Some("Größe ✓".into()) },
+        ],
+    );
+    j.append(&batch).unwrap();
+    let full = m.get(LOG).unwrap();
+    let batch_bytes = &full[good.len()..];
+    let later = apply(&mut c, vec![Op::SetRating { id, rating: 1 }]);
+    j.append(&later).unwrap();
+    let later_bytes = m.get(LOG).unwrap()[full.len()..].to_vec();
+    drop(j);
+
+    // every tear (inside the first record, after it, inside a multi-byte character…)
+    for tear in 1..batch_bytes.len() {
+        if batch_bytes[tear - 1] == b'\n' {
+            continue; // a tear on a record boundary leaves no fragment
+        }
+        let mut log = good.clone();
+        log.extend_from_slice(&batch_bytes[..tear]);
+        log.extend_from_slice(batch_bytes);
+        log.extend_from_slice(&later_bytes);
+        let t = MemStore::new();
+        t.set(LOG, log);
+        let (_, loaded, r) = Journal::open(Box::new(t)).unwrap();
+        assert!(r.damaged.is_none(), "tear at {tear}: {r:?}");
+        assert_eq!(r.torn_fragments, 1, "tear at {tear}");
+        assert_eq!(loaded.to_snapshot(), c.to_snapshot(), "tear at {tear}");
+    }
+
+    // a damaged record whose tail happens to be a whole record from the future is still damage
+    let mut log = good.clone();
+    log.extend_from_slice(b"garbage");
+    log.extend_from_slice(&later_bytes);
+    log.extend_from_slice(&later_bytes);
+    let t = MemStore::new();
+    t.set(LOG, log);
+    let (_, _, r) = Journal::open(Box::new(t)).unwrap();
+    assert!(r.damaged.is_some(), "{r:?}");
+}
+
+/// A snapshot can absorb ops whose append failed: it records them as saved (`seq` moves past
+/// them), and appending after it continues from there.
+#[test]
+fn snapshot_with_unlogged_ops_saves_them() {
+    let t = Torn::default();
+    let (mut j, mut c, _) = Journal::open(Box::new(t.clone())).unwrap();
+    let add = add_photo(&mut c);
+    let first = apply(&mut c, vec![add]);
+    j.append(&first).unwrap();
+    let id = c.photos().next().unwrap().id;
+    let queued = apply(&mut c, vec![Op::SetRating { id, rating: 2 }, Op::SetFlag { id, flag: Flag::Reject }]);
+    t.tear_next_append(10);
+    assert!(j.append(&queued).is_err());
+    j.snapshot_with_unlogged(&c, queued.len() as u64).unwrap();
+    assert_eq!(j.seq(), 3);
+    let after = apply(&mut c, vec![Op::SetRating { id, rating: 5 }]);
+    j.append(&after).unwrap();
+    drop(j);
+    let (j, loaded, r) = Journal::open(Box::new(t.clone())).unwrap();
+    assert_eq!((r.snapshot_seq, r.replayed), (3, 1));
+    assert_eq!(j.seq(), 4);
+    assert_eq!(loaded.to_snapshot(), c.to_snapshot());
+}
+
+/// `FsStore::truncate` on a file that was never created (an append that failed first) is a no-op.
+#[test]
+fn fs_store_truncates_a_missing_file_quietly() {
+    let dir = std::env::temp_dir().join(format!("lc-torn-{}", std::process::id()));
+    let _ = std::fs::remove_dir_all(&dir);
+    let mut s = FsStore::open(&dir).unwrap();
+    s.truncate(LOG, 0).unwrap();
+    assert!(!dir.join(LOG).exists());
+    s.append(LOG, b"abc\n").unwrap();
+    s.truncate(LOG, 0).unwrap();
+    assert_eq!(std::fs::read(dir.join(LOG)).unwrap(), b"");
+    let _ = std::fs::remove_dir_all(&dir);
+}

crates/engine/src/cmd/query.rs

@@ -113,7 +113,7 @@ pub fn specs() -> Vec<CommandSpec> {
                 .map(|r| json!({"group": r.group, "tag": r.tag, "name": r.name, "value": r.value}))
                 .collect();
             // XMP: the sidecar if there is one, else the file's own packet
-            let packet = crate::sidecar::read_packet(path, ph.kind, s.xmp.naming).map(|(x, _)| x).or_else(|| lightcraft_meta::embedded(&bytes).xmp);
+            let packet = crate::sidecar::read_packet(path, ph.kind, s.sidecar_naming(ph.id)).map(|(x, _)| x).or_else(|| lightcraft_meta::embedded(&bytes).xmp);
             let xmp: Vec<Value> = packet
                 .and_then(|x| lightcraft_meta::parse_xmp(&x).ok())
                 .map(|d| d.properties.into_iter().filter(|(k, _)| !k.starts_with("lc:")).map(|(k, v)| json!({"name": k, "value": v.join("; ")})).collect())

crates/engine/src/cmd/xmp.rs

@@ -9,14 +9,26 @@ use crate::{Result, Session};
 
 fn save(s: &mut Session, p: &Value) -> Result<Value> {
     let mut written = Vec::new();
+    let mut merged = Vec::new();
+    let mut backups = Vec::new();
     let mut failed = Vec::new();
+    let owners = crate::sidecar::StemOwners::of(&s.catalog);
     for id in s.targets(p) {
-        match s.save_sidecar(id) {
-            Ok(path) => written.push(path.display().to_string()),
+        match s.save_sidecar_with(id, &owners) {
+            Ok(r) => {
+                let path = r.path.display().to_string();
+                if r.merged {
+                    merged.push(path.clone());
+                }
+                if let Some(b) = r.backup {
+                    backups.push(json!({"path": path, "backup": b.display().to_string()}));
+                }
+                written.push(path);
+            }
             Err(e) => failed.push(json!({"id": id.0, "error": e.to_string()})),
         }
     }
-    Ok(json!({"written": written, "failed": failed}))
+    Ok(json!({"written": written, "merged": merged, "backups": backups, "failed": failed}))
 }
 
 fn read(s: &mut Session, p: &Value) -> Result<Value> {
@@ -63,7 +75,7 @@ pub fn specs() -> Vec<CommandSpec> {
             "Save Metadata to File",
             ["Photo"],
             Some("Cmd+S"),
-            "{ids?} — writes each photo's XMP sidecar (metadata + develop settings) next to the original → {written: [path], failed}",
+            "{ids?} — writes each photo's XMP sidecar (metadata + develop settings) next to the original, merged into an existing one (other apps' data kept; an unreadable one is backed up first) → {written: [path], merged: [path], backups: [{path, backup}], failed}",
             has_selection,
             save
         ),

crates/engine/src/import_move.rs

@@ -234,7 +234,7 @@ pub(crate) fn finish(p: &Placed) -> Result<Vec<(String, String)>, String> {
 }
 
 /// A photo (by extension) still beside a stem-named sidecar, sharing its stem.
-fn sibling_photo(sidecar: &Path) -> Option<String> {
+pub(crate) fn sibling_photo(sidecar: &Path) -> Option<String> {
     let dir = sidecar.parent()?;
     let stem = sidecar.file_stem()?.to_string_lossy().to_string();
     fs::read_dir(dir).ok()?.flatten().map(|e| e.path()).find_map(|f| {

crates/engine/src/library.rs

@@ -362,16 +362,35 @@ impl Session {
     }
 
     /// Flush everything and write a snapshot (on quit). Ends an open interaction first.
+    ///
+    /// The snapshot is written even when appending the queued ops fails: it is a fresh file
+    /// holding everything in memory, so it saves those ops too (the log handle may be the only
+    /// thing that's broken). Fails only if nothing could be saved; the ops then stay queued.
     pub fn close_library(&mut self) -> Result<()> {
         if self.library.is_none() {
             return Ok(());
         }
         let _ = self.end_interaction();
-        self.persist()?;
+        let persisted = self.persist();
         self.save_view();
+        let unlogged = if persisted.is_err() { self.pending_log.len() as u64 } else { 0 };
         let Some(lib) = self.library.as_mut() else { return Ok(()) };
-        lib.journal.snapshot(&self.catalog)?;
-        Ok(())
+        let before = lib.journal.seq();
+        let snapshot = lib.journal.snapshot_with_unlogged(&self.catalog, unlogged);
+        if unlogged > 0 && lib.journal.seq() == before + unlogged {
+            // the snapshot holds the queued ops: they are saved, never append them again
+            log::info!("library: {unlogged} queued change(s) saved in the closing snapshot");
+            self.pending_log.clear();
+            lib.unsaved_error = None;
+            lib.retry_at = None;
+            lib.last_error = None;
+        }
+        match (persisted, snapshot) {
+            (_, Ok(())) => Ok(()),
+            // neither the log nor the snapshot took the queued ops
+            (Err(EngineError::NotSaved(e)), Err(s)) if lib.journal.seq() == before => Err(EngineError::NotSaved(format!("{e}; snapshot: {s}"))),
+            (_, Err(s)) => Err(s.into()),
+        }
     }
 
     fn view_json(&self) -> Vec<u8> {

crates/engine/src/rename.rs

@@ -313,6 +313,12 @@ pub(crate) trait MoveFs {
     fn same_file(&self, a: &Path, b: &Path) -> bool;
     /// Rename `a` to `b`, failing (never replacing) when `b` exists.
     fn rename_no_replace(&self, a: &Path, b: &Path) -> std::io::Result<()>;
+    /// Copy `a` to a new file `b` (an independent copy, never a link), failing when `b` exists.
+    fn copy_no_replace(&self, a: &Path, b: &Path) -> std::io::Result<()>;
+    fn remove_file(&self, p: &Path) -> std::io::Result<()>;
+    /// Another photo file beside the stem-named sidecar `sidecar` that shares its stem (e.g.
+    /// `IMG_1.JPG` for `IMG_1.xmp`), which still uses that sidecar.
+    fn stem_sibling(&self, sidecar: &Path) -> Option<String>;
 }
 
 /// The real file system.
@@ -367,6 +373,23 @@ impl MoveFs for RealFs {
             Err(_) => std::fs::rename(a, b),
         }
     }
+
+    fn copy_no_replace(&self, a: &Path, b: &Path) -> std::io::Result<()> {
+        use std::io::Write;
+        let bytes = std::fs::read(a)?;
+        let mut f = std::fs::OpenOptions::new().write(true).create_new(true).open(b)?;
+        f.write_all(&bytes).and_then(|_| f.sync_all()).inspect_err(|_| {
+            let _ = std::fs::remove_file(b);
+        })
+    }
+
+    fn remove_file(&self, p: &Path) -> std::io::Result<()> {
+        std::fs::remove_file(p)
+    }
+
+    fn stem_sibling(&self, sidecar: &Path) -> Option<String> {
+        crate::import_move::sibling_photo(sidecar)
+    }
 }
 
 /// `from` → `to` differs only in letter case and `to` is that very file (a case-insensitive
@@ -427,7 +450,8 @@ pub(crate) fn move_file_with(fs: &dyn MoveFs, from: &str, to: &str) -> std::resu
         return Err(fail(format!("{to} already exists")));
     }
     move_one(fs, f, t).map_err(|e| fail(format!("rename {from}: {e}")))?;
-    let mut done: Vec<(PathBuf, PathBuf)> = Vec::new(); // sidecars moved
+    // sidecars moved (or copied: `true`)
+    let mut done: Vec<(PathBuf, PathBuf, bool)> = Vec::new();
     for (sc, naming, upper) in sidecars(from) {
         if !fs.is_file(&sc) {
             continue;
@@ -436,28 +460,35 @@ pub(crate) fn move_file_with(fs: &dyn MoveFs, from: &str, to: &str) -> std::resu
         if upper {
             dst = dst.with_extension("XMP");
         }
-        if fs.exists(&dst) && !is_respelling(fs, &sc, &dst) {
+        // a stem sidecar another file still uses (`IMG_1.xmp` of `IMG_1.CR3` and `IMG_1.JPG`)
+        // is copied, not taken away from it (issue #92)
+        let shared = naming == SidecarNaming::Stem && fs.stem_sibling(&sc).is_some();
+        if fs.exists(&dst) && (shared || !is_respelling(fs, &sc, &dst)) {
             continue; // never overwrite: the old sidecar stays where it was
         }
-        if let Err(e) = move_one(fs, &sc, &dst) {
+        let r = if shared { fs.copy_no_replace(&sc, &dst) } else { move_one(fs, &sc, &dst) };
+        if let Err(e) = r {
             let mut message = format!("rename {}: {e}", sc.display());
             // the file first: if it can't go back, the sidecars that moved stay with it
             if let Err(e) = move_one(fs, t, f) {
                 message.push_str(&format!("; {from} could not be moved back ({e}): it is now {to}"));
                 if !done.is_empty() {
-                    let names: Vec<String> = done.iter().map(|(_, b)| b.display().to_string()).collect();
+                    let names: Vec<String> = done.iter().map(|(_, b, _)| b.display().to_string()).collect();
                     message.push_str(&format!(" with its sidecar {}", names.join(", ")));
                 }
                 return Err(MoveError { message, moved: true });
             }
-            for (a, b) in done.iter().rev() {
-                if let Err(e) = move_one(fs, b, a) {
+            for (a, b, copied) in done.iter().rev() {
+                if *copied {
+                    // the original is still there: the copy just goes (a leftover copy loses nothing)
+                    let _ = fs.remove_file(b);
+                } else if let Err(e) = move_one(fs, b, a) {
                     message.push_str(&format!("; sidecar {} could not be moved back ({e}): it is now {}", a.display(), b.display()));
                 }
             }
             return Err(fail(message));
         }
-        done.push((sc, dst));
+        done.push((sc, dst, shared));
     }
     Ok(())
 }
@@ -747,6 +778,27 @@ mod tests {
             self.files.borrow_mut()[i].0 = b.to_string_lossy().to_string();
             Ok(())
         }
+        fn copy_no_replace(&self, a: &Path, b: &Path) -> std::io::Result<()> {
+            if self.exists(b) {
+                return Err(std::io::Error::new(std::io::ErrorKind::AlreadyExists, "exists"));
+            }
+            let i = self.idx(a).ok_or_else(|| std::io::Error::new(std::io::ErrorKind::NotFound, "no such file"))?;
+            let c = self.files.borrow()[i].1.clone();
+            self.files.borrow_mut().push((b.to_string_lossy().to_string(), c));
+            Ok(())
+        }
+        fn remove_file(&self, p: &Path) -> std::io::Result<()> {
+            let i = self.idx(p).ok_or_else(|| std::io::Error::new(std::io::ErrorKind::NotFound, "no such file"))?;
+            self.files.borrow_mut().remove(i);
+            Ok(())
+        }
+        fn stem_sibling(&self, sidecar: &Path) -> Option<String> {
+            let stem = sidecar.with_extension("").to_string_lossy().to_string();
+            self.files.borrow().iter().map(|(f, _)| f.clone()).find(|f| {
+                let p = Path::new(f);
+                p.with_extension("").to_string_lossy() == stem && !p.extension().is_some_and(|e| e.eq_ignore_ascii_case("xmp"))
+            })
+        }
     }
 
     fn file_photo(id: u64, path: &str) -> Photo {
@@ -849,6 +901,34 @@ mod tests {
         assert!(fs.listing().iter().all(|(p, _)| p.starts_with("/p/d.")));
     }
 
+    /// Issue #92 (comment): renaming one of `IMG_1.CR3` + `IMG_1.JPG` copies their shared
+    /// `IMG_1.xmp` instead of taking it away from the other; the last one renamed takes it.
+    #[test]
+    fn shared_stem_sidecar_is_copied_not_taken() {
+        let fs = FakeFs::new(false, &[("/p/IMG_1.CR3", "raw"), ("/p/IMG_1.JPG", "jpg"), ("/p/IMG_1.xmp", "shared"), ("/p/IMG_1.CR3.xmp", "own")]);
+        move_file_with(&fs, "/p/IMG_1.CR3", "/p/Trip_1.CR3").unwrap();
+        assert_eq!(
+            fs.listing(),
+            vec![
+                ("/p/IMG_1.JPG".into(), "jpg".into()),
+                ("/p/IMG_1.xmp".into(), "shared".into()),
+                ("/p/Trip_1.CR3".into(), "raw".into()),
+                ("/p/Trip_1.CR3.xmp".into(), "own".into()),
+                ("/p/Trip_1.xmp".into(), "shared".into()),
+            ]
+        );
+        // the JPEG is the last one using it: it moves
+        move_file_with(&fs, "/p/IMG_1.JPG", "/p/Trip_2.JPG").unwrap();
+        assert!(fs.listing().contains(&("/p/Trip_2.xmp".into(), "shared".into())));
+        assert!(!fs.exists(Path::new("/p/IMG_1.xmp")));
+        // a failure after the copy removes the copy and keeps the original
+        let fs = FakeFs::new(false, &[("/p/A.CR3", "raw"), ("/p/A.JPG", "jpg"), ("/p/A.xmp", "shared"), ("/p/A.CR3.xmp", "own")]);
+        fs.fail.borrow_mut().push("A.CR3.xmp".into());
+        assert!(move_file_with(&fs, "/p/A.CR3", "/p/B.CR3").is_err());
+        assert_eq!(fs.listing().len(), 4);
+        assert!(fs.listing().contains(&("/p/A.xmp".into(), "shared".into())) && !fs.exists(Path::new("/p/B.xmp")));
+    }
+
     /// Issue #95 on the real disk, whichever kind of volume the temp folder is on.
     #[test]
     fn case_only_rename_on_disk() {

crates/engine/src/sidecar.rs

@@ -5,12 +5,25 @@
 //! creator, keywords, capture time and GPS in the standard namespaces, plus our complete develop
 //! settings (`lc:settings`, JSON), the pick/reject flag (`lc:flag`) and location (`lc:location`).
 //!
+//! An existing sidecar is never replaced wholesale (issue #92): LightCraft's properties
+//! ([`OWNED`], [`OWNED_IF_STATED`]) are merged into it ([`lightcraft_meta::merge_xmp`]) and
+//! everything else — another editor's `crs:` develop settings, `xmpMM` history, unknown
+//! namespaces — is kept byte for byte. A sidecar that can't be read as XMP is first copied to
+//! `<name>.xmp.bak-<time>` (never overwritten), then replaced. Writes are atomic (temp file,
+//! fsync, rename).
+//!
+//! **Shared names** (Stem naming): `IMG_0001.CR3` and `IMG_0001.JPG` would share `IMG_0001.xmp`.
+//! When two catalogued files map to one stem sidecar, it belongs to one of them (a raw first, then
+//! the first by file name — [`Session::sidecar_naming`]); the others use `<file>.xmp`
+//! (`IMG_0001.JPG.xmp`) for writing and reading, so neither overwrites the other.
+//!
 //! **Read** (on import, and `photo.readMetadataFromFile`): the sidecar wins for metadata, except
 //! the capture time: a time embedded in the file wins, and the sidecar's (`exif:DateTimeOriginal`,
 //! else `photoshop:DateCreated`, else `xmp:CreateDate`) fills in only when the file has none; develop
 //! settings are restored from `lc:settings` when present, else mapped from interoperable `crs:`
 //! fields ([`crate::crs`]). For raw/DNG files without a sidecar the file's embedded XMP is used.
 
+use std::collections::HashMap;
 use std::path::{Path, PathBuf};
 use std::sync::Arc;
 
@@ -258,11 +271,101 @@ pub fn sidecar_packet(p: &Photo, cat: &lightcraft_catalog::Catalog) -> String {
     lightcraft_meta::write_xmp_lc(&meta, &lc)
 }
 
-/// Write `data` to `path` atomically (temp file + sync + rename).
+/// The properties LightCraft writes and owns in a sidecar: replaced on every save (removed when
+/// LightCraft has no value, so clearing a field clears it in the file too). All of them are read
+/// back on import and by Read Metadata from File.
+pub const OWNED: &[&str] = &[
+    "xmp:Rating",
+    "xmp:Label",
+    "dc:title",
+    "dc:description",
+    "dc:rights",
+    "dc:creator",
+    "dc:subject",
+    "Iptc4xmpCore:Location",
+    "Iptc4xmpCore:AltTextAccessibility",
+    "Iptc4xmpCore:ExtDescrAccessibility",
+    "photoshop:City",
+    "photoshop:State",
+    "photoshop:Country",
+    "xmpRights:Marked",
+    "xmpRights:UsageTerms",
+    "xmpRights:WebStatement",
+    "lc:*",
+];
+
+/// Properties replaced only when LightCraft has a value (capture time; GPS, which LightCraft
+/// doesn't read from sidecars): otherwise the sidecar's own value stays. Anything else LightCraft
+/// writes (`xmp:CreatorTool`) goes only into new sidecars.
+pub const OWNED_IF_STATED: &[&str] = &["exif:DateTimeOriginal", "photoshop:DateCreated", "exif:GPSLatitude", "exif:GPSLongitude"];
+
+/// Write `data` to `path` atomically: a temp file next to it, synced, then renamed over it.
 fn write_atomic(path: &Path, data: &[u8]) -> std::io::Result<()> {
     lightcraft_catalog::safe_file::write_atomic(path, data)
 }
 
+/// Copy `path` to a new `<name>.bak-<stamp>` (`-1`, `-2`… if taken; never overwriting).
+fn backup(path: &Path, stamp: &str) -> std::io::Result<PathBuf> {
+    use std::io::Write;
+    let bytes = std::fs::read(path)?;
+    let stamp: String = stamp.chars().filter(char::is_ascii_alphanumeric).collect();
+    let name = path.file_name().map(|n| n.to_string_lossy().to_string()).unwrap_or_default();
+    for k in 0..1000 {
+        let b = path.with_file_name(if k == 0 { format!("{name}.bak-{stamp}") } else { format!("{name}.bak-{stamp}-{k}") });
+        match std::fs::OpenOptions::new().write(true).create_new(true).open(&b) {
+            Ok(mut f) => {
+                f.write_all(&bytes)?;
+                f.sync_all()?;
+                return Ok(b);
+            }
+            Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => continue,
+            Err(e) => return Err(e),
+        }
+    }
+    Err(std::io::Error::other("no free backup name"))
+}
+
+/// What [`Session::save_sidecar`] did.
+#[derive(Clone, Debug, PartialEq)]
+pub struct SidecarSaved {
+    pub path: PathBuf,
+    /// An existing sidecar was merged into (its other contents kept).
+    pub merged: bool,
+    /// An existing sidecar that couldn't be read as XMP was copied here before being replaced.
+    pub backup: Option<PathBuf>,
+}
+
+/// The new contents for the sidecar at `path`: `fresh` merged into the existing file, if any.
+/// Returns (contents, merged, backup).
+fn sidecar_contents(path: &Path, fresh: String, stamp: &str) -> std::io::Result<(String, bool, Option<PathBuf>)> {
+    let bytes = match std::fs::read(path) {
+        Ok(b) => b,
+        Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok((fresh, false, None)),
+        // can't see what is there: never overwrite it blindly
+        Err(e) => return Err(e),
+    };
+    if bytes.iter().all(u8::is_ascii_whitespace) {
+        return Ok((fresh, false, None));
+    }
+    let rules = lightcraft_meta::MergeRules { owned: OWNED, owned_if_present: OWNED_IF_STATED };
+    match std::str::from_utf8(&bytes)
+        .map_err(|e| e.to_string())
+        .and_then(|old| lightcraft_meta::merge_xmp(old, &fresh, rules).map_err(|e| e.to_string()))
+    {
+        Ok(merged) => Ok((merged, true, None)),
+        Err(why) => {
+            let b = backup(path, stamp)?;
+            log::warn!("{}: not readable as XMP ({why}); kept a copy as {} before replacing it", path.display(), b.display());
+            Ok((fresh, false, Some(b)))
+        }
+    }
+}
+
+/// Key of the stem sidecar a file maps to (case-insensitive).
+fn stem_key(original: &str) -> String {
+    sidecar_path(original, SidecarNaming::Stem).to_string_lossy().to_lowercase()
+}
+
 fn file_path(p: &Photo) -> Option<&str> {
     match &p.source {
         Source::File { path } => Some(path),
@@ -298,24 +401,70 @@ pub(crate) fn op_photos(op: &Op, out: &mut Vec<PhotoId>) {
     }
 }
 
+/// Which photo owns each stem sidecar that several catalogued files map to (see
+/// [`Session::sidecar_naming`]).
+pub(crate) struct StemOwners(HashMap<String, PhotoId>);
+
+impl StemOwners {
+    pub(crate) fn of(cat: &lightcraft_catalog::Catalog) -> StemOwners {
+        // per stem: (raw first, then file name, then id) of the best candidate; and how many
+        let mut best: HashMap<String, ((bool, String, u64), PhotoId, usize)> = HashMap::new();
+        for p in cat.photos().filter(|p| p.copy_of.is_none()) {
+            let Some(path) = file_path(p) else { continue };
+            let rank = (p.kind != MediaKind::Raw, path.to_lowercase(), p.id.0);
+            let e = best.entry(stem_key(path)).or_insert_with(|| (rank.clone(), p.id, 0));
+            e.2 += 1;
+            if rank < e.0 {
+                (e.0, e.1) = (rank, p.id);
+            }
+        }
+        StemOwners(best.into_iter().filter(|(_, v)| v.2 > 1).map(|(k, v)| (k, v.1)).collect())
+    }
+
+    /// `naming` for photo `p`, except that a stem sidecar another file owns becomes Full.
+    fn naming(&self, p: &Photo, naming: SidecarNaming) -> SidecarNaming {
+        match (naming, file_path(p)) {
+            (SidecarNaming::Stem, Some(path)) if self.0.get(&stem_key(path)).is_some_and(|owner| *owner != p.id) => SidecarNaming::Full,
+            _ => naming,
+        }
+    }
+}
+
 impl Session {
-    /// Write the photo's XMP sidecar; returns its path.
-    pub fn save_sidecar(&self, id: PhotoId) -> Result<PathBuf> {
+    /// The sidecar naming for photo `id`: the library's, except under Stem naming when another
+    /// catalogued file shares the stem (`IMG_0001.CR3` + `IMG_0001.JPG`) and owns the stem
+    /// sidecar — a raw first, else the first by file name. The others use Full naming
+    /// (`IMG_0001.JPG.xmp`), so their metadata never overwrites each other.
+    pub fn sidecar_naming(&self, id: PhotoId) -> SidecarNaming {
+        match self.catalog.photo(id) {
+            Some(p) if self.xmp.naming == SidecarNaming::Stem => StemOwners::of(&self.catalog).naming(p, self.xmp.naming),
+            _ => self.xmp.naming,
+        }
+    }
+
+    /// Write the photo's XMP sidecar, merged into an existing one (see the module docs).
+    pub fn save_sidecar(&self, id: PhotoId) -> Result<SidecarSaved> {
+        self.save_sidecar_with(id, &StemOwners::of(&self.catalog))
+    }
+
+    pub(crate) fn save_sidecar_with(&self, id: PhotoId, owners: &StemOwners) -> Result<SidecarSaved> {
         let p = self.catalog.photo(id).ok_or(lightcraft_catalog::CatalogError::NoPhoto(id))?;
         if p.copy_of.is_some() {
             return Err(EngineError::Other(format!("{} is a virtual copy: its settings live only in the library", p.file_name)));
         }
         let orig = file_path(p).ok_or_else(|| EngineError::Other(format!("{} is not a file on disk", p.file_name)))?;
-        let path = sidecar_path(orig, self.xmp.naming);
-        write_atomic(&path, sidecar_packet(p, &self.catalog).as_bytes()).map_err(|e| EngineError::Other(format!("{}: {e}", path.display())))?;
-        Ok(path)
+        let path = sidecar_path(orig, owners.naming(p, self.xmp.naming));
+        let err = |e: std::io::Error| EngineError::Other(format!("{}: {e}", path.display()));
+        let (data, merged, backup) = sidecar_contents(&path, sidecar_packet(p, &self.catalog), &(self.clock)()).map_err(err)?;
+        write_atomic(&path, data.as_bytes()).map_err(err)?;
+        Ok(SidecarSaved { path, merged, backup })
     }
 
     /// The op that applies a photo's sidecar (or embedded XMP) to the catalog, if there is one.
     pub fn read_sidecar_op(&self, id: PhotoId) -> Result<Option<(Op, PathBuf)>> {
         let p = self.catalog.photo(id).ok_or(lightcraft_catalog::CatalogError::NoPhoto(id))?;
         let Some(orig) = file_path(p) else { return Ok(None) };
-        let Some((packet, from)) = read_packet(orig, p.kind, self.xmp.naming) else { return Ok(None) };
+        let Some((packet, from)) = read_packet(orig, p.kind, self.sidecar_naming(id)) else { return Ok(None) };
         let sc = parse_sidecar(&packet, p.kind == MediaKind::Raw)
             .map_err(|e| EngineError::Other(format!("{}: {e}", from.display())))?
             .resolve_label(&self.catalog);
@@ -340,9 +489,13 @@ impl Session {
     pub(crate) fn auto_write_sidecars(&self, ops: &[Op]) {
         let mut ids = Vec::new();
         ops.iter().for_each(|o| op_photos(o, &mut ids));
+        if ids.is_empty() {
+            return;
+        }
+        let owners = StemOwners::of(&self.catalog);
         for id in ids {
             if self.catalog.photo(id).is_some_and(|p| file_path(p).is_some() && p.copy_of.is_none())
-                && let Err(e) = self.save_sidecar(id)
+                && let Err(e) = self.save_sidecar_with(id, &owners)
             {
                 log::warn!("auto-write XMP: {e}");
             }

crates/engine/src/tests_persist.rs

@@ -17,6 +17,8 @@ struct Flaky {
     fail: Arc<AtomicBool>,
     /// Only snapshots fail (appends work).
     snapshots_only: bool,
+    /// Only appends fail (a dead log handle; fresh files can still be written).
+    appends_only: bool,
 }
 
 impl Flaky {
@@ -39,7 +41,7 @@ impl Store for Flaky {
         self.files.read(name)
     }
     fn write_atomic(&mut self, name: &str, data: &[u8]) -> std::io::Result<()> {
-        if self.failing() {
+        if self.failing() && !self.appends_only {
             return Err(std::io::Error::other("disk full"));
         }
         self.files.write_atomic(name, data)
@@ -145,3 +147,47 @@ fn failed_snapshot_does_not_fail_the_command() {
     store.set_failing(false);
     assert_eq!(open(&store, false).catalog.albums().count(), 2);
 }
+
+/// Issue #101: quitting while the log can't be appended to still saves the queued changes in the
+/// closing snapshot (a fresh file), and reports success; they are not appended again later.
+#[test]
+fn close_saves_queued_changes_in_the_snapshot_when_appends_fail() {
+    let store = Flaky { appends_only: true, ..Default::default() };
+    let mut s = open(&store, true);
+    let id = s.selection.active.unwrap();
+    store.set_failing(true);
+    assert!(matches!(s.execute("photo.rate", &json!({"rating": 4})), Err(EngineError::NotSaved(_))));
+    assert!(matches!(s.execute("photo.flag", &json!({"flag": "pick"})), Err(EngineError::NotSaved(_))));
+    assert_eq!(s.unsaved().map(|u| u.0), Some(2));
+    s.close_library().unwrap();
+    assert_eq!(s.unsaved(), None);
+    assert!(s.pending_log.is_empty());
+    let expect = s.catalog.to_snapshot();
+    drop(s);
+    store.set_failing(false);
+    let mut s2 = open(&store, true);
+    assert_eq!(s2.catalog.to_snapshot(), expect);
+    let p = s2.catalog.photo(id).unwrap();
+    assert_eq!((p.rating, p.flag), (4, Flag::Pick));
+    // later edits continue after the absorbed ops
+    s2.execute("photo.rate", &json!({"rating": 2})).unwrap();
+    let expect = s2.catalog.to_snapshot();
+    drop(s2);
+    assert_eq!(open(&store, true).catalog.to_snapshot(), expect);
+}
+
+/// When neither the log nor the snapshot can be written, closing fails with `NotSaved` and the
+/// changes stay queued (a later retry can still save them).
+#[test]
+fn close_fails_when_nothing_can_be_saved() {
+    let store = Flaky::default();
+    let mut s = open(&store, true);
+    store.set_failing(true);
+    assert!(s.execute("photo.rate", &json!({"rating": 4})).is_err());
+    let e = s.close_library().unwrap_err();
+    assert!(matches!(e, EngineError::NotSaved(_)), "{e:?}");
+    assert_eq!(s.unsaved().map(|u| u.0), Some(1));
+    store.set_failing(false);
+    s.close_library().unwrap();
+    assert_eq!(s.unsaved(), None);
+}

crates/engine/src/tests_xmp.rs

@@ -625,3 +625,132 @@ fn copyright_status_usage_terms_and_url_round_trip() {
     let _ = std::fs::remove_dir_all(&src);
     let _ = std::fs::remove_dir_all(&lib);
 }
+
+/// A sidecar another raw developer wrote: develop settings in attributes and elements, a
+/// structured edit history, an unknown namespace.
+const OTHER_APP_SIDECAR: &str = r#"<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?>
+<x:xmpmeta xmlns:x="adobe:ns:meta/" x:xmptk="Other Toolkit">
+ <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#">
+  <rdf:Description rdf:about=""
+    xmlns:xmp="http://ns.adobe.com/xap/1.0/"
+    xmlns:xmpMM="http://ns.adobe.com/xap/1.0/mm/"
+    xmlns:stEvt="http://ns.adobe.com/xap/1.0/sType/ResourceEvent#"
+    xmlns:crs="http://ns.adobe.com/camera-raw-settings/1.0/"
+    xmlns:other="http://example.com/other/1.0/"
+    xmp:Rating="2"
+    crs:Version="99.0"
+    crs:Exposure2012="+0.65"
+    crs:HasSettings="True"
+    other:Secret="keep me">
+   <xmpMM:History>
+    <rdf:Seq>
+     <rdf:li stEvt:action="derived" stEvt:parameters="converted from image/x-raw to image/png"/>
+    </rdf:Seq>
+   </xmpMM:History>
+   <crs:ToneCurvePV2012>
+    <rdf:Seq>
+     <rdf:li>0, 0</rdf:li>
+     <rdf:li>128, 140</rdf:li>
+     <rdf:li>255, 255</rdf:li>
+    </rdf:Seq>
+   </crs:ToneCurvePV2012>
+  </rdf:Description>
+ </rdf:RDF>
+</x:xmpmeta>
+<?xpacket end="w"?>"#;
+
+/// Issue #92: saving merges into another app's sidecar instead of replacing it.
+#[test]
+fn saving_merges_into_another_apps_sidecar() {
+    let src = temp_dir("merge");
+    let lib = temp_dir("merge-lib");
+    write_png(&src.join("shot.png"), 1);
+    std::fs::write(src.join("shot.xmp"), OTHER_APP_SIDECAR).unwrap();
+    let mut s = Session::new().with_fs();
+    s.open_library(&lib, false).unwrap();
+    s.execute("library.import", &json!({"paths": [src.join("shot.png").to_string_lossy()]})).unwrap();
+    let id = only(&s);
+    s.execute("library.select", &json!({"ids": [id.0]})).unwrap();
+    s.execute("photo.rate", &json!({"rating": 5})).unwrap();
+    s.execute("photo.setMeta", &json!({"title": "Harbour", "keywords": ["boats"]})).unwrap();
+    s.execute("develop.set", &json!({"control": "effects.clarity", "value": 30})).unwrap();
+    let r = s.execute("photo.saveMetadataToFile", &json!({})).unwrap();
+    assert_eq!(r["merged"][0], src.join("shot.xmp").to_string_lossy().as_ref(), "{r}");
+    let out = std::fs::read_to_string(src.join("shot.xmp")).unwrap();
+    // the other app's data, byte for byte
+    for part in [
+        "crs:Exposure2012=\"+0.65\"",
+        "other:Secret=\"keep me\"",
+        "   <xmpMM:History>\n    <rdf:Seq>\n     <rdf:li stEvt:action=\"derived\" stEvt:parameters=\"converted from image/x-raw to image/png\"/>\n    </rdf:Seq>\n   </xmpMM:History>",
+        "   <crs:ToneCurvePV2012>\n    <rdf:Seq>\n     <rdf:li>0, 0</rdf:li>\n     <rdf:li>128, 140</rdf:li>",
+    ] {
+        assert!(out.contains(part), "lost {part:?}:\n{out}");
+    }
+    let d = lightcraft_meta::parse_xmp(&out).unwrap();
+    assert_eq!(d.metadata.rating, Some(5), "ours replaces theirs");
+    assert_eq!(d.metadata.title.as_deref(), Some("Harbour"));
+    assert_eq!(d.properties.get("crs:Version"), Some(&vec!["99.0".to_string()]));
+    let saved = s.catalog.photo(id).unwrap().develop.clone();
+    // reading it back restores our settings (lc:settings wins over crs:)
+    s.execute("develop.set", &json!({"control": "effects.clarity", "value": 0})).unwrap();
+    s.execute("photo.readMetadataFromFile", &json!({})).unwrap();
+    assert_eq!(s.catalog.photo(id).unwrap().develop, saved);
+    // saving again keeps one LightCraft description and the other app's data
+    s.execute("photo.rate", &json!({"rating": 3})).unwrap();
+    s.execute("photo.saveMetadataToFile", &json!({})).unwrap();
+    let again = std::fs::read_to_string(src.join("shot.xmp")).unwrap();
+    assert_eq!(again.matches("<rdf:Description").count(), 2, "{again}");
+    assert!(again.contains("other:Secret=\"keep me\"") && again.contains("crs:Exposure2012=\"+0.65\""));
+    assert_eq!(lightcraft_meta::parse_xmp(&again).unwrap().metadata.rating, Some(3));
+
+    // a sidecar that isn't XMP is kept as a backup before it is replaced
+    std::fs::write(src.join("shot.xmp"), b"<not xmp").unwrap();
+    let r = s.execute("photo.saveMetadataToFile", &json!({})).unwrap();
+    let backup = r["backups"][0]["backup"].as_str().unwrap().to_string();
+    assert!(backup.contains("shot.xmp.bak-"), "{r}");
+    assert_eq!(std::fs::read(&backup).unwrap(), b"<not xmp");
+    assert_eq!(lightcraft_meta::parse_xmp(&std::fs::read_to_string(src.join("shot.xmp")).unwrap()).unwrap().metadata.rating, Some(3));
+    // … and another one never overwrites the first backup
+    std::fs::write(src.join("shot.xmp"), b"<still not xmp").unwrap();
+    let r = s.execute("photo.saveMetadataToFile", &json!({})).unwrap();
+    let second = r["backups"][0]["backup"].as_str().unwrap().to_string();
+    assert_ne!(second, backup);
+    assert_eq!(std::fs::read(&backup).unwrap(), b"<not xmp");
+    assert_eq!(std::fs::read(&second).unwrap(), b"<still not xmp");
+    let _ = std::fs::remove_dir_all(&src);
+    let _ = std::fs::remove_dir_all(&lib);
+}
+
+/// Issue #92: two catalogued files with one stem (`IMG_1.jpg` + `IMG_1.png`) don't share a
+/// Stem-named sidecar: the first by name keeps `IMG_1.xmp`, the other writes and reads
+/// `IMG_1.png.xmp`.
+#[test]
+fn files_sharing_a_stem_get_their_own_sidecars() {
+    let src = temp_dir("stem");
+    let lib = temp_dir("stem-lib");
+    write_png(&src.join("IMG_1.png"), 1);
+    let img = lightcraft_raster::Rgba8::from_fn(40, 24, |x, y| [(x * 6) as u8, (y * 9) as u8, 7, 255]);
+    let jpg =
+        crate::export::encode_image(&img, &crate::export::ExportOptions { format: crate::export::ExportFormat::Jpeg, ..Default::default() }).unwrap();
+    std::fs::write(src.join("IMG_1.jpg"), jpg).unwrap();
+    let mut s = Session::new().with_fs();
+    s.open_library(&lib, false).unwrap();
+    s.execute("library.import", &json!({"paths": [src.to_string_lossy()]})).unwrap();
+    let id = |s: &Session, name: &str| s.catalog.photos().find(|p| p.file_name == name).unwrap().id;
+    let (j, p) = (id(&s, "IMG_1.jpg"), id(&s, "IMG_1.png"));
+    assert_eq!(s.sidecar_naming(j), crate::sidecar::SidecarNaming::Stem);
+    assert_eq!(s.sidecar_naming(p), crate::sidecar::SidecarNaming::Full);
+    s.execute("photo.rate", &json!({"ids": [j.0], "rating": 2})).unwrap();
+    s.execute("photo.rate", &json!({"ids": [p.0], "rating": 5})).unwrap();
+    let r = s.execute("photo.saveMetadataToFile", &json!({"ids": [j.0, p.0]})).unwrap();
+    assert_eq!(r["written"].as_array().unwrap().len(), 2, "{r}");
+    let rating = |f: &str| lightcraft_meta::parse_xmp(&std::fs::read_to_string(src.join(f)).unwrap()).unwrap().metadata.rating;
+    assert_eq!(rating("IMG_1.xmp"), Some(2));
+    assert_eq!(rating("IMG_1.png.xmp"), Some(5));
+    // each reads its own back
+    s.execute("photo.rate", &json!({"ids": [j.0, p.0], "rating": 0})).unwrap();
+    s.execute("photo.readMetadataFromFile", &json!({"ids": [j.0, p.0]})).unwrap();
+    assert_eq!((s.catalog.photo(j).unwrap().rating, s.catalog.photo(p).unwrap().rating), (2, 5));
+    let _ = std::fs::remove_dir_all(&src);
+    let _ = std::fs::remove_dir_all(&lib);
+}

crates/meta/src/lib.rs

@@ -17,6 +17,7 @@ mod gpx;
 mod iptc;
 pub mod tags;
 mod xmp;
+mod xmp_merge;
 
 pub use container::{Embedded, embedded, jpeg_segments, png_chunks, webp_chunks};
 pub use datetime::DateTime;
@@ -26,6 +27,7 @@ pub use iptc::parse_iptc;
 pub use lightcraft_geom::Orientation;
 pub use tags::{TagRow, file_tag_rows, tag_rows};
 pub use xmp::{CRS_NS, LC_NS, XmpData, XmpError, XmpValue, parse_xmp, write_xmp, write_xmp_lc};
+pub use xmp_merge::{MergeRules, merge_xmp};
 
 use serde::{Deserialize, Serialize};
 

crates/meta/src/xmp.rs

@@ -145,6 +145,11 @@ impl Node {
 const MAX_DEPTH: usize = 64;
 const MAX_NODES: usize = 200_000;
 
+/// `prefix:local` with the prefix canonicalised by namespace URI (see [`NAMESPACES`]).
+pub(crate) fn canonical_name(qname: &str, scopes: &[Vec<(String, String)>]) -> String {
+    canonical(qname, scopes)
+}
+
 fn canonical(qname: &str, scopes: &[Vec<(String, String)>]) -> String {
     let (prefix, local) = qname.split_once(':').unwrap_or(("", qname));
     if prefix == "xml" || prefix == "xmlns" {

crates/meta/src/xmp_merge.rs

@@ -0,0 +1,403 @@
+//! Merging a freshly written XMP packet into an existing one (a sidecar another application
+//! wrote, e.g. with its develop settings and edit history), keeping everything the writer does not
+//! own byte for byte.
+//!
+//! The existing packet is scanned once (namespace-resolved, with byte positions). Only top-level
+//! properties of the `rdf:Description` elements directly under `rdf:RDF` are considered, in
+//! attribute form (`xmp:Rating="3"`) and element form (`<dc:subject>…</dc:subject>`):
+//! - properties the writer owns ([`MergeRules::owned`]) are removed, and written from the fresh
+//!   packet when it has them (so a cleared field is cleared in the file too);
+//! - properties owned only when stated ([`MergeRules::owned_if_present`]) are replaced when the
+//!   fresh packet has them and kept otherwise;
+//! - any other property of the fresh packet (e.g. `xmp:CreatorTool`) is not written: the file
+//!   keeps describing itself as its creator left it;
+//! - everything else — other namespaces (e.g. `crs:`), `xmpMM:History`, unknown properties,
+//!   comments, the packet wrapper and padding — is copied unchanged.
+//!
+//! The written properties go into one new `rdf:Description` (declaring its own namespaces, so
+//! the existing prefix bindings never matter) just before `</rdf:RDF>`. A description left empty
+//! by the removals is dropped, so repeated saves don't accumulate. The result is checked by
+//! parsing it again: every written property must read back as in the fresh packet.
+
+use std::collections::BTreeSet;
+
+use quick_xml::events::Event;
+
+use crate::xmp::{XmpError, canonical_name, parse_xmp};
+
+/// Which properties [`merge_xmp`] takes from the fresh packet. Names are canonical
+/// `prefix:name` (prefixes as [`crate::parse_xmp`] reports them); `prefix:*` is a whole namespace.
+#[derive(Clone, Copy, Debug, Default)]
+pub struct MergeRules<'a> {
+    /// Always replaced: removed from the existing packet, written from the fresh one if stated.
+    pub owned: &'a [&'a str],
+    /// Replaced only when the fresh packet states them; otherwise the existing value stays.
+    pub owned_if_present: &'a [&'a str],
+}
+
+fn listed(list: &[&str], name: &str) -> bool {
+    list.iter().any(|p| match p.strip_suffix('*') {
+        Some(ns) => name.starts_with(ns),
+        None => *p == name,
+    })
+}
+
+#[derive(Debug)]
+struct Attr {
+    raw: String,
+    name: String,
+    /// The value as written (still escaped).
+    value: String,
+}
+
+#[derive(Debug)]
+struct Prop {
+    name: String,
+    start: usize,
+    end: usize,
+}
+
+#[derive(Debug, Default)]
+struct Desc {
+    tag_start: usize,
+    tag_end: usize,
+    /// The element name as written (`rdf:Description`, or another prefix for the RDF namespace).
+    raw_name: String,
+    empty: bool,
+    attrs: Vec<Attr>,
+    props: Vec<Prop>,
+    /// The end of `</rdf:Description>` (`tag_end` when self-closing).
+    end: usize,
+}
+
+#[derive(Debug, Default)]
+struct Scan {
+    descs: Vec<Desc>,
+    /// Where the first `</rdf:RDF>` starts.
+    rdf_close: Option<usize>,
+}
+
+enum Kind {
+    Other,
+    Rdf,
+    Desc(usize),
+    Prop { desc: usize, start: usize, name: String },
+}
+
+fn is_meta_attr(name: &str) -> bool {
+    name.starts_with("xmlns")
+        || matches!(name, "rdf:about" | "rdf:ID" | "rdf:nodeID" | "xml:lang" | "rdf:parseType" | "rdf:resource" | "rdf:datatype")
+}
+
+fn pos(r: &quick_xml::Reader<&[u8]>) -> usize {
+    usize::try_from(r.buffer_position()).unwrap_or(usize::MAX)
+}
+
+/// Locate the descriptions, their top-level properties and `</rdf:RDF>` in a packet.
+fn scan(s: &str) -> Result<Scan, XmpError> {
+    let mut reader = quick_xml::Reader::from_reader(s.as_bytes());
+    reader.config_mut().check_end_names = true;
+    let mut out = Scan::default();
+    let mut stack: Vec<Kind> = Vec::new();
+    let mut scopes: Vec<Vec<(String, String)>> = vec![vec![("xml".into(), "http://www.w3.org/XML/1998/namespace".into())]];
+    let mut count = 0usize;
+    loop {
+        let before = pos(&reader);
+        let ev = reader.read_event().map_err(|e| XmpError::Xml(e.to_string()))?;
+        let after = pos(&reader);
+        match ev {
+            Event::Start(ref e) | Event::Empty(ref e) => {
+                count += 1;
+                if count > 200_000 || stack.len() > 64 {
+                    return Err(XmpError::TooComplex);
+                }
+                let empty = matches!(ev, Event::Empty(_));
+                let mut scope = Vec::new();
+                let mut raw_attrs = Vec::new();
+                for a in e.attributes() {
+                    let a = a.map_err(|e| XmpError::Xml(e.to_string()))?;
+                    let k = String::from_utf8_lossy(a.key.as_ref()).into_owned();
+                    let v = String::from_utf8_lossy(&a.value).into_owned();
+                    if k == "xmlns" {
+                        scope.push((String::new(), v.clone()));
+                    } else if let Some(p) = k.strip_prefix("xmlns:") {
+                        scope.push((p.to_string(), v.clone()));
+                    }
+                    raw_attrs.push((k, v));
+                }
+                scopes.push(scope);
+                let raw_name = String::from_utf8_lossy(e.name().as_ref()).into_owned();
+                let name = canonical_name(&raw_name, &scopes);
+                let kind = match stack.last() {
+                    Some(Kind::Rdf) if name == "rdf:Description" => {
+                        let attrs = raw_attrs.into_iter().map(|(raw, value)| Attr { name: canonical_name(&raw, &scopes), raw, value }).collect();
+                        out.descs.push(Desc { tag_start: before, tag_end: after, raw_name, empty, attrs, props: Vec::new(), end: after });
+                        Kind::Desc(out.descs.len() - 1)
+                    }
+                    Some(Kind::Desc(i)) => Kind::Prop { desc: *i, start: before, name },
+                    _ if name == "rdf:RDF" && out.rdf_close.is_none() => Kind::Rdf,
+                    _ => Kind::Other,
+                };
+                if empty {
+                    scopes.pop();
+                    if let Kind::Prop { desc, start, name } = kind
+                        && let Some(d) = out.descs.get_mut(desc)
+                    {
+                        d.props.push(Prop { name, start, end: after });
+                    }
+                } else {
+                    stack.push(kind);
+                }
+            }
+            Event::End(_) => {
+                scopes.pop();
+                match stack.pop() {
+                    Some(Kind::Prop { desc, start, name }) => {
+                        if let Some(d) = out.descs.get_mut(desc) {
+                            d.props.push(Prop { name, start, end: after });
+                        }
+                    }
+                    Some(Kind::Desc(i)) => {
+                        if let Some(d) = out.descs.get_mut(i) {
+                            d.end = after;
+                        }
+                    }
+                    Some(Kind::Rdf) => out.rdf_close = out.rdf_close.or(Some(before)),
+                    Some(Kind::Other) => {}
+                    None => return Err(XmpError::Xml("unbalanced end tag".into())),
+                }
+            }
+            Event::Eof => break,
+            _ => {}
+        }
+    }
+    if !stack.is_empty() {
+        return Err(XmpError::Xml("unclosed element".into()));
+    }
+    Ok(out)
+}
+
+/// `start` moved back over the indentation and line break before it (so a removed property
+/// takes its line with it).
+fn line_start(s: &str, start: usize) -> usize {
+    let b = s.as_bytes();
+    let mut i = start;
+    while i > 0 && matches!(b.get(i - 1), Some(b' ' | b'\t')) {
+        i -= 1;
+    }
+    if i > 0 && b.get(i - 1) == Some(&b'\n') {
+        i -= 1;
+        if i > 0 && b.get(i - 1) == Some(&b'\r') {
+            i -= 1;
+        }
+    }
+    i
+}
+
+/// Merge `fresh` (a packet as [`crate::write_xmp_lc`] writes it) into `existing` following
+/// `rules` (see the module docs). Fails — and the caller must not overwrite `existing` blindly —
+/// when `existing` isn't a well-formed XMP packet.
+pub fn merge_xmp(existing: &str, fresh: &str, rules: MergeRules) -> Result<String, XmpError> {
+    let (bom, old) = match existing.strip_prefix('\u{feff}') {
+        Some(rest) => ("\u{feff}", rest),
+        None => ("", existing),
+    };
+    parse_xmp(old)?;
+    let ex = scan(old)?;
+    let rdf_close = ex.rdf_close.ok_or_else(|| XmpError::Xml("no rdf:RDF element".into()))?;
+    let new = scan(fresh)?;
+    let fresh_desc = new.descs.first().ok_or_else(|| XmpError::Xml("the new packet has no rdf:Description".into()))?;
+    let fresh_names: BTreeSet<&str> = fresh_desc.props.iter().map(|p| p.name.as_str()).collect();
+    let remove = |name: &str| listed(rules.owned, name) || (listed(rules.owned_if_present, name) && fresh_names.contains(name));
+    let write = |name: &str| listed(rules.owned, name) || listed(rules.owned_if_present, name);
+
+    // edits on `old`: (start, end, replacement), applied back to front
+    let mut edits: Vec<(usize, usize, String)> = Vec::new();
+    for d in &ex.descs {
+        let gone_attrs: Vec<&Attr> = d.attrs.iter().filter(|a| !is_meta_attr(&a.name) && remove(&a.name)).collect();
+        let gone_props: Vec<&Prop> = d.props.iter().filter(|p| remove(&p.name)).collect();
+        if gone_attrs.is_empty() && gone_props.is_empty() {
+            continue;
+        }
+        let attrs_left = d.attrs.iter().any(|a| !is_meta_attr(&a.name) && !remove(&a.name));
+        if !attrs_left && gone_props.len() == d.props.len() {
+            // nothing of its own left: drop the whole description
+            edits.push((line_start(old, d.tag_start), d.end, String::new()));
+            continue;
+        }
+        if !gone_attrs.is_empty() {
+            let mut tag = format!("<{}", d.raw_name);
+            for a in d.attrs.iter().filter(|a| is_meta_attr(&a.name) || !remove(&a.name)) {
+                tag.push_str(&format!("\n    {}=\"{}\"", a.raw, a.value.replace('"', "&quot;")));
+            }
+            tag.push_str(if d.empty { "/>" } else { ">" });
+            edits.push((d.tag_start, d.tag_end, tag));
+        }
+        for p in gone_props {
+            edits.push((line_start(old, p.start), p.end, String::new()));
+        }
+    }
+    // the new description: its own namespace declarations, the properties to write
+    let mut block = String::from("\n  <rdf:Description rdf:about=\"\"\n    xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\"");
+    for a in fresh_desc.attrs.iter().filter(|a| a.raw.starts_with("xmlns:") && a.raw != "xmlns:rdf") {
+        block.push_str(&format!("\n    {}=\"{}\"", a.raw, a.value));
+    }
+    block.push('>');
+    let mut written = 0;
+    for p in fresh_desc.props.iter().filter(|p| write(&p.name)) {
+        let text = fresh.get(p.start..p.end).ok_or_else(|| XmpError::Xml("bad property span".into()))?;
+        block.push_str("\n   ");
+        block.push_str(text);
+        written += 1;
+    }
+    block.push_str("\n  </rdf:Description>");
+    if written > 0 {
+        let at = old.get(..rdf_close).map_or(rdf_close, |h| h.trim_end().len());
+        edits.push((at, at, block));
+    }
+    edits.sort_by_key(|e| (e.0, e.1));
+    // overlapping edits can't happen (properties sit inside their description, which is either
+    // dropped whole or edited piecewise), but never splice blindly
+    let mut out = String::with_capacity(old.len() + 4096);
+    out.push_str(bom);
+    let mut at = 0;
+    for (s, e, r) in &edits {
+        if *s < at {
+            return Err(XmpError::Xml("overlapping edits".into()));
+        }
+        out.push_str(old.get(at..*s).ok_or_else(|| XmpError::Xml("bad span".into()))?);
+        out.push_str(r);
+        at = *e;
+    }
+    out.push_str(old.get(at..).ok_or_else(|| XmpError::Xml("bad span".into()))?);
+
+    // read back: everything written must come out as written
+    let merged = parse_xmp(&out)?;
+    let want = parse_xmp(fresh)?;
+    for (k, v) in &want.properties {
+        let top = k.split('/').next().unwrap_or(k);
+        if write(top) && merged.properties.get(k) != Some(v) {
+            return Err(XmpError::Xml(format!("{k} did not survive the merge")));
+        }
+    }
+    Ok(out)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const RULES: MergeRules =
+        MergeRules { owned: &["xmp:Rating", "xmp:Label", "dc:subject", "dc:title", "lc:*"], owned_if_present: &["exif:DateTimeOriginal"] };
+
+    /// A sidecar as another raw developer writes it: attribute-form simple properties, develop
+    /// settings, a structured history, an unknown namespace.
+    const FOREIGN: &str = "<?xpacket begin=\"\u{feff}\" id=\"W5M0MpCehiHzreSzNTczkc9d\"?>
+<x:xmpmeta xmlns:x=\"adobe:ns:meta/\" x:xmptk=\"Some Toolkit 1.0\">
+ <rdf:RDF xmlns:rdf=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\">
+  <rdf:Description rdf:about=\"\"
+    xmlns:xmp=\"http://ns.adobe.com/xap/1.0/\"
+    xmlns:xmpMM=\"http://ns.adobe.com/xap/1.0/mm/\"
+    xmlns:stEvt=\"http://ns.adobe.com/xap/1.0/sType/ResourceEvent#\"
+    xmlns:crs=\"http://ns.adobe.com/camera-raw-settings/1.0/\"
+    xmlns:dc=\"http://purl.org/dc/elements/1.1/\"
+    xmlns:foo=\"http://example.com/foo/\"
+    xmp:Rating=\"2\"
+    xmp:CreatorTool=\"Other App\"
+    crs:Exposure2012=\"+0.50\"
+    crs:Contrast2012=\"-12\"
+    foo:Thing=\"a &amp; b\">
+   <xmpMM:History>
+    <rdf:Seq>
+     <rdf:li stEvt:action=\"saved\" stEvt:when=\"2026-01-02T03:04:05\"/>
+    </rdf:Seq>
+   </xmpMM:History>
+   <crs:ToneCurvePV2012>
+    <rdf:Seq>
+     <rdf:li>0, 0</rdf:li>
+     <rdf:li>255, 255</rdf:li>
+    </rdf:Seq>
+   </crs:ToneCurvePV2012>
+   <dc:subject>
+    <rdf:Bag>
+     <rdf:li>old</rdf:li>
+    </rdf:Bag>
+   </dc:subject>
+  </rdf:Description>
+ </rdf:RDF>
+</x:xmpmeta>
+";
+
+    /// With the packet's whitespace padding and trailer.
+    fn foreign() -> String {
+        format!("{FOREIGN}{}\n<?xpacket end=\"w\"?>", " ".repeat(100))
+    }
+
+    fn fresh(rating: i8, keywords: &[&str]) -> String {
+        let m = crate::Metadata {
+            software: Some("LightCraft".into()),
+            rating: Some(rating),
+            keywords: keywords.iter().map(|k| k.to_string()).collect(),
+            ..Default::default()
+        };
+        crate::write_xmp_lc(&m, &[("settings", "{\"a\":1}"), ("flag", "pick")])
+    }
+
+    #[test]
+    fn keeps_foreign_properties_and_replaces_owned_ones() {
+        let out = merge_xmp(&foreign(), &fresh(4, &["new", "two"]), RULES).unwrap();
+        let d = parse_xmp(&out).unwrap();
+        let p = |k: &str| d.properties.get(k).cloned().unwrap_or_default();
+        assert_eq!(p("xmp:Rating"), vec!["4"]);
+        assert_eq!(p("dc:subject"), vec!["new", "two"]);
+        assert_eq!(p("lc:settings"), vec!["{\"a\":1}"]);
+        assert_eq!(p("lc:flag"), vec!["pick"]);
+        assert_eq!(p("xmp:CreatorTool"), vec!["Other App"], "not ours: kept");
+        assert_eq!(p("crs:Exposure2012"), vec!["+0.50"]);
+        assert_eq!(p("foo:Thing").len(), 1);
+        // untouched parts are byte for byte the same
+        for part in [
+            "   <xmpMM:History>\n    <rdf:Seq>\n     <rdf:li stEvt:action=\"saved\" stEvt:when=\"2026-01-02T03:04:05\"/>\n    </rdf:Seq>\n   </xmpMM:History>",
+            "   <crs:ToneCurvePV2012>\n    <rdf:Seq>\n     <rdf:li>0, 0</rdf:li>",
+            "crs:Contrast2012=\"-12\"",
+            "foo:Thing=\"a &amp; b\"",
+            "<?xpacket begin=\"\u{feff}\" id=\"W5M0MpCehiHzreSzNTczkc9d\"?>\n<x:xmpmeta xmlns:x=\"adobe:ns:meta/\" x:xmptk=\"Some Toolkit 1.0\">",
+            &format!("</x:xmpmeta>\n{}\n<?xpacket end=\"w\"?>", " ".repeat(100)),
+        ] {
+            assert!(out.contains(part), "lost {part:?} in\n{out}");
+        }
+        assert!(!out.contains("xmp:Rating=\"2\""));
+        assert!(!out.contains("<rdf:li>old</rdf:li>"));
+        // saving again changes only our part, and doesn't pile up descriptions
+        let again = merge_xmp(&out, &fresh(1, &[]), RULES).unwrap();
+        let d = parse_xmp(&again).unwrap();
+        assert_eq!(d.properties.get("xmp:Rating"), Some(&vec!["1".to_string()]));
+        assert!(!d.properties.contains_key("dc:subject"), "a cleared field is cleared");
+        assert_eq!(again.matches("<rdf:Description").count(), 2, "{again}");
+        assert_eq!(merge_xmp(&again, &fresh(1, &[]), RULES).unwrap(), again, "idempotent");
+    }
+
+    #[test]
+    fn owned_if_present_and_prefix_independence() {
+        // the existing packet binds the namespaces to other prefixes, and has a capture time
+        let ex = "<x:xmpmeta xmlns:x=\"adobe:ns:meta/\"><r:RDF xmlns:r=\"http://www.w3.org/1999/02/22-rdf-syntax-ns#\">\
+            <r:Description r:about=\"\" xmlns:a=\"http://ns.adobe.com/xap/1.0/\" xmlns:e=\"http://ns.adobe.com/exif/1.0/\" \
+            a:Rating=\"5\" e:DateTimeOriginal=\"2020-01-01T00:00:00\"/></r:RDF></x:xmpmeta>";
+        let out = merge_xmp(ex, &fresh(3, &[]), RULES).unwrap();
+        let d = parse_xmp(&out).unwrap();
+        assert_eq!(d.properties.get("xmp:Rating"), Some(&vec!["3".to_string()]));
+        assert_eq!(d.properties.get("exif:DateTimeOriginal"), Some(&vec!["2020-01-01T00:00:00".to_string()]), "fresh has none: kept");
+        let mut m = crate::Metadata { rating: Some(3), ..Default::default() };
+        m.capture_time = crate::DateTime::parse_iso("2024-05-06T07:08:09");
+        let out = merge_xmp(ex, &crate::write_xmp_lc(&m, &[]), RULES).unwrap();
+        let d = parse_xmp(&out).unwrap();
+        assert_eq!(d.properties.get("exif:DateTimeOriginal"), Some(&vec!["2024-05-06T07:08:09".to_string()]));
+    }
+
+    #[test]
+    fn refuses_what_it_cannot_read() {
+        for bad in ["", "not xml at all", "<x:xmpmeta xmlns:x=\"adobe:ns:meta/\"><rdf:RDF", "<a><b></a>", "<x:xmpmeta xmlns:x=\"adobe:ns:meta/\"/>"] {
+            assert!(merge_xmp(bad, &fresh(1, &[]), RULES).is_err(), "{bad:?}");
+        }
+    }
+}

crates/meta/tests/robust.rs

@@ -1,4 +1,4 @@
-use lightcraft_meta::{Metadata, extract, parse_iptc, parse_xmp, read_exif, write_xmp};
+use lightcraft_meta::{MergeRules, Metadata, extract, merge_xmp, parse_iptc, parse_xmp, read_exif, write_xmp};
 use proptest::prelude::*;
 
 proptest! {
@@ -21,6 +21,23 @@ proptest! {
         let _ = parse_xmp(&s);
     }
 
+    /// Merging into arbitrary (also damaged) packets never panics, and a merge that succeeds
+    /// reads back with the written values.
+    #[test]
+    fn merge_never_panics(cut in 0usize..900, junk in ".{0,20}", rating in 0i8..=5) {
+        let base = write_xmp(&Metadata { title: Some("t".into()), rating: Some(1), ..Default::default() }, Some("{}"));
+        let mut s: String = base.chars().take(cut).collect();
+        s.push_str(&junk);
+        s.extend(base.chars().skip(cut));
+        let fresh = write_xmp(&Metadata { rating: Some(rating), ..Default::default() }, Some("{\"x\":1}"));
+        let rules = MergeRules { owned: &["xmp:Rating", "dc:title", "lc:*"], owned_if_present: &[] };
+        if let Ok(out) = merge_xmp(&s, &fresh, rules) {
+            let d = parse_xmp(&out).unwrap();
+            prop_assert_eq!(d.metadata.rating, Some(rating));
+            prop_assert_eq!(d.lc_settings.as_deref(), Some("{\"x\":1}"));
+        }
+    }
+
     #[test]
     fn user_text_roundtrips(title in "[a-zA-Z0-9 &<>\"'éü€;|/\\\\]{1,40}", kw in proptest::collection::vec("[a-zA-Z0-9 &<>\"'|]{1,12}", 0..5), rating in -1i8..=5) {
         let title = title.trim().to_string();

docs/parity.md

@@ -153,7 +153,7 @@ under the UI command that wraps it (a no-op error); the UI command now wins.
 | LR-LIB-DELETE | Delete / Recently Deleted | P0 | ✅ | `cmd:photo.delete`, `cmd:photo.restore`, `cmd:photo.deletePermanently` | no confirmation dialog, no auto-purge after N days, no "Empty" |
 | LR-LIB-REMOVE-ALBUM | Remove from album | P0 | ✅ | `cmd:album.removePhotos` | |
 | LR-LIB-DUPLICATE | Duplicate a photo | P2 | ✅ | `cmd:photo.duplicate` | Photo ▸ Duplicate: a real `-copy` file with the same settings, metadata and albums (virtual copies share the file) |
-| LR-LIB-RENAME | Batch rename | P1 | ✅ | `cmd:photo.rename`, `cmd:photo.renamePreview`, `cmd:photo.renameTokens`, `cmd:dialog.rename`, `crates/engine/src/rename.rs` (`TOKENS`) | template tokens {name} {num} {seq:N} {date:%Y%m%d} {folder} {camera} {lens} {iso} {rating} {title} {creator} {ext} (shared with export naming and import rename); a Tags picker beside every template field (Rename Photos, import Rename, export File name) lists each tag with meaning + live example, the date directives and the rules, and inserts the clicked tag at the text cursor; unknown tags are flagged; preview; renames files on disk with their XMP sidecars, never overwriting (-1, -2… suffixes; a change of letter case only is checked by file identity, so on case-sensitive volumes `img_1.jpg` next to `IMG_1.JPG` is a collision), rolls back on failure (a file that can't be moved back is reported old → new and the library follows it as an undoable partial rename; the same for undo/redo); undo/redo move the files; virtual copies follow |
+| LR-LIB-RENAME | Batch rename | P1 | ✅ | `cmd:photo.rename`, `cmd:photo.renamePreview`, `cmd:photo.renameTokens`, `cmd:dialog.rename`, `crates/engine/src/rename.rs` (`TOKENS`) | template tokens {name} {num} {seq:N} {date:%Y%m%d} {folder} {camera} {lens} {iso} {rating} {title} {creator} {ext} (shared with export naming and import rename); a Tags picker beside every template field (Rename Photos, import Rename, export File name) lists each tag with meaning + live example, the date directives and the rules, and inserts the clicked tag at the text cursor; unknown tags are flagged; preview; renames files on disk with their XMP sidecars (a stem sidecar another file still shares, e.g. raw + JPEG, is copied rather than taken), never overwriting (-1, -2… suffixes; a change of letter case only is checked by file identity, so on case-sensitive volumes `img_1.jpg` next to `IMG_1.JPG` is a collision), rolls back on failure (a file that can't be moved back is reported old → new and the library follows it as an undoable partial rename; the same for undo/redo); undo/redo move the files; virtual copies follow |
 | LR-LIB-CAPTURETIME | Edit capture time | P1 | ✅ | `cmd:photo.setCaptureTime`, `cmd:dialog.captureTime`, `crates/catalog/src/dates.rs` | set (the other selected photos shift by the same amount, or `each`), shift by days/hours/minutes, time-zone shift; one undo step, journaled; Info panel button; no “revert to original capture time” |
 | LR-LIB-SHOWFINDER | Reveal original in file manager | P0 | ✅ | `cmd:app.showInFinder` | ⌘R (see MENU-FILE-SHOWFINDER) |
 | LR-LIB-COVER | Album cover | P2 | ✅ | `cmd:album.setCover` | |
@@ -210,7 +210,7 @@ under the UI command that wraps it (a no-op error); the UI command now wins.
 | LR-META-COPYRIGHT-DEFAULT | Default copyright on import | P1 | ✅ | `cmd:library.preferences` (`import.copyright`, `import.creator`), `crates/ui-egui/src/panels/settings.rs` | Settings → Import → Metadata; fills only photos without their own |
 | LR-META-LOCATION | Location editing | P2 | 🟡 | `cmd:photo.setMeta` (`location`, `city`, `state`, `country`, `gps`) | place fields and GPS (decimal or degrees / minutes / seconds) edited in Info, read/written as IPTC Core / Photoshop / EXIF XMP; Show on Map opens OpenStreetMap; no embedded map, no geocoding |
 | LR-META-COPYPASTE | Copy / paste metadata | P2 | ✅ | `cmd:photo.copyMetadata`, `cmd:photo.pasteMetadata` | title, caption, alt text, extended description, copyright (notice, status, usage terms, info URL), creator, place fields, keywords; `fields` picks a subset |
-| LR-META-XMP | XMP read/write | P0 | ✅ | `cmd:photo.saveMetadataToFile`, `cmd:photo.readMetadataFromFile`, `cmd:library.xmpPreferences`, `crates/engine/src/sidecar.rs`, `docs/xmp-interop.md` | sidecar wins for metadata; a sidecar capture time (`exif:DateTimeOriginal` / `photoshop:DateCreated` / `xmp:CreateDate`) fills in only when the file has none |
+| LR-META-XMP | XMP read/write | P0 | ✅ | `cmd:photo.saveMetadataToFile`, `cmd:photo.readMetadataFromFile`, `cmd:library.xmpPreferences`, `crates/engine/src/sidecar.rs`, `docs/xmp-interop.md` | sidecar wins for metadata; a sidecar capture time (`exif:DateTimeOriginal` / `photoshop:DateCreated` / `xmp:CreateDate`) fills in only when the file has none; saving merges into an existing sidecar (`crates/meta/src/xmp_merge.rs`): another app's `crs:`, `xmpMM:History` and unknown namespaces are kept byte for byte, an unreadable sidecar is backed up first; with stem naming, files sharing a stem (raw + JPEG) get separate sidecars (`<file>.xmp` for all but the raw) |
 | LR-META-EXIF-FULL | Full EXIF/IPTC [Classic] | P1 | ✅ | `cmd:photo.allMetadata`, `cmd:dialog.allMetadata`, `crates/meta/src/tags.rs`, `crates/meta/src/exif.rs`, `crates/meta/src/iptc.rs` | read and written on export; Info ▸ All Metadata…: every TIFF / EXIF / GPS / interop tag (named, common values spelled out) and the XMP fields, searchable; metadata presets |
 
 ## F. Edit panel — global adjustments (EDIT)
@@ -488,7 +488,7 @@ under the UI command that wraps it (a no-op error); the UI command now wins.
 
 | Id | Feature | Tier | Status | Evidence | Missing / notes |
 |---|---|---|---|---|---|
-| LR-BEHAV-AUTOSAVE | Instant autosave | P0 | ✅ | `crates/catalog/src/journal.rs`, `crates/engine/src/library.rs` | every change fsynced before the command returns; a failed write fails the command ("saved in memory but not written to disk"), keeps the change queued and retries; top-bar warning until saved |
+| LR-BEHAV-AUTOSAVE | Instant autosave | P0 | ✅ | `crates/catalog/src/journal.rs`, `crates/engine/src/library.rs` | every change fsynced before the command returns; a failed write fails the command ("saved in memory but not written to disk"), keeps the change queued and retries; top-bar warning until saved; a write that fails part-way is cut back to the last whole record so the retry never reads back as damage (logs from older builds with such a fragment load in full); quitting saves queued changes in the closing snapshot even when the log can't be appended to; versioned catalog format (`journal::VERSION`): older libraries are upgraded on open, a library from a newer LightCraft is refused untouched ("written by a newer version") |
 | LR-BEHAV-UNDO | Global undo | P0 | ✅ | `cmd:edit.undo`, `crates/engine/src/tests.rs` (`rating_flag_undo_redo`) | covers ratings, albums, deletes, edits |
 | LR-BEHAV-MULTISELECT | Multi-selection | P0 | ✅ | `cmd:library.select` (`replace`/`add`/`toggle`/`range`), `cmd:library.selectAll` | |
 | LR-BEHAV-BATCH | Batch apply to selection | P0 | ✅ | `cmd:photo.rate`, `cmd:develop.paste`, `cmd:preset.apply`, `cmd:app.export` | |

docs/whats-new.md

@@ -26,6 +26,19 @@
   compared byte for byte with the card. A copy that fails or differs is removed and reported as a failed import —
   so "import complete" means the copies are good before you format the card — and a name that is taken gets -1,
   -2… instead of being replaced.
+- Saving metadata to an XMP sidecar another application wrote no longer replaces it (issue #92): LightCraft merges its
+  fields in and keeps the rest — e.g. that application's develop settings and edit history — byte for byte. A
+  sidecar that isn't valid XMP is copied to `<name>.xmp.bak-<time>` first. With the default stem naming, a raw and a
+  JPEG with the same name (`IMG_0001.CR3` + `IMG_0001.JPG`) no longer share one sidecar: the raw keeps `IMG_0001.xmp`,
+  the JPEG uses `IMG_0001.JPG.xmp`.
+- A save that fails part-way (a full disk, a network share that drops) no longer looks like a damaged catalog
+  afterwards (issue #101): the partial write is cut off before LightCraft retries, so the next launch replays every
+  change. Catalogs already holding such a fragment load in full. Quitting while the catalog log can't be written
+  still saves your queued changes in the closing snapshot.
+- The catalog has a format version (issue #102). Opening a library from an older LightCraft upgrades it; a library
+  written by a newer LightCraft is refused with "this library was written by a newer version of LightCraft" and left
+  untouched — older versions no longer read part of it as a damaged log. Once this version has opened a library,
+  LightCraft 0.2.0 and older refuse it ("unsupported format … v2").
 - Canon CR2 photos from the EOS 7D, 50D, 60D, 550D, 600D, 1200D, 1300D, 5D Mark II and 1D Mark IV (and other
   models whose sensor starts on a green-blue row) no longer come out magenta (issue #85): the colour-filter
   layout is read from each file instead of assumed.
@@ -44,7 +57,8 @@
   `img_1-1.JPG`; on case-insensitive volumes the case change still goes through.
 - Rename Photos reports files it could not move back after a failure (issue #105), e.g. when a network share drops
   mid-batch: the error lists them (old → new) and the library points at their new names (an undoable partial rename),
-  so none shows as missing. Find Missing Photos also finds renamed files by their content, prefers a content match
+  so none shows as missing. Renaming one of a raw + JPEG pair copies their shared `IMG_0001.xmp` instead of taking
+  it away from the other (issue #92). Find Missing Photos also finds renamed files by their content, prefers a content match
   over a same-name same-size look-alike, and skips (and reports) photos it can't tell apart instead of guessing.
 - Smart albums with a rule editor: match all / any / none, nested groups, 26 fields.
 - Quick Collection and target album (B in the grid), keyword sets (⌥1–⌥9), colour-label sets.

docs/xmp-interop.md

@@ -8,8 +8,8 @@ other tools), and let LightCraft pick up edits made elsewhere.
 
 | | |
 |---|---|
-| Name | `<stem>.xmp` by default (`IMG_0001.CR3` → `IMG_0001.xmp`); `<file>.xmp` (`IMG_0001.CR3.xmp`) with `naming: "full"`. Reading accepts either (preferred first) and `.XMP`. |
-| Write | `photo.saveMetadataToFile {ids?}` (Photo ▸ Save Metadata to File, ⌘S), or automatically after every change with `library.xmpPreferences {autoWrite: true}` (File ▸ Automatically Write Changes into XMP). Slider drags are written once, when the drag ends; undo/redo rewrite the sidecar. Written atomically (temp file + rename). |
+| Name | `<stem>.xmp` by default (`IMG_0001.CR3` → `IMG_0001.xmp`); `<file>.xmp` (`IMG_0001.CR3.xmp`) with `naming: "full"`. Reading accepts either (preferred first) and `.XMP`. With stem naming, files sharing a stem don't share a sidecar: see *Shared names* below. |
+| Write | `photo.saveMetadataToFile {ids?}` (Photo ▸ Save Metadata to File, ⌘S), or automatically after every change with `library.xmpPreferences {autoWrite: true}` (File ▸ Automatically Write Changes into XMP). Slider drags are written once, when the drag ends; undo/redo rewrite the sidecar. An existing sidecar is **merged into, never replaced** (see *Saving into an existing sidecar*). Written atomically (temp file, fsync, rename). The result lists `written`, `merged` and `backups`. |
 | Read | On import (`library.import`, the report counts `sidecars`), and `photo.readMetadataFromFile {ids?}` (one undo step). For raw/DNG files without a sidecar, the XMP embedded in the file is used. |
 | Preferences | `library.xmpPreferences {autoWrite?, naming?: stem\|full}`, stored in the library's `prefs.json`. |
 
@@ -37,6 +37,39 @@ used — on import (it then also files a copied photo in its date folder) and by
 `xmp:Rating="-1"` (the XMP convention for rejected) sets the reject flag. Develop settings come from
 `lc:settings` when present (exact); otherwise from the `crs:` fields below (approximate).
 
+## Saving into an existing sidecar
+
+A sidecar may already hold another application's data — e.g. its `crs:` develop settings and `xmpMM:History` — often
+the only copy of those edits outside that application's catalog. Saving never drops it:
+
+- LightCraft **owns** the properties in the table above: `xmp:Rating`, `xmp:Label`, `dc:title`, `dc:description`,
+  `dc:rights`, `dc:creator`, `dc:subject`, `Iptc4xmpCore:Location`, `Iptc4xmpCore:AltTextAccessibility`,
+  `Iptc4xmpCore:ExtDescrAccessibility`, `photoshop:City`/`State`/`Country`, `xmpRights:Marked`/`UsageTerms`/
+  `WebStatement` and everything in `lc:`. They are replaced on every save, and removed when LightCraft has no value
+  (clearing a title in LightCraft clears it in the file). All of them are read back on import, so the library starts
+  from what the sidecar said.
+- The **capture time** (`exif:DateTimeOriginal`, `photoshop:DateCreated`) and **GPS** (`exif:GPSLatitude`,
+  `exif:GPSLongitude`) are replaced only when LightCraft has a value; otherwise the file's stay.
+- **Everything else is kept byte for byte**: other namespaces (`crs:`, `xmpMM:`, `lr:hierarchicalSubject`, unknown
+  ones), `xmp:CreatorTool`, comments, the packet wrapper and padding. LightCraft's properties go into one
+  `rdf:Description` of their own; owned properties written by another application (in attribute or element form) are
+  removed from its description, which otherwise stays as it was.
+- A sidecar that can't be read as XMP (not well-formed, not UTF-8, no `rdf:RDF`) is first copied to
+  `<name>.xmp.bak-<date><time>` (`-1`, `-2`… if taken — a backup is never overwritten), then replaced. A sidecar that
+  can't be read at all (permissions) is left alone and the save fails.
+
+Limits: LightCraft writes keywords to `dc:subject` only, so another application's `lr:hierarchicalSubject` is kept as
+it was and may still list keywords removed in LightCraft. LightCraft doesn't write `crs:`: the other application's
+develop settings stay as that application left them, next to LightCraft's own (`lc:settings`, which LightCraft reads
+first).
+
+## Shared names
+
+With stem naming, `IMG_0001.CR3` and `IMG_0001.JPG` map to the same `IMG_0001.xmp`. When two or more files in the
+library share a stem, the stem sidecar belongs to one of them — a raw first, otherwise the first by file name — and
+the others write and read `<file>.xmp` (`IMG_0001.JPG.xmp`), falling back to the stem sidecar for reading when they
+have none. So saving one photo never overwrites the other's metadata (`Session::sidecar_naming`).
+
 ## Reading `crs:` develop fields
 
 Many raw developers store edits as `crs:` properties (`http://ns.adobe.com/camera-raw-settings/1.0/`) in sidecars, in