Add transfer-source snapshot API

Introduce a reusable decoded-source snapshot flow and fileless transfer helpers. Public API additions include TransferSourceSnapshot, read_transfer_source_snapshot_file/bytes, build_transfer_source_snapshot, prepare_metadata_for_target_snapshot, execute_prepared_transfer_snapshot (including an overload that accepts target bytes) and execute_prepared_transfer_bundle, plus related option/result structs and stable read error enums. Implementations were added to copy/finalize MetaStore state, decode from bytes/files with proper resource policy handling, and map decode/map failures into transfer statuses. XMP sidecar/embedded controls were extended with XmpExistingDestinationSidecarState and new execution options. Documentation and Sphinx quick-start/host-integration docs were updated with a "Read Once / Save Later" section and Python examples; Python bindings and tests were adjusted accordingly. Note: current snapshots are decoded-store-backed (not raw passthrough).

Author: ssh4net

docs/development.md

@@ -1269,6 +1269,23 @@ Python transfer entry point:
   - same probe contract, but allows `include_payloads=True` and returns raw
     payload bytes (`bytes`) in `blocks[i].payload`.
   - intended for explicit raw/unsafe workflows only.
+- Snapshot/fileless Python helpers:
+  - `openmeta.read_transfer_source_snapshot_file(...)` and
+    `openmeta.read_transfer_source_snapshot_bytes(...)` expose the reusable
+    decoded-source contract directly.
+  - `Document.build_transfer_source_snapshot()` and
+    `openmeta.build_transfer_source_snapshot(document)` mirror the C++
+    `MetaStore -> TransferSourceSnapshot` builder.
+  - `openmeta.transfer_snapshot_probe(...)` /
+    `openmeta.transfer_snapshot_file(...)` expose the core snapshot-based
+    execute/persist path, including host-owned `target_bytes`.
+  - `openmeta.unsafe_transfer_snapshot_probe(...)` /
+    `openmeta.unsafe_transfer_snapshot_file(...)` add optional edited-output
+    bytes for explicit unsafe workflows.
+  - the Python transfer wrappers now distinguish
+    `xmp_existing_sidecar_base_path` from `xmp_sidecar_base_path`, and they
+    also expose `xmp_existing_destination_embedded_path` plus
+    `xmp_existing_destination_sidecar_state` for pathless host flows.
 
 Transfer probe contract hardening (stable machine fields):
 - `overall_status`, `overall_status_name`

docs/host_integration.md

@@ -253,6 +253,74 @@ openmeta::PersistPreparedTransferFileResult saved =
 This path is usually simpler than a custom adapter when the container already
 exists.
 
+### Read Once, Save Later
+
+If your host already decoded source metadata during the initial load, keep a
+decoded source snapshot and execute the later save without reopening the
+source file:
+
+```cpp
+#include "openmeta/metadata_transfer.h"
+
+const openmeta::ReadTransferSourceSnapshotFileResult snapshot =
+    openmeta::read_transfer_source_snapshot_file("source.jpg");
+
+openmeta::ExecutePreparedTransferSnapshotOptions options;
+options.prepare.target_format = openmeta::TransferTargetFormat::Tiff;
+options.edit_target_path      = "target.tif";
+options.execute.edit_apply    = true;
+
+openmeta::ExecutePreparedTransferFileResult result =
+    openmeta::execute_prepared_transfer_snapshot(
+        snapshot.snapshot, options);
+```
+
+Python mirrors that same host-facing snapshot flow:
+
+```python
+from pathlib import Path
+
+import openmeta
+
+snapshot_info = openmeta.read_transfer_source_snapshot_file("source.jpg")
+snapshot = snapshot_info["snapshot"]
+
+result = openmeta.transfer_snapshot_file(
+    snapshot,
+    target_format=openmeta.TransferTargetFormat.Tiff,
+    edit_target_path="target.tif",
+    target_bytes=Path("target.tif").read_bytes(),
+    output_path="edited.tif",
+)
+```
+
+Current source snapshots are decoded-store-backed. They are intended for the
+normal EXIF/XMP/ICC/IPTC transfer flow, not raw source-packet passthrough.
+For hosts that still own the bundle/execution split, the lower-level
+`prepare_metadata_for_target_snapshot(...)` entry point remains available.
+If the host already has a decoded `MetaStore`, build a reusable snapshot with
+`build_transfer_source_snapshot(store)`. If it already owns the source bytes in
+memory, use `read_transfer_source_snapshot_bytes(bytes)` instead of the
+file-path reader.
+In Python, a previously decoded `Document` can be turned into a reusable
+snapshot through `doc.build_transfer_source_snapshot()` or
+`openmeta.build_transfer_source_snapshot(doc)`.
+If it also owns the destination bytes in memory, call the overload
+`execute_prepared_transfer_snapshot(snapshot, target_bytes, options)`.
+If it already holds a prepared bundle, use
+`execute_prepared_transfer_bundle(bundle, target_bytes, options)` instead.
+Snapshot execution supports the same existing-sidecar merge and destination
+carrier-precedence controls as the file helper; when loading an existing
+sidecar it defaults to `edit_target_path` unless
+`xmp_existing_sidecar_base_path` is set explicitly.
+For embedded-only writeback with sidecar cleanup and no filesystem path, set
+`xmp_existing_destination_sidecar_state` explicitly so OpenMeta can return a
+cleanup decision without guessing a sidecar location.
+Python now exposes those same split path/state controls directly:
+`xmp_existing_sidecar_base_path`, `xmp_sidecar_base_path`,
+`xmp_existing_destination_embedded_path`, and
+`xmp_existing_destination_sidecar_state`.
+
 ## 7. Use The Optional Adobe DNG SDK Bridge
 
 If OpenMeta was built with `OPENMETA_WITH_DNG_SDK_ADAPTER=ON`, you can use the

