apb-catalog 0.1.0__tar.gz

apb_catalog-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Witold Wolski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

apb_catalog-0.1.0/PKG-INFO

@@ -0,0 +1,79 @@
+Metadata-Version: 2.4
+Name: apb-catalog
+Version: 0.1.0
+Summary: Semantic source catalogues and column resolution for APB results
+Keywords: proteomics,anndata,metadata,catalogue,mass spectrometry
+Author: Witold Wolski
+Author-email: Witold Wolski <wew@fgcz.ethz.ch>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Typing :: Typed
+Requires-Dist: apb2>=0.1,<0.2
+Requires-Dist: polars>=1.43,<2
+Requires-Dist: pydantic>=2.10
+Requires-Python: >=3.13
+Project-URL: Documentation, https://anndata-omics-bridge.github.io/apb-catalog/
+Project-URL: Repository, https://github.com/anndata-omics-bridge/apb-catalog
+Description-Content-Type: text/markdown
+
+# APB Catalog
+
+Catalogues of what APB result fields mean, one set per kind of meaning, each stating its purpose and users, so the consumer asks for a meaning instead of vendor columns such as `PEP`, `EG_PEP` or `Q_Value`.
+
+Documentation: [anndata-omics-bridge.github.io/apb-catalog](https://anndata-omics-bridge.github.io/apb-catalog/), built from [docs/](https://github.com/anndata-omics-bridge/apb-catalog/tree/main/docs) with `make docs`; start with [Get started](https://anndata-omics-bridge.github.io/apb-catalog/getting-started/).
+
+## Installation
+
+```bash
+pip install apb-catalog
+```
+
+## Use
+
+```python
+from apb_catalog.api import Catalog
+
+confidence = Catalog(parsed, "identification_confidence")                     # parsed: apb2 ParsedLevels
+confidence.layer("ion", concept="confidence")                 # ('pep', 'q_value') — kinds on offer, or None
+pep = confidence.layer("ion", concept="confidence", kind="pep")  # MaxQuant PEP, Spectronaut EG_PEP, DIA-NN PEP
+
+miape = Catalog(parsed, "miape")
+miape.var("protein", concept="miape")                        # ('gene_name', 'protein_group')
+genes = miape.var("protein", concept="miape", kind="gene_name")  # the column MIAPE-AnnData calls gene_name
+```
+
+- [Every entry](https://anndata-omics-bridge.github.io/apb-catalog/catalogues/) of both sets
+- `layer` returns the apb2 layer table, `var` the column; `None` means the vendor has no such field
+- A level answers only for its own entity: ion for precursors, protein for protein groups
+- Confidence lookups mean identification unless `stage="quantification"` says otherwise
+- Two equally good fields, or a rule nobody reviewed, raise `UnresolvedField` naming the candidates
+- `attach_snapshot(parsed, catalog.snapshot())` records bindings and lookups in `metadata["catalog"][<catalogue>]`
+
+## Catalogues
+
+- `identification_confidence`: how likely each identification is correct: per-run PEP and q-value layers, per-feature PEP and Sage's MS1-peak q-value; used by apb-aggregate's confidence-weighted rollups; 12 entries
+- `miape`: draft mapping onto the MIAPE-AnnData Schema 0.4.0 draft (HUPO-PSI AI Readiness Working Group): protein, peptide and peptidoform fields and the `raw` layer; ion levels have no MIAPE modality; 32 entries
+- `Catalog(parsed, name).description`: the set's purpose and users, also embedded in its snapshot
+- Each set lists every packaged APB2 rule level, so a vendor without a relevant field answers `missing`, never `unknown`
+- Entries bind to reviewed effective-rule fingerprints (SHA-256 of canonical `rule_json`); any APB2 rule change needs re-review, enforced by the drift tests
+- Vocabulary: `confidence` with `kind` (pep, q_value) and `stage`; `miape` with `kind` naming the MIAPE-AnnData field and its requirement level
+
+## Snapshot contract
+
+`attach_snapshot` stores `apb-catalog-resolution` 0.2 as JSON at `ParsedLevels.metadata["catalog"][<catalogue>]`; APB2 persists it in every format, including AnnData `uns` from HDF5 result format 5. It embeds the set's description, concept definitions, level bindings, retained entries and every answer, so readers need neither this package nor its catalogues. The [JSON Schema](https://github.com/anndata-omics-bridge/apb-catalog/blob/main/src/apb_catalog/data/apb-catalog-resolution-0.2.schema.json) is published with the package; `make schema` regenerates it.
+
+## Development
+
+```bash
+uv sync --group dev
+make check
+.venv/bin/pre-commit install --hook-type pre-commit --hook-type pre-push
+```
+
+All Python commands run from the synchronized project `.venv`.

apb_catalog-0.1.0/README.md

@@ -0,0 +1,55 @@
+# APB Catalog
+
+Catalogues of what APB result fields mean, one set per kind of meaning, each stating its purpose and users, so the consumer asks for a meaning instead of vendor columns such as `PEP`, `EG_PEP` or `Q_Value`.
+
+Documentation: [anndata-omics-bridge.github.io/apb-catalog](https://anndata-omics-bridge.github.io/apb-catalog/), built from [docs/](https://github.com/anndata-omics-bridge/apb-catalog/tree/main/docs) with `make docs`; start with [Get started](https://anndata-omics-bridge.github.io/apb-catalog/getting-started/).
+
+## Installation
+
+```bash
+pip install apb-catalog
+```
+
+## Use
+
+```python
+from apb_catalog.api import Catalog
+
+confidence = Catalog(parsed, "identification_confidence")                     # parsed: apb2 ParsedLevels
+confidence.layer("ion", concept="confidence")                 # ('pep', 'q_value') — kinds on offer, or None
+pep = confidence.layer("ion", concept="confidence", kind="pep")  # MaxQuant PEP, Spectronaut EG_PEP, DIA-NN PEP
+
+miape = Catalog(parsed, "miape")
+miape.var("protein", concept="miape")                        # ('gene_name', 'protein_group')
+genes = miape.var("protein", concept="miape", kind="gene_name")  # the column MIAPE-AnnData calls gene_name
+```
+
+- [Every entry](https://anndata-omics-bridge.github.io/apb-catalog/catalogues/) of both sets
+- `layer` returns the apb2 layer table, `var` the column; `None` means the vendor has no such field
+- A level answers only for its own entity: ion for precursors, protein for protein groups
+- Confidence lookups mean identification unless `stage="quantification"` says otherwise
+- Two equally good fields, or a rule nobody reviewed, raise `UnresolvedField` naming the candidates
+- `attach_snapshot(parsed, catalog.snapshot())` records bindings and lookups in `metadata["catalog"][<catalogue>]`
+
+## Catalogues
+
+- `identification_confidence`: how likely each identification is correct: per-run PEP and q-value layers, per-feature PEP and Sage's MS1-peak q-value; used by apb-aggregate's confidence-weighted rollups; 12 entries
+- `miape`: draft mapping onto the MIAPE-AnnData Schema 0.4.0 draft (HUPO-PSI AI Readiness Working Group): protein, peptide and peptidoform fields and the `raw` layer; ion levels have no MIAPE modality; 32 entries
+- `Catalog(parsed, name).description`: the set's purpose and users, also embedded in its snapshot
+- Each set lists every packaged APB2 rule level, so a vendor without a relevant field answers `missing`, never `unknown`
+- Entries bind to reviewed effective-rule fingerprints (SHA-256 of canonical `rule_json`); any APB2 rule change needs re-review, enforced by the drift tests
+- Vocabulary: `confidence` with `kind` (pep, q_value) and `stage`; `miape` with `kind` naming the MIAPE-AnnData field and its requirement level
+
+## Snapshot contract
+
+`attach_snapshot` stores `apb-catalog-resolution` 0.2 as JSON at `ParsedLevels.metadata["catalog"][<catalogue>]`; APB2 persists it in every format, including AnnData `uns` from HDF5 result format 5. It embeds the set's description, concept definitions, level bindings, retained entries and every answer, so readers need neither this package nor its catalogues. The [JSON Schema](https://github.com/anndata-omics-bridge/apb-catalog/blob/main/src/apb_catalog/data/apb-catalog-resolution-0.2.schema.json) is published with the package; `make schema` regenerates it.
+
+## Development
+
+```bash
+uv sync --group dev
+make check
+.venv/bin/pre-commit install --hook-type pre-commit --hook-type pre-push
+```
+
+All Python commands run from the synchronized project `.venv`.

apb_catalog-0.1.0/pyproject.toml

@@ -0,0 +1,129 @@
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "apb-catalog"
+version = "0.1.0"
+description = "Semantic source catalogues and column resolution for APB results"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "proteomics",
+    "anndata",
+    "metadata",
+    "catalogue",
+    "mass spectrometry",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+dependencies = [
+    "apb2>=0.1,<0.2",
+    "polars>=1.43,<2",
+    "pydantic>=2.10",
+]
+
+[[project.authors]]
+name = "Witold Wolski"
+email = "wew@fgcz.ethz.ch"
+
+[project.urls]
+Documentation = "https://anndata-omics-bridge.github.io/apb-catalog/"
+Repository = "https://github.com/anndata-omics-bridge/apb-catalog"
+
+[tool.uv.sources.apb2]
+path = "../apb2"
+editable = true
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = [
+    "ANN",
+    "B",
+    "C4",
+    "C90",
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "I",
+    "PGH",
+    "PIE",
+    "RUF",
+    "SIM",
+    "UP",
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.pyright]
+include = [
+    "src",
+    "tests",
+]
+venvPath = "."
+venv = ".venv"
+pythonVersion = "3.13"
+typeCheckingMode = "strict"
+reportImportCycles = "error"
+reportMissingTypeStubs = "error"
+reportUnnecessaryTypeIgnoreComment = "error"
+reportImplicitOverride = "error"
+enableTypeIgnoreComments = false
+
+[tool.pytest.ini_options]
+addopts = [
+    "--strict-config",
+    "--strict-markers",
+    "-ra",
+]
+testpaths = ["tests"]
+xfail_strict = true
+
+[tool.coverage.run]
+branch = true
+source = ["apb_catalog"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+skip_covered = true
+
+[tool.deptry]
+known_first_party = ["apb_catalog"]
+
+[dependency-groups]
+dev = [
+    "build>=1.3,<2",
+    "deptry>=0.24,<1",
+    "pre-commit>=4,<5",
+    "pyright>=1.1.400,<2",
+    "pytest>=9,<10",
+    "pytest-cov>=7,<8",
+    "ruff>=0.15,<1",
+    "twine>=6,<7",
+]
+docs = [
+    "pymdown-extensions>=11,<12",
+    "zensical==0.0.43",
+]

apb_catalog-0.1.0/pyproject.toml.orig

@@ -0,0 +1,111 @@
+[build-system]
+requires = ["uv_build>=0.9.26,<0.10.0"]
+build-backend = "uv_build"
+
+[project]
+name = "apb-catalog"
+version = "0.1.0"
+description = "Semantic source catalogues and column resolution for APB results"
+readme = "README.md"
+requires-python = ">=3.13"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Witold Wolski", email = "wew@fgcz.ethz.ch" },
+]
+keywords = ["proteomics", "anndata", "metadata", "catalogue", "mass spectrometry"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+    "Typing :: Typed",
+]
+dependencies = [
+    "apb2>=0.1,<0.2",
+    "polars>=1.43,<2",
+    "pydantic>=2.10",
+]
+
+[project.urls]
+Documentation = "https://anndata-omics-bridge.github.io/apb-catalog/"
+Repository = "https://github.com/anndata-omics-bridge/apb-catalog"
+
+[tool.uv.sources]
+apb2 = { path = "../apb2", editable = true }
+
+[dependency-groups]
+dev = [
+    "build>=1.3,<2",
+    "deptry>=0.24,<1",
+    "pre-commit>=4,<5",
+    "pyright>=1.1.400,<2",
+    "pytest>=9,<10",
+    "pytest-cov>=7,<8",
+    "ruff>=0.15,<1",
+    "twine>=6,<7",
+]
+docs = [
+    "pymdown-extensions>=11,<12",
+    "zensical==0.0.43",
+]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "ANN",
+    "B",
+    "C4",
+    "C90",
+    "E4",
+    "E7",
+    "E9",
+    "F",
+    "I",
+    "PGH",
+    "PIE",
+    "RUF",
+    "SIM",
+    "UP",
+]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.ruff.format]
+docstring-code-format = true
+
+[tool.pyright]
+include = ["src", "tests"]
+venvPath = "."
+venv = ".venv"
+pythonVersion = "3.13"
+typeCheckingMode = "strict"
+reportImportCycles = "error"
+reportMissingTypeStubs = "error"
+reportUnnecessaryTypeIgnoreComment = "error"
+reportImplicitOverride = "error"
+enableTypeIgnoreComments = false
+
+[tool.pytest.ini_options]
+addopts = ["--strict-config", "--strict-markers", "-ra"]
+testpaths = ["tests"]
+xfail_strict = true
+
+[tool.coverage.run]
+branch = true
+source = ["apb_catalog"]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+skip_covered = true
+
+[tool.deptry]
+known_first_party = ["apb_catalog"]

apb_catalog-0.1.0/src/apb_catalog/__init__.py

@@ -0,0 +1 @@
+

apb_catalog-0.1.0/src/apb_catalog/api.py

@@ -0,0 +1,16 @@
+"""The one public APB Catalog module: semantic lookups and their stored snapshots."""
+
+from __future__ import annotations
+
+from apb_catalog.catalog import Catalog, attach_snapshot, stale_levels, stored_snapshot
+from apb_catalog.resolver import UnresolvedField
+from apb_catalog.snapshot import ResolutionSnapshot
+
+__all__ = [
+    "Catalog",
+    "ResolutionSnapshot",
+    "UnresolvedField",
+    "attach_snapshot",
+    "stale_levels",
+    "stored_snapshot",
+]

apb_catalog-0.1.0/src/apb_catalog/catalog.py

@@ -0,0 +1,234 @@
+"""Look up an APB result's fields by meaning, so callers never name vendor columns."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import replace
+from typing import overload
+
+import polars as pl
+from apb2.api import FinalLayerTable, ParsedLevel, ParsedLevels
+
+from apb_catalog.fingerprint import fingerprint
+from apb_catalog.resolver import (
+    AbsentLevel,
+    ConceptRequest,
+    Resolution,
+    ReviewedLevel,
+    UnreviewedLevel,
+)
+from apb_catalog.snapshot import ResolutionSnapshot, this_producer
+from apb_catalog.source import (
+    CatalogueDescription,
+    Location,
+    Reference,
+    SourceCatalogues,
+    packaged_catalogues,
+)
+
+METADATA_KEY = "catalog"
+_DEFAULTS = {"stage": "identification"}
+
+
+class Catalog:
+    """What one APB result's fields mean to one consumer, with the data handed back directly.
+
+    ``Catalog(parsed, "identification_confidence").layer("ion", concept="confidence", kind="pep")`` returns
+    MaxQuant's ``PEP`` or Spectronaut's ``EG_PEP`` layer, or ``None`` when the vendor reports no
+    PEP; ``Catalog(parsed, "miape").var("protein", concept="miape", kind="gene_name")`` returns the
+    column MIAPE-AnnData calls ``gene_name``. Leaving out ``kind`` lists the kinds the level holds.
+    A level answers only for its own entity. Confidence lookups mean identification unless
+    ``stage="quantification"`` says otherwise. Ambiguous or unreviewed answers raise
+    :class:`~apb_catalog.resolver.UnresolvedField` naming the candidates.
+    """
+
+    __slots__ = ("_catalogues", "_name", "_parsed", "_resolutions", "_views")
+
+    def __init__(self, parsed: ParsedLevels, catalogue: str) -> None:
+        self._parsed = parsed
+        self._name = catalogue
+        self._catalogues = packaged_catalogues(catalogue)
+        self._views: dict[str, ReviewedLevel | UnreviewedLevel] = {
+            name: level_view(name, level, self._catalogues) for name, level in parsed.levels.items()
+        }
+        self._resolutions: list[Resolution] = []
+
+    @property
+    def description(self) -> CatalogueDescription:
+        """What this catalogue set holds and who uses it."""
+        return self._catalogues.description
+
+    @overload
+    def layer(
+        self, level: str, concept: str, kind: str, **qualifiers: str
+    ) -> FinalLayerTable | None: ...
+
+    @overload
+    def layer(
+        self, level: str, concept: str, kind: None = None, **qualifiers: str
+    ) -> tuple[str, ...] | None: ...
+
+    def layer(
+        self, level: str, concept: str, kind: str | None = None, **qualifiers: str
+    ) -> FinalLayerTable | tuple[str, ...] | None:
+        """Return the sample-by-feature layer with this meaning, or the kinds on offer."""
+        if kind is None:
+            return self._kinds(level, "layers", concept, qualifiers)
+        reference = self._find(level, "layers", concept, qualifiers | {"kind": kind})
+        return None if reference is None else self._parsed.levels[level].layers[reference.name]
+
+    @overload
+    def var(self, level: str, concept: str, kind: str, **qualifiers: str) -> pl.Series | None: ...
+
+    @overload
+    def var(
+        self, level: str, concept: str, kind: None = None, **qualifiers: str
+    ) -> tuple[str, ...] | None: ...
+
+    def var(
+        self, level: str, concept: str, kind: str | None = None, **qualifiers: str
+    ) -> pl.Series | tuple[str, ...] | None:
+        """Return the per-feature column with this meaning, or the kinds on offer."""
+        if kind is None:
+            return self._kinds(level, "var", concept, qualifiers)
+        reference = self._find(level, "var", concept, qualifiers | {"kind": kind})
+        return None if reference is None else self._parsed.levels[level].var.frame[reference.name]
+
+    def fields(self) -> pl.DataFrame:
+        """List every catalogued field the result retains, one row per field."""
+        return pl.DataFrame(
+            [
+                {
+                    "level": entry.reference.level,
+                    "location": entry.reference.location,
+                    "name": entry.reference.name,
+                    "concept": entry.concept,
+                    **entry.qualifiers,
+                }
+                for view in self._views.values()
+                for entry in view.entries
+            ]
+        )
+
+    def resolve(self, request: ConceptRequest) -> Resolution:
+        """Answer one explicit request and record it for the snapshot."""
+        resolution = self._answer(request)
+        self._resolutions.append(resolution)
+        return resolution
+
+    def snapshot(self) -> ResolutionSnapshot:
+        """Return a self-contained record of the bindings, fields and every lookup so far."""
+        entries = tuple(entry for view in self._views.values() for entry in view.entries)
+        concepts = {entry.concept for entry in entries}
+        concepts |= {resolution.request.concept for resolution in self._resolutions}
+        vocabulary = self._catalogues.vocabulary
+        return ResolutionSnapshot(
+            producer=this_producer(),
+            catalogue=self._name,
+            description=self._catalogues.description,
+            vocabulary_version=vocabulary.vocabulary_version,
+            concepts={name: vocabulary.concept(name) for name in sorted(concepts)},
+            levels=tuple(view.binding() for view in self._views.values()),
+            entries=entries,
+            resolutions=tuple(self._resolutions),
+        )
+
+    def _find(
+        self,
+        level: str,
+        location: Location,
+        concept: str,
+        qualifiers: dict[str, str],
+    ) -> Reference | None:
+        return self.resolve(self._request(level, location, concept, qualifiers)).found()
+
+    def _kinds(
+        self,
+        level: str,
+        location: Location,
+        concept: str,
+        qualifiers: dict[str, str],
+    ) -> tuple[str, ...] | None:
+        offered = self._answer(self._request(level, location, concept, qualifiers)).offered("kind")
+        return offered or None
+
+    def _request(
+        self,
+        level: str,
+        location: Location,
+        concept: str,
+        qualifiers: dict[str, str],
+    ) -> ConceptRequest:
+        declared = self._catalogues.vocabulary.concept(concept).qualifiers
+        described = {name: value for name, value in _DEFAULTS.items() if name in declared}
+        described |= qualifiers
+        return ConceptRequest(
+            concept=concept,
+            level=level,
+            location=location,
+            qualifiers={name: (value,) for name, value in described.items()},
+        )
+
+    def _answer(self, request: ConceptRequest) -> Resolution:
+        self._catalogues.vocabulary.concept(request.concept).check_predicate(request.qualifiers)
+        return self._views.get(request.level, AbsentLevel(request.level)).resolve(request)
+
+
+def rule_fingerprint(level: ParsedLevel, /) -> str | None:
+    """Return the fingerprint of a level's stored effective rule, if it records one."""
+    rule_json = level.uns.get("rule_json")
+    if not isinstance(rule_json, str):
+        return None
+    return fingerprint(json.loads(rule_json))
+
+
+def level_view(
+    name: str, level: ParsedLevel, catalogues: SourceCatalogues, /
+) -> ReviewedLevel | UnreviewedLevel:
+    """Bind one level to its reviewed rule, keeping only entries whose fields it retains."""
+    level_fingerprint = rule_fingerprint(level)
+    if level_fingerprint is None:
+        return UnreviewedLevel(name, None, "the level records no rule_json provenance")
+    reviewed = catalogues.reviewed(level_fingerprint)
+    if reviewed is None:
+        return UnreviewedLevel(
+            name, level_fingerprint, "no source catalogue reviewed this effective rule"
+        )
+    retained = {("layers", layer) for layer in level.layers}
+    retained |= {("var", column) for column in level.var.frame.columns}
+    entries = tuple(
+        entry
+        for entry in reviewed.entries()
+        if (entry.reference.location, entry.reference.name) in retained
+    )
+    return ReviewedLevel(name, level_fingerprint, reviewed, entries)
+
+
+def attach_snapshot(parsed: ParsedLevels, snapshot: ResolutionSnapshot) -> ParsedLevels:
+    """Return a new result carrying the snapshot beside other catalogues' snapshots.
+
+    Scientific data is shared, not copied.
+    """
+    namespace = parsed.metadata.get(METADATA_KEY)
+    snapshots = dict(namespace) if isinstance(namespace, dict) else {}
+    snapshots[snapshot.catalogue] = snapshot.model_dump(mode="json")
+    return replace(parsed, metadata={**parsed.metadata, METADATA_KEY: snapshots})
+
+
+def stored_snapshot(parsed: ParsedLevels, catalogue: str) -> ResolutionSnapshot | None:
+    """Return the snapshot one catalogue set left on a result, if any."""
+    namespace = parsed.metadata.get(METADATA_KEY)
+    stored = namespace.get(catalogue) if isinstance(namespace, dict) else None
+    if stored is None:
+        return None
+    return ResolutionSnapshot.model_validate(stored)
+
+
+def stale_levels(parsed: ParsedLevels, snapshot: ResolutionSnapshot) -> tuple[str, ...]:
+    """Return the snapshot's levels whose current effective rule differs from the recorded one."""
+    return tuple(
+        binding.level
+        for binding in snapshot.levels
+        if binding.level not in parsed.levels
+        or rule_fingerprint(parsed.levels[binding.level]) != binding.fingerprint
+    )