slide2vec 5.5.0__tar.gz → 5.6.0__tar.gz

{slide2vec-5.5.0 → slide2vec-5.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slide2vec
-Version: 5.5.0
+Version: 5.6.0
 Summary: Embedding of whole slide images with Foundation Models
 Author-email: Clément Grisi <clement.grisi@radboudumc.nl>
 License-Expression: Apache-2.0
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.3.0
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.4.0
 Requires-Dist: omegaconf
 Requires-Dist: matplotlib
 Requires-Dist: numpy<2
@@ -65,7 +65,7 @@ Requires-Dist: numpy<2; extra == "fm"
 Requires-Dist: pandas; extra == "fm"
 Requires-Dist: pillow; extra == "fm"
 Requires-Dist: rich; extra == "fm"
-Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.3.0; extra == "fm"
+Requires-Dist: hs2p[asap,cucim,openslide,sam2,vips]>=4.4.0; extra == "fm"
 Requires-Dist: wandb; extra == "fm"
 Requires-Dist: torch<2.8,>=2.3; extra == "fm"
 Requires-Dist: torchvision>=0.18.0; extra == "fm"

{slide2vec-5.5.0 → slide2vec-5.6.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "slide2vec"
-version = "5.5.0"
+version = "5.6.0"
 description = "Embedding of whole slide images with Foundation Models"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -21,7 +21,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "hs2p[asap,cucim,openslide,sam2,vips]>=4.3.0",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.0",
     "omegaconf",
     "matplotlib",
     "numpy<2",
@@ -88,7 +88,7 @@ fm = [
     "pandas",
     "pillow",
     "rich",
-    "hs2p[asap,cucim,openslide,sam2,vips]>=4.3.0",
+    "hs2p[asap,cucim,openslide,sam2,vips]>=4.4.0",
     "wandb",
     "torch>=2.3,<2.8",
     "torchvision>=0.18.0",
@@ -141,12 +141,13 @@ slide2vec = ["py.typed"]
 "slide2vec.configs" = ["*.yaml", "models/*.yaml", "preprocessing/*.yaml"]
 
 [tool.pytest.ini_options]
-addopts = "--cov=slide2vec"
+addopts = "--cov=slide2vec -m 'not gpu_integration'"
 testpaths = [
     "tests",
 ]
 markers = [
     "heavy: real-weight foundation-model inference on CPU; minutes per test. Excluded from the PR suite via `-m 'not heavy'`; run on the scheduled/manual heavy workflow (.github/workflows/nightly-heavy.yaml).",
+    "gpu_integration: real one-GPU versus multi-GPU parity; requires at least two visible CUDA devices. Run explicitly with `CUDA_VISIBLE_DEVICES=0,1 python -m pytest -m gpu_integration --no-cov`.",
 ]
 
 [tool.mypy]
@@ -167,7 +168,7 @@ no_implicit_reexport = true
 max-line-length = 160
 
 [tool.bumpver]
-current_version = "5.5.0"
+current_version = "5.6.0"
 version_pattern = "MAJOR.MINOR.PATCH"
 commit = false       # We do version bumping in CI, not as a commit
 tag = false          # Git tag already exists — we don't auto-tag

{slide2vec-5.5.0 → slide2vec-5.6.0}/slide2vec/__init__.py

@@ -22,7 +22,7 @@ from slide2vec.artifacts import (
 )
 
 
-__version__ = "5.5.0"
+__version__ = "5.6.0"
 
 __all__ = [
     "Model",

{slide2vec-5.5.0 → slide2vec-5.6.0}/slide2vec/api.py

@@ -19,9 +19,10 @@ from slide2vec.artifacts import (
     SlideEmbeddingArtifact,
     TileEmbeddingArtifact,
 )
+from slide2vec.configs.resources import load_config
 from slide2vec.encoders.registry import (
     encoder_registry,
-    resolve_preprocessing_defaults,
+    resolve_preprocessing_fields,
 )
 from slide2vec.encoders.validation import validate_encoder_config
 from slide2vec.runtime.model_settings import (
@@ -63,14 +64,42 @@ DEFAULT_MASKS: dict[str, Any] = {
     "min_coverage": {"background": None, "tissue": 0.01},
 }
 
+_REQUESTED_TILE_SIZE_INTERPOLATION = "${tiling.params.requested_tile_size_px}"
+
+
+def _load_default_preprocessing() -> dict[str, dict[str, Any]]:
+    """Read the public nested defaults from the package's canonical YAML config."""
+    from omegaconf import OmegaConf
+
+    tiling = load_config("default").tiling
+    defaults: dict[str, dict[str, Any]] = {}
+    for public_name, config_name in (
+        ("segmentation", "seg_params"),
+        ("filtering", "filter_params"),
+        ("preview", "preview"),
+    ):
+        section = OmegaConf.to_container(getattr(tiling, config_name), resolve=False)
+        if not isinstance(section, dict):
+            raise TypeError(f"tiling.{config_name} must be a mapping")
+        defaults[public_name] = section
+    defaults["preview"]["tissue_contour_color"] = tuple(
+        defaults["preview"]["tissue_contour_color"]
+    )
+    return defaults
+
+
+#: Complete defaults for the nested public preprocessing sections, loaded from
+#: ``configs/default.yaml`` so Python and YAML entry points share one source.
+DEFAULT_PREPROCESSING = _load_default_preprocessing()
 
-def _deep_merge_masks(base: Mapping[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
+
+def _deep_merge_dicts(base: Mapping[str, Any], override: Mapping[str, Any]) -> dict[str, Any]:
     """Deep-merge *override* onto a copy of *base* (nested dicts merge key-by-key)."""
     merged = copy.deepcopy(dict(base))
     for key, value in override.items():
         existing = merged.get(key)
         if isinstance(value, Mapping) and isinstance(existing, dict):
-            merged[key] = _deep_merge_masks(existing, value)
+            merged[key] = _deep_merge_dicts(existing, value)
         else:
             merged[key] = copy.deepcopy(value)
     return merged
@@ -80,7 +109,7 @@ def resolve_masks(masks: Mapping[str, Any] | None) -> dict[str, Any]:
     """Complete a (possibly partial) ``masks`` mapping by merging it over :data:`DEFAULT_MASKS`."""
     if not masks:
         return copy.deepcopy(DEFAULT_MASKS)
-    return _deep_merge_masks(DEFAULT_MASKS, masks)
+    return _deep_merge_dicts(DEFAULT_MASKS, masks)
 
 
 def _masks_to_plain_dict(node: Any) -> dict[str, Any]:
@@ -103,7 +132,7 @@ def _masks_to_plain_dict(node: Any) -> dict[str, Any]:
 class PreprocessingConfig:
     """Configuration for slide tiling and preprocessing."""
 
-    #: Slide reading backend. ``"auto"`` tries cucim → openslide → vips in order.
+    #: Slide reading backend. ``"auto"`` tries cucim → vips → openslide → asap.
     #: Explicit choices: ``"cucim"``, ``"openslide"``, ``"vips"``, ``"asap"``.
     backend: str = "auto"
     #: Source-mask reading backend, resolved independently from the *mask* path
@@ -140,19 +169,23 @@ class PreprocessingConfig:
     adaptive_batching: bool = False
     #: Group adjacent tiles into supertile batches for faster I/O.
     use_supertiles: bool = True
-    #: JPEG decode library — ``"turbojpeg"`` (default) or ``"pillow"``.
-    jpeg_backend: str = "turbojpeg"
+    #: JPEG encoder for extracted tile archives — portable ``"pil"`` (default) or
+    #: explicitly requested ``"turbojpeg"``.
+    jpeg_backend: str = "pil"
     #: Number of CuCIM reader threads.
     num_cucim_workers: int = 4
     #: Skip slides already present in the output directory when ``True``.
     resume: bool = False
-    #: Forwarded to hs2p segmentation config. Supported keys: ``method``,
-    #: ``downsample``, ``sam2_device``. See :doc:`preprocessing` for details.
+    #: Partial override forwarded to hs2p segmentation config. Supported keys:
+    #: ``method``, ``downsample``, ``sam2_device``. Omitted keys retain the
+    #: standard configuration defaults. See :doc:`preprocessing` for details.
     segmentation: dict[str, Any] = field(default_factory=dict)
-    #: Forwarded to hs2p tile-filtering config.
+    #: Partial override forwarded to hs2p tile-filtering config. Omitted keys
+    #: retain the standard configuration defaults.
     filtering: dict[str, Any] = field(default_factory=dict)
-    #: Controls whether hs2p writes mask and tiling preview images.
-    #: Keys: ``save_mask_preview``, ``save_tiling_preview``, ``downsample``.
+    #: Partial override controlling whether hs2p writes mask and tiling preview
+    #: images. Keys: ``save_mask_preview``, ``save_tiling_preview``,
+    #: ``downsample``. Omitted keys retain the standard configuration defaults.
     preview: dict[str, Any] = field(default_factory=dict)
     #: Annotation-mask vocabulary forwarded to hs2p's sampling resolver. Keys:
     #: ``output_mode``, ``pixel_mapping``, ``colors``, ``min_coverage``. A partial
@@ -166,6 +199,36 @@ class PreprocessingConfig:
     independent_sampling: bool = True
 
     def __post_init__(self) -> None:
+        filtering_defaults = DEFAULT_PREPROCESSING["filtering"]
+        filtering_override = self.filtering
+        if self.requested_tile_size_px is not None:
+            filtering_defaults = {
+                **filtering_defaults,
+                "ref_tile_size": int(self.requested_tile_size_px),
+            }
+            if (
+                filtering_override.get("ref_tile_size")
+                == _REQUESTED_TILE_SIZE_INTERPOLATION
+            ):
+                filtering_override = {
+                    **filtering_override,
+                    "ref_tile_size": int(self.requested_tile_size_px),
+                }
+        object.__setattr__(
+            self,
+            "segmentation",
+            _deep_merge_dicts(DEFAULT_PREPROCESSING["segmentation"], self.segmentation),
+        )
+        object.__setattr__(
+            self,
+            "filtering",
+            _deep_merge_dicts(filtering_defaults, filtering_override),
+        )
+        object.__setattr__(
+            self,
+            "preview",
+            _deep_merge_dicts(DEFAULT_PREPROCESSING["preview"], self.preview),
+        )
         # Complete a (possibly partial) masks mapping against the shipped default.
         object.__setattr__(self, "masks", resolve_masks(self.masks))
 
@@ -238,6 +301,7 @@ class ExecutionOptions:
     batch_size: int = 32
     #: DataLoader worker count per GPU rank. ``None`` means auto
     #: (capped by CPU / SLURM limit, then split across the resolved GPU count).
+    #: Image-only routes safely use zero when auto selection happens after model loading.
     num_workers_per_gpu: int | None = None
     #: Tiling worker count. ``None`` means auto (capped by CPU / SLURM limit).
     num_preprocessing_workers: int | None = None
@@ -322,6 +386,12 @@ class ExecutionOptions:
             return self.num_workers_per_gpu
         return max(1, cpu_worker_limit() // self.num_gpus)
 
+    def resolved_image_num_workers_per_gpu(self) -> int:
+        """Resolve safe post-model-load image-transform workers for this rank."""
+        if self.num_workers_per_gpu is None:
+            return 0
+        return self.resolved_num_workers_per_gpu()
+
     def with_output_dir(self, output_dir: PathLike | None) -> "ExecutionOptions":
         if output_dir is None:
             return self
@@ -346,7 +416,8 @@ class DenseOptions:
     target_size: int
     #: Relative spacing tolerance for pyramid level selection.
     tolerance: float = 0.05
-    #: Slide reading backend. ``"auto"`` resolves per slide (cucim → openslide → vips).
+    #: Slide reading backend. ``"auto"`` resolves per slide
+    #: (cucim → vips → openslide → asap).
     backend: str = "auto"
     #: Padding mode used to pad the tile up to the encoder's patch multiple.
     #: One of ``"reflect"`` / ``"replicate"`` / ``"constant"`` / ``"zero"``.
@@ -373,26 +444,37 @@ class DenseOptions:
 
 @dataclass(frozen=True, kw_only=True)
 class DenseImageOptions:
-    """Dense ``(d, gh, gw)`` grid extraction over pre-cropped images (issue #235).
-
-    :class:`DenseOptions` minus everything that only a slide has: there is no spacing, no
-    tolerance and no reading backend here, because the image *is* the region — it is read
-    from disk at the size it was written. What remains is the same supervision geometry and
-    the same dense encode knobs, so a run migrating from ROIs to image/mask pairs keeps its
-    recipe.
-
-    ``target_size`` is a **declaration**, not a resize: the dense transform is
-    normalization-only, so every image must already be exactly this size and one that is not
-    is an error rather than a silent rescale. Declaring it up front is what lets the
-    effective encoder input be validated (and the encoder's variable-input constructor
-    settings resolved) before a single image is decoded. A run whose images are not all the
-    same size is therefore several runs, one per geometry — which is also the only way their
-    grids could be batched downstream.
+    """Dense ``(d, gh, gw)`` extraction over pre-cropped images.
+
+    One run has one reader regime. ``.png``, ``.jpg``, and ``.jpeg`` inputs
+    (case-insensitive) use Pillow and treat numeric ``spacing_um`` as an assertion about
+    unchanged pixels. hs2p-supported WSI formats form the spacing-readable regime: hs2p
+    resolves source spacing, backend, pyramid level, tolerance, complete-extent read, and
+    area downsampling at the one requested run-level ``spacing_um``. Omitted spacing resolves
+    the encoder's single registry default for spacing-readable inputs and requires an
+    explicit value when no default is available.
+
+    ``ImageSpec.spacing_at_level_0`` overrides level-0 metadata only for spacing-readable
+    sources. ``target_size`` is always a strict post-read declaration, never a fit-to-size
+    request: each final pixel array must already be exactly this size. Declaring it up front
+    lets the effective encoder input be validated (and variable-input constructor settings
+    resolved) before model loading or pixel decoding. Differing final geometries therefore
+    require separate runs.
     """
 
     #: Supervision geometry in pixels the dense grid registers to: a square side length, or
     #: an explicit ``(height, width)`` for non-square images.
     target_size: int | tuple[int, int]
+    #: Positive, finite run-level spacing in µm/px: asserted for raster pixels and requested
+    #: for spacing-readable reads. ``None`` is unknown for raster and resolves the encoder's
+    #: single registry default for spacing-readable inputs.
+    spacing_um: float | None = None
+    #: Relative spacing tolerance used by hs2p for spacing-readable level selection; raster
+    #: reads have no tolerance result.
+    tolerance: float = 0.05
+    #: Requested hs2p backend for spacing-readable inputs. ``"auto"`` is resolved in the
+    #: parent; raster images always resolve to Pillow.
+    backend: str = "auto"
     #: Padding mode used to pad the image up to the encoder's patch multiple.
     #: One of ``"reflect"`` / ``"replicate"`` / ``"constant"`` / ``"zero"``.
     pad_mode: str = "reflect"
@@ -432,18 +514,21 @@ class SlideRegions:
 
 @dataclass(frozen=True, kw_only=True)
 class ImageSpec:
-    """One pre-cropped image to embed: ``(sample_id, image_path)``.
+    """One named image source: ``(sample_id, image_path, spacing_at_level_0)``.
 
     The input unit of :meth:`Model.embed_images` — the Given-geometry counterpart of
-    :class:`SlideRegions`. There is no slide, no coordinate and no spacing here: the caller
-    holds an image file it never asked slide2vec to produce (a public patch benchmark
-    sample), and names it. ``sample_id`` is the artifact's whole identity, so it must be
-    unique within a run and a valid filename component; slide2vec never derives it from the
-    path, because two directories can hold the same filename.
+    :class:`SlideRegions`. ``spacing_at_level_0`` represents caller metadata for
+    spacing-readable image sources. The current raster paths reject a non-null value: a
+    pre-cropped PNG/JPEG has no slide pyramid or level-0 read plan to override. ``sample_id``
+    is the artifact's whole identity, so it must be unique within a run and a valid filename
+    component.
     """
 
     sample_id: str
     image_path: PathLike
+    #: Optional caller override for the source's level-0 spacing. Raster image paths reject
+    #: non-null overrides because they have no slide pyramid or level-0 read plan.
+    spacing_at_level_0: float | None = None
 
 
 @dataclass(frozen=True, kw_only=True)
@@ -779,19 +864,31 @@ class Model:
         — whole-image, or by sliding the encoder's native field and blending the token grids
         — and written to ``dense_image_embeddings/<sample_id>.pt`` plus a geometry sidecar.
         The run splits its images across all visible GPUs (``execution.num_gpus``);
-        ``num_gpus=1`` encodes fully in-process. Resume is automatic — images whose sidecar
-        already exists are skipped. Returns one
+        ``num_gpus=1`` encodes fully in-process. Resume is automatic: an image is skipped
+        only when its payload exists and its sidecar records the same normalized source
+        identity and complete extraction recipe. Returns one
         :class:`~slide2vec.artifacts.DenseImageArtifact` per input image, in input order.
 
-        It differs from :meth:`embed_regions_dense` in exactly one respect: there is no
-        slide, no coordinate and no spacing→level plan, because the image *is* the region.
-        Everything else is shared, including the effective encoder input — the padded image
+        One run uses one reader regime. Raster inputs are exactly ``.png``, ``.jpg``, and
+        ``.jpeg`` (case-insensitive) and always use Pillow's RGB decoder.
+        ``dense.spacing_um`` asserts the scale those unchanged pixels already have; ``None``
+        records unknown spacing. hs2p-supported WSI inputs are spacing-readable:
+        ``dense.spacing_um`` requests one physical read scale, or ``None`` resolves the
+        encoder's single registry default. The parent resolves each source's metadata,
+        concrete backend, native level, tolerance result, and final geometry before resume;
+        hs2p reads that complete level and area-downsamples when required, but never
+        upsamples. ``ImageSpec.spacing_at_level_0`` overrides source metadata only in this
+        spacing-readable regime and is rejected for raster inputs.
+
+        Everything after reading is shared with the slide path, including the effective encoder input — the padded image
         for a whole-image run, one patch-aligned window for a sliding one — which is declared
         before any image is decoded, so a geometry the encoder cannot accept raises here
         rather than on a torchrun rank's first forward pass.
 
-        ``dense.target_size`` is a declaration, not a resize request: dense extraction never
-        rescales, so every image must already be that size (a non-square ``(h, w)`` is fine).
+        ``dense.target_size`` is a strict post-read declaration, not a fit-to-size request:
+        every final image must already be that size (a non-square ``(h, w)`` is fine).
+        Spacing-driven area downsampling establishes physical scale; it never repairs a
+        mismatch with the declared geometry.
         """
         from slide2vec.runtime.dense_image_stage import embed_images_dense
 
@@ -822,8 +919,11 @@ class Model:
         heterogeneously sized (2048x1536 beside 96x96) and were never requested, so the
         encoder's shipped transform is the contract and slide2vec *records* the resulting
         encoder input size as run provenance rather than validating it. That also means
-        preprocessing runs itemwise in the loader workers — differently sized images cannot
-        be stacked before they are resized.
+        preprocessing runs itemwise before stacking — in-process by default, or in spawned
+        loader workers when ``num_workers_per_gpu`` is explicit — because differently sized
+        images cannot be stacked before they are resized. ``ImageSpec.spacing_at_level_0``
+        is rejected here rather than ignored because this path has no slide level-0 read
+        plan.
         """
         from slide2vec.runtime.image_stage import embed_images
 
@@ -1163,32 +1263,27 @@ def _resolve_direct_api_preprocessing(
     preprocessing: PreprocessingConfig | None,
 ) -> PreprocessingConfig:
     name = model.name
-    defaults = None
-
-    def ensure_defaults() -> tuple[int, float]:
-        nonlocal defaults
-        if defaults is None:
-            defaults = _default_preprocessing_from_registry(name)
-        return defaults
 
     if preprocessing is None:
-        requested_tile_size_px, requested_spacing_um = ensure_defaults()
+        default_tile_size_px, default_spacing_um = _default_preprocessing_from_registry(name)
         return _resolve_hierarchical_preprocessing(
             PreprocessingConfig(
                 backend="auto",
-                requested_spacing_um=requested_spacing_um,
-                requested_tile_size_px=requested_tile_size_px,
+                requested_spacing_um=default_spacing_um,
+                requested_tile_size_px=default_tile_size_px,
             )
         )
 
     requested_spacing_um = preprocessing.requested_spacing_um
     requested_tile_size_px = preprocessing.requested_tile_size_px
     if requested_spacing_um is None or requested_tile_size_px is None:
-        default_tile_size_px, default_spacing_um = ensure_defaults()
-        if requested_spacing_um is None:
-            requested_spacing_um = default_spacing_um
-        if requested_tile_size_px is None:
-            requested_tile_size_px = default_tile_size_px
+        resolved_fields = _resolve_registered_preprocessing_fields(
+            name,
+            requested_spacing_um=requested_spacing_um,
+            requested_tile_size_px=requested_tile_size_px,
+        )
+        requested_spacing_um = float(resolved_fields["spacing_um"])
+        requested_tile_size_px = int(resolved_fields["tile_size_px"])
     return _resolve_hierarchical_preprocessing(
         replace(
             preprocessing,
@@ -1199,14 +1294,30 @@ def _resolve_direct_api_preprocessing(
 
 
 def _default_preprocessing_from_registry(name: str | None) -> tuple[int, float]:
+    resolved_fields = _resolve_registered_preprocessing_fields(
+        name,
+        requested_spacing_um=None,
+        requested_tile_size_px=None,
+    )
+    return int(resolved_fields["tile_size_px"]), float(resolved_fields["spacing_um"])
+
+
+def _resolve_registered_preprocessing_fields(
+    name: str | None,
+    *,
+    requested_spacing_um: float | None,
+    requested_tile_size_px: int | None,
+) -> dict[str, Any]:
     if not name or name not in encoder_registry:
         raise ValueError(
             "Cannot infer preprocessing defaults without a registered model. "
             "Pass preprocessing.requested_spacing_um and preprocessing.requested_tile_size_px explicitly."
         )
-
-    defaults = resolve_preprocessing_defaults(name)
-    return int(defaults["tile_size_px"]), float(defaults["spacing_um"])
+    return resolve_preprocessing_fields(
+        name,
+        requested_spacing_um=requested_spacing_um,
+        requested_tile_size_px=requested_tile_size_px,
+    )
 
 
 def _validate_model_config(

{slide2vec-5.5.0 → slide2vec-5.6.0}/slide2vec/artifacts.py

@@ -7,7 +7,6 @@ from uuid import uuid4
 
 import numpy as np
 import torch
-from hs2p.fileops import is_flattened_annotation
 
 from slide2vec.runtime.model_settings import output_torch_dtype
 
@@ -20,6 +19,7 @@ class TileEmbeddingArtifact:
     format: str
     feature_dim: int
     num_tiles: int
+    annotation: str | None = None
 
     @property
     def metadata(self) -> dict[str, Any]:
@@ -208,15 +208,32 @@ def _write_metadata(path: Path, metadata: dict[str, Any]) -> None:
     )
 
 
+def normalize_artifact_annotation(annotation: str | None) -> str | None:
+    """Return the annotation component used for slide2vec artifact placement.
+
+    ``"merged"`` is a process-list sentinel, not an hs2p 4.4 artifact annotation:
+    structural merged output is ``annotation=None`` plus ``output_mode="merged"``.
+    Accepting the sentinel here keeps 4.3 process lists reusable without delegating
+    process identity to hs2p's artifact-annotation helper.
+    """
+    if annotation in (None, "tissue", "merged"):
+        return None
+    return str(annotation)
+
+
+def structural_artifact_annotation(annotation: str | None) -> str | None:
+    """Translate only the structural merged process sentinel to artifact identity."""
+    return None if annotation == "merged" else annotation
+
+
 def tile_embeddings_subdir(annotation: str | None) -> str:
     """Namespace the ``tile_embeddings`` output dir per annotation class.
 
-    Reuses hs2p's flatten rule (the single source of truth): ``None`` and the sentinel
-    ``"tissue"`` collapse to the flat ``tile_embeddings`` root, so the default tissue-only
-    path is byte-for-byte unchanged; any real class label gets its own
-    ``tile_embeddings/<class>`` subdirectory.
+    Structural ``None`` and the process sentinels ``"tissue"``/``"merged"`` collapse to
+    the flat root; a genuine class gets ``tile_embeddings/<class>``.
     """
-    if is_flattened_annotation(annotation):
+    annotation = normalize_artifact_annotation(annotation)
+    if annotation is None:
         return "tile_embeddings"
     return f"tile_embeddings/{annotation}"
 
@@ -224,19 +241,18 @@ def tile_embeddings_subdir(annotation: str | None) -> str:
 def slide_embeddings_subdir(annotation: str | None) -> str:
     """Namespace the ``slide_embeddings`` output dir per annotation class.
 
-    Reuses hs2p's flatten rule (the single source of truth, shared with
-    :func:`tile_embeddings_subdir`): ``None`` and the sentinel ``"tissue"`` collapse to the
-    flat ``slide_embeddings`` root, so the default tissue-only path is byte-for-byte
-    unchanged; any real class label gets its own ``slide_embeddings/<class>`` subdirectory.
+    Uses the same structural/process identity rule as :func:`tile_embeddings_subdir`.
     """
-    if is_flattened_annotation(annotation):
+    annotation = normalize_artifact_annotation(annotation)
+    if annotation is None:
         return "slide_embeddings"
     return f"slide_embeddings/{annotation}"
 
 
 def slide_latents_subdir(annotation: str | None) -> str:
     """Namespace the ``slide_latents`` output dir per annotation class (mirrors slide embeddings)."""
-    if is_flattened_annotation(annotation):
+    annotation = normalize_artifact_annotation(annotation)
+    if annotation is None:
         return "slide_latents"
     return f"slide_latents/{annotation}"
 
@@ -244,13 +260,10 @@ def slide_latents_subdir(annotation: str | None) -> str:
 def hierarchical_embeddings_subdir(annotation: str | None) -> str:
     """Namespace the ``hierarchical_embeddings`` output dir per annotation class.
 
-    Reuses hs2p's flatten rule (the single source of truth, shared with
-    :func:`tile_embeddings_subdir` and :func:`slide_embeddings_subdir`): ``None`` and the
-    sentinel ``"tissue"`` collapse to the flat ``hierarchical_embeddings`` root, so the
-    default tissue-only path is byte-for-byte unchanged; any real class label gets its own
-    ``hierarchical_embeddings/<class>`` subdirectory.
+    Uses the same structural/process identity rule as :func:`tile_embeddings_subdir`.
     """
-    if is_flattened_annotation(annotation):
+    annotation = normalize_artifact_annotation(annotation)
+    if annotation is None:
         return "hierarchical_embeddings"
     return f"hierarchical_embeddings/{annotation}"
 
@@ -272,12 +285,10 @@ def _validate_path_component(value: str, *, field: str) -> str:
 def dense_embeddings_subdir(annotation: str | None) -> str:
     """Namespace the ``dense_embeddings`` output dir per annotation class.
 
-    Reuses hs2p's flatten rule (the single source of truth, shared with
-    :func:`tile_embeddings_subdir` and the other pooled subdir helpers): ``None`` and the
-    sentinel ``"tissue"`` collapse to the flat ``dense_embeddings`` root; any real class
-    label gets its own ``dense_embeddings/<class>`` subdirectory.
+    Uses the same structural/process identity rule as :func:`tile_embeddings_subdir`.
     """
-    if is_flattened_annotation(annotation):
+    annotation = normalize_artifact_annotation(annotation)
+    if annotation is None:
         return "dense_embeddings"
     annotation_component = _validate_path_component(annotation, field="annotation")
     return f"dense_embeddings/{annotation_component}"
@@ -329,6 +340,7 @@ def write_dense_region(
 ) -> DenseRegionArtifact:
     """Persist one ROI's ``(d, gh, gw)`` grid + its geometry sidecar (see
     :func:`_write_dense_grid` for the write order this shares with every dense artifact)."""
+    annotation = structural_artifact_annotation(annotation)
     payload_path, metadata_path = region_dense_paths(
         output_dir, sample_id=sample_id, annotation=annotation, x=x, y=y
     )
@@ -353,7 +365,8 @@ def dense_image_paths(output_dir: str | Path, *, sample_id: str) -> tuple[Path,
     ``dense_image_embeddings/<sample_id>.pt`` plus ``<sample_id>.meta.json``. Flat, like the
     pooled image layout and unlike the per-slide dense one: a pre-cropped image has no slide
     directory to live under and no ``(x, y)`` to be named by, so the caller's ``sample_id``
-    is the whole identity and the resume check needs nothing else.
+    determines the paths. Resume additionally validates the payload and the complete
+    compatibility record in the sidecar.
     """
     output_root = Path(output_dir).expanduser().resolve()
     sample_component = _validate_path_component(sample_id, field="sample_id")
@@ -463,6 +476,7 @@ def _build_tile_embedding_metadata(
     output_format: str,
     feature_dim: int | None,
     num_tiles: int,
+    annotation: str | None,
     metadata: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     tile_metadata = {
@@ -474,6 +488,7 @@ def _build_tile_embedding_metadata(
     }
     if metadata:
         tile_metadata.update(metadata)
+    tile_metadata["annotation"] = normalize_artifact_annotation(annotation)
     return tile_metadata
 
 
@@ -521,6 +536,7 @@ def write_tile_embeddings(
         output_format=output_format,
         feature_dim=int(feature_array.shape[-1]) if feature_array.ndim else 1,
         num_tiles=int(feature_array.shape[0]) if feature_array.ndim else 1,
+        annotation=annotation,
         metadata=metadata,
     )
     _write_metadata(metadata_path, tile_metadata)
@@ -531,6 +547,7 @@ def write_tile_embeddings(
         format=output_format,
         feature_dim=tile_metadata["feature_dim"],
         num_tiles=tile_metadata["num_tiles"],
+        annotation=tile_metadata["annotation"],
     )
 
 
@@ -553,6 +570,7 @@ def write_tile_embedding_metadata(
         output_format=output_format,
         feature_dim=feature_dim,
         num_tiles=num_tiles,
+        annotation=annotation,
         metadata=metadata,
     )
     _write_metadata(metadata_path, tile_metadata)
@@ -570,6 +588,7 @@ def write_slide_embeddings(
     annotation: str | None = None,
 ) -> SlideEmbeddingArtifact:
     output_format = _validate_output_format(output_format)
+    annotation = structural_artifact_annotation(annotation)
     artifact_path, metadata_path = _setup_artifact_paths(
         output_dir, slide_embeddings_subdir(annotation), sample_id, output_format
     )
@@ -657,6 +676,7 @@ def write_hierarchical_embeddings(
     annotation: str | None = None,
 ) -> HierarchicalEmbeddingArtifact:
     output_format = _validate_output_format(output_format)
+    annotation = structural_artifact_annotation(annotation)
     artifact_path, metadata_path = _setup_artifact_paths(
         output_dir, hierarchical_embeddings_subdir(annotation), sample_id, output_format
     )