docs/metadata_transfer_plan.md

@@ -418,6 +418,11 @@ Current behavior:
   `transfer_file(...)` and `unsafe_transfer_file(...)`, and the public Python
   wrapper uses that core helper instead of maintaining its own sidecar write
   and cleanup implementation
+- the Python binding now also exposes the reusable decoded-source path through
+  `read_transfer_source_snapshot_file(...)`,
+  `read_transfer_source_snapshot_bytes(...)`,
+  `Document.build_transfer_source_snapshot()`, and
+  `transfer_snapshot_probe(...)` / `transfer_snapshot_file(...)`
 - public API regression coverage now asserts dual-write roundtrip and
   persistence behavior across `jpeg`, `tiff`, `dng`, `png`, `webp`, `jp2`,
   `jxl`, `heif`, `avif`, and `cr3`

docs/quick_start.md

@@ -221,6 +221,71 @@ Use the same pattern for other file-backed targets:
 - `TransferTargetFormat::Jxl`
 - bounded BMFF targets such as `Heif`, `Avif`, and `Cr3`
 
+### Read Once And Reuse Later
+
+If your application already decoded source metadata earlier, keep a decoded
+source snapshot and execute the later save without reopening the source file:
+
+```cpp
+#include "openmeta/metadata_transfer.h"
+
+const openmeta::ReadTransferSourceSnapshotFileResult snapshot =
+    openmeta::read_transfer_source_snapshot_file("source.jpg");
+
+openmeta::ExecutePreparedTransferSnapshotOptions options;
+options.prepare.target_format = openmeta::TransferTargetFormat::Tiff;
+options.edit_target_path      = "target.tif";
+options.execute.edit_apply    = true;
+
+const openmeta::ExecutePreparedTransferFileResult result =
+    openmeta::execute_prepared_transfer_snapshot(
+        snapshot.snapshot, options);
+```
+
+Python exposes the same reusable snapshot flow for host code:
+
+```python
+from pathlib import Path
+
+import openmeta
+
+snapshot_info = openmeta.read_transfer_source_snapshot_file("source.jpg")
+snapshot = snapshot_info["snapshot"]
+
+result = openmeta.transfer_snapshot_probe(
+    snapshot,
+    target_format=openmeta.TransferTargetFormat.Tiff,
+    edit_target_path="target.tif",
+    target_bytes=Path("target.tif").read_bytes(),
+)
+```
+
+Current source snapshots are decoded-store-backed. They are meant for the
+common EXIF/XMP/ICC/IPTC transfer workflow, not raw source-packet passthrough.
+If the host owns the final file write path, the lower-level
+`prepare_metadata_for_target_snapshot(...)` entry point remains available.
+If the host already has a decoded `MetaStore`, build a reusable snapshot with
+`build_transfer_source_snapshot(store)`. If it already owns the source bytes in
+memory, use `read_transfer_source_snapshot_bytes(bytes)` instead of the
+file-path reader.
+In Python, if the host already has `doc = openmeta.read(...)`, call
+`doc.build_transfer_source_snapshot()` or
+`openmeta.build_transfer_source_snapshot(doc)` instead of reopening the file.
+If it also owns the destination bytes in memory, call the overload
+`execute_prepared_transfer_snapshot(snapshot, target_bytes, options)`.
+If it already holds a prepared bundle, use
+`execute_prepared_transfer_bundle(bundle, target_bytes, options)` instead.
+Snapshot execution supports the same existing-sidecar merge and destination
+carrier-precedence controls as the file helper; when loading an existing
+sidecar it defaults to `edit_target_path` unless
+`xmp_existing_sidecar_base_path` is set explicitly.
+For embedded-only writeback with sidecar cleanup and no filesystem path, set
+`xmp_existing_destination_sidecar_state` explicitly so OpenMeta can return a
+cleanup decision without guessing a sidecar location.
+The Python snapshot helpers intentionally cover the core transfer/edit/persist
+path. The older `transfer_probe(...)` / `unsafe_transfer_probe(...)` entry
+points remain the broader artifact-dump/debug surface.
+
 ## 8. Prepare Metadata For Host-Owned Encoders
 
 Some applications do not want a file helper. They already own the encoder or

docs/sphinx/host_integration.rst

@@ -215,6 +215,75 @@ helper instead of building your own writer path.
    openmeta::PersistPreparedTransferFileResult saved =
        openmeta::persist_prepared_transfer_file_result(exec, persist);
 
+Read once, save later
+~~~~~~~~~~~~~~~~~~~~~
+
+If your host already decoded source metadata during the initial load, keep a
+decoded source snapshot and execute the later save without reopening the
+source file.
+
+.. code-block:: cpp
+
+   #include "openmeta/metadata_transfer.h"
+
+   openmeta::ReadTransferSourceSnapshotFileResult snapshot =
+       openmeta::read_transfer_source_snapshot_file("source.jpg");
+
+   openmeta::ExecutePreparedTransferSnapshotOptions options;
+   options.prepare.target_format = openmeta::TransferTargetFormat::Tiff;
+   options.edit_target_path      = "target.tif";
+   options.execute.edit_apply    = true;
+
+   openmeta::ExecutePreparedTransferFileResult result =
+       openmeta::execute_prepared_transfer_snapshot(
+           snapshot.snapshot, options);
+
+Python mirrors that same host-facing snapshot flow:
+
+.. code-block:: python
+
+   from pathlib import Path
+
+   import openmeta
+
+   snapshot_info = openmeta.read_transfer_source_snapshot_file("source.jpg")
+   snapshot = snapshot_info["snapshot"]
+
+   result = openmeta.transfer_snapshot_file(
+       snapshot,
+       target_format=openmeta.TransferTargetFormat.Tiff,
+       edit_target_path="target.tif",
+       target_bytes=Path("target.tif").read_bytes(),
+       output_path="edited.tif",
+   )
+
+Current source snapshots are decoded-store-backed. They are intended for the
+normal EXIF/XMP/ICC/IPTC transfer flow, not raw source-packet passthrough.
+If the host still owns the bundle/execution split, the lower-level
+``prepare_metadata_for_target_snapshot(...)`` entry point remains available.
+If the host already has a decoded ``MetaStore``, build a reusable snapshot with
+``build_transfer_source_snapshot(store)``. If it already owns the source bytes
+in memory, use ``read_transfer_source_snapshot_bytes(bytes)`` instead of the
+file-path reader.
+In Python, a previously decoded ``Document`` can be turned into a reusable
+snapshot through ``doc.build_transfer_source_snapshot()`` or
+``openmeta.build_transfer_source_snapshot(doc)``.
+If it also owns the destination bytes in memory, call the overload
+``execute_prepared_transfer_snapshot(snapshot, target_bytes, options)``.
+If it already holds a prepared bundle, use
+``execute_prepared_transfer_bundle(bundle, target_bytes, options)`` instead.
+Snapshot execution supports the same existing-sidecar merge and destination
+carrier-precedence controls as the file helper; when loading an existing
+sidecar it defaults to ``edit_target_path`` unless
+``xmp_existing_sidecar_base_path`` is set explicitly.
+For embedded-only writeback with sidecar cleanup and no filesystem path, set
+``xmp_existing_destination_sidecar_state`` explicitly so OpenMeta can return a
+cleanup decision without guessing a sidecar location.
+Python now exposes those same split path/state controls directly:
+``xmp_existing_sidecar_base_path``, ``xmp_sidecar_base_path``,
+``xmp_existing_destination_embedded_path``, and
+``xmp_existing_destination_sidecar_state``.
+
 Optional Adobe DNG SDK bridge
 -----------------------------
 

docs/sphinx/quick_start.rst

@@ -176,6 +176,73 @@ Copy metadata into an existing target
 Use the same pattern for ``Tiff``, ``Dng``, ``Png``, ``Webp``, ``Jp2``,
 ``Jxl``, and bounded BMFF targets such as ``Heif``, ``Avif``, and ``Cr3``.
 
+Read once and reuse later
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If your application already decoded source metadata earlier, keep a decoded
+source snapshot and execute the later save without reopening the source file.
+
+.. code-block:: cpp
+
+   #include "openmeta/metadata_transfer.h"
+
+   openmeta::ReadTransferSourceSnapshotFileResult snapshot =
+       openmeta::read_transfer_source_snapshot_file("source.jpg");
+
+   openmeta::ExecutePreparedTransferSnapshotOptions options;
+   options.prepare.target_format = openmeta::TransferTargetFormat::Tiff;
+   options.edit_target_path      = "target.tif";
+   options.execute.edit_apply    = true;
+
+   openmeta::ExecutePreparedTransferFileResult result =
+       openmeta::execute_prepared_transfer_snapshot(
+           snapshot.snapshot, options);
+
+Python exposes the same reusable snapshot flow for host code:
+
+.. code-block:: python
+
+   from pathlib import Path
+
+   import openmeta
+
+   snapshot_info = openmeta.read_transfer_source_snapshot_file("source.jpg")
+   snapshot = snapshot_info["snapshot"]
+
+   result = openmeta.transfer_snapshot_probe(
+       snapshot,
+       target_format=openmeta.TransferTargetFormat.Tiff,
+       edit_target_path="target.tif",
+       target_bytes=Path("target.tif").read_bytes(),
+   )
+
+Current source snapshots are decoded-store-backed. They are intended for the
+common EXIF/XMP/ICC/IPTC transfer workflow, not raw source-packet passthrough.
+If the host still owns the bundle/execution split, the lower-level
+``prepare_metadata_for_target_snapshot(...)`` entry point remains available.
+If the host already has a decoded ``MetaStore``, build a reusable snapshot with
+``build_transfer_source_snapshot(store)``. If it already owns the source bytes
+in memory, use ``read_transfer_source_snapshot_bytes(bytes)`` instead of the
+file-path reader.
+In Python, if the host already has ``doc = openmeta.read(...)``, call
+``doc.build_transfer_source_snapshot()`` or
+``openmeta.build_transfer_source_snapshot(doc)`` instead of reopening the
+file.
+If it also owns the destination bytes in memory, call the overload
+``execute_prepared_transfer_snapshot(snapshot, target_bytes, options)``.
+If it already holds a prepared bundle, use
+``execute_prepared_transfer_bundle(bundle, target_bytes, options)`` instead.
+Snapshot execution supports the same existing-sidecar merge and destination
+carrier-precedence controls as the file helper; when loading an existing
+sidecar it defaults to ``edit_target_path`` unless
+``xmp_existing_sidecar_base_path`` is set explicitly.
+For embedded-only writeback with sidecar cleanup and no filesystem path, set
+``xmp_existing_destination_sidecar_state`` explicitly so OpenMeta can return a
+cleanup decision without guessing a sidecar location.
+The Python snapshot helpers intentionally cover the core transfer/edit/persist
+path. The older ``transfer_probe(...)`` / ``unsafe_transfer_probe(...)``
+entry points remain the broader artifact-dump/debug surface.
+
 Next steps
 ----------