s3dgraphy 1.6.0.dev33__tar.gz → 1.6.0.dev34__tar.gz

{s3dgraphy-1.6.0.dev33/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev34}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev33
+Version: 1.6.0.dev34
 Summary: 3D Stratigraphic Graph Management Library for archaeological and heritage applications
 Author-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
 Maintainer-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>

{s3dgraphy-1.6.0.dev33 → s3dgraphy-1.6.0.dev34}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "s3dgraphy"
-version = "1.6.0.dev33"
+version = "1.6.0.dev34"
 description = "3D Stratigraphic Graph Management Library for archaeological and heritage applications"
 readme = "README.md"
 requires-python = ">=3.9"

{s3dgraphy-1.6.0.dev33 → s3dgraphy-1.6.0.dev34}/src/s3dgraphy/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "1.6.0.dev33"
+__version__ = "1.6.0.dev34"
 __datamodel_version__ = "1.5.5"  # s3Dgraphy connections datamodel version
 
 # s3Dgraphy/__init__.py

{s3dgraphy-1.6.0.dev33 → s3dgraphy-1.6.0.dev34}/src/s3dgraphy/api.py

@@ -2704,6 +2704,45 @@ def pick_representation(graph: Graph, res_id: str, can_open) -> Dict[str, Any]:
     return _pick(graph, res_id, can_open)
 
 
+# ── an asset and its versions (E.D. 30 Sep / 3 Oct 2026) ──────────────────────
+# The asset is the master resource; each version (LOD1, LOD2…) is a child made
+# by a `lod_generation` step, with its level and purpose in the step's
+# parameters. The semantic link stays on the asset and the versions inherit it.
+# See :mod:`s3dgraphy.resources.versions`.
+def add_version(graph: Graph, master_id: str, *, level: str, purpose: str = "",
+                **kwargs) -> Dict[str, Any]:
+    """A version of the asset ``master_id`` at ``level`` for ``purpose``: a child
+    resource ``dtc_derived_from`` the master through a ``lod_generation`` step.
+    Idempotent per (asset, level); other bytes at a level are refused (revise
+    the version instead). Returns ``{version_id, process_id, created, asset_id,
+    level, purpose, warnings}``."""
+    from .resources.versions import add_version as _add
+    before = _ids(graph)
+    out = _add(graph, master_id, level=level, purpose=purpose, **kwargs)
+    _born(graph, before)
+    return out
+
+
+def versions_of(graph: Graph, res_id: str) -> List[Dict[str, Any]]:
+    """The asset of ``res_id`` and its versions, master first then by level,
+    each the CURRENT revision: ``[{id, level, purpose, master, checksum, …}]``."""
+    from .resources.versions import versions_of as _versions
+    return _versions(graph, res_id)
+
+
+def asset_of(graph: Graph, res_id: str) -> str:
+    """The asset (master) ``res_id`` is a version of; itself if it is none."""
+    from .resources.versions import asset_of as _asset
+    return _asset(graph, res_id)
+
+
+def inherited_links(graph: Graph, res_id: str) -> Dict[str, Any]:
+    """What hats the asset of ``res_id`` (RM/proxy facets and their epochs and
+    units): the semantic link a version inherits, never copied onto it."""
+    from .resources.versions import inherited_links as _links
+    return _links(graph, res_id)
+
+
 # ── the 3D Tiles Archive (.3tz), recognised and read, never written here ──────
 # The writers are 3DSC and EMStudio (E.D. 2026-09-30); the canonical form and
 # the content digest belong to dtcstamp. See :mod:`s3dgraphy.resources.tiles3tz`.

{s3dgraphy-1.6.0.dev33 → s3dgraphy-1.6.0.dev34}/src/s3dgraphy/geometry/store_backed.py

@@ -206,6 +206,17 @@ def _binds(graph: Any, node_id: str, by_id: Dict[str, Any]) -> List[Dict[str, st
     return out
 
 
+def _version_of(graph: Any, res_id: str) -> Optional[Dict[str, Any]]:
+    """The version entry of this resource, or None (also for a graph whose
+    shape the versions reader cannot walk: listing geometry must not fail on
+    that)."""
+    try:
+        from ..resources.versions import version_info
+        return version_info(graph, res_id)
+    except Exception:      # noqa: BLE001 — a fork in the revisions is not ours here
+        return None
+
+
 def store_backed_geometry(graph: Any) -> List[Dict[str, Any]]:
     """The geometry this graph describes that lives in the store, as records.
 
@@ -226,6 +237,9 @@ def store_backed_geometry(graph: Any) -> List[Dict[str, Any]]:
     ``bind``       ``[{id, node_type, name, via}]`` — epochs, units, documents
     ``residency``  always ``resident`` in this list (see the module docstring)
     ``name`` / ``media_type`` / ``url`` — for the message a consumer shows
+    ``asset_id`` / ``level`` / ``purpose`` — only for an asset with versions
+                   and its versions (a version is listed under its asset's
+                   facets: it inherits them)
 
     Sorted by (kind, name, node_id): two runs read the same, which is what makes
     "materialise" idempotent from the caller's side as well.
@@ -246,10 +260,24 @@ def store_backed_geometry(graph: Any) -> List[Dict[str, Any]]:
             and str(getattr(by_id[str(getattr(e, "edge_source", ""))],
                             "node_type", "")) in _FACET_TYPES
         ]
+        #: a VERSION of an asset (LOD1, LOD2…) is hatted by nothing itself: it
+        #: inherits the facets of its asset (s3dgraphy.resources.versions), so
+        #: it is listed where the asset goes, with its level beside it
+        version = _version_of(graph, resource.node_id)
+        if not facets and version and version.get("asset_id") != resource.node_id:
+            facets = [by_id[str(e.edge_source)] for e in _alive_edges(graph)
+                      if str(getattr(e, "edge_type", "")) == EDGE_HAS_LINKED
+                      and str(getattr(e, "edge_target", "")) == version["asset_id"]
+                      and str(getattr(e, "edge_source", "")) in by_id
+                      and str(getattr(by_id[str(e.edge_source)], "node_type", ""))
+                      in _FACET_TYPES]
         carriers: List[Any] = facets or [resource]
         for carrier in carriers:
             node_type = str(getattr(carrier, "node_type", "") or "")
+            extra = ({"asset_id": version["asset_id"], "level": version["level"],
+                      "purpose": version["purpose"]} if version else {})
             records.append({
+                **extra,
                 "node_id": carrier.node_id,
                 "resource_id": resource.node_id,
                 "checksum": str(data.get("checksum") or ""),

s3dgraphy-1.6.0.dev34/src/s3dgraphy/resources/versions.py

@@ -0,0 +1,305 @@
+"""An asset and its versions — one survey object, several levels of detail.
+
+Decided by E.D. (30 Sep 2026, confirmed 3 Oct 2026, «asset padre con le versioni
+come risorse figlie»): the ASSET is the master resource (the podium as surveyed,
+LOD0), and each VERSION (LOD1, LOD2, a decimated or retopologised mesh) is a
+child ``ResourceNode`` made from it:
+
+* ``version ──dtc_derived_from──▶ master``, and a ``DTCProcessNode`` of kind
+  ``lod_generation`` with ``dtc_had_input`` the master and ``dtc_had_output`` the
+  version — the shape :func:`s3dgraphy.dtc.ingest.declare_derivation` writes;
+* the version's LEVEL and PURPOSE go in the process ``parameters`` (``level``,
+  ``purpose``), where the ``lod_generation`` kind of the visual rules says the
+  level goes; the master's own level, when somebody states it, is the
+  ``source_level`` of the same parameters — the level of the input as whoever
+  made the version saw it. No new field on the resource, so nothing new to map:
+  the parameters of a step already travel in em.json and in RDF;
+* the SEMANTIC LINK (the RM or proxy that hats the object, its epochs, its unit)
+  is declared ONCE, on the asset. A version inherits it: :func:`inherited_links`
+  reads it from the asset, and nothing is copied onto the version — a copy
+  would be a second statement that can disagree with the first.
+
+A version whose bytes change is REVISED like any resource (``replace_file``,
+``was_revision_of``): the revision keeps the level and purpose of the version it
+revises, and :func:`versions_of` answers with the CURRENT revision of each level.
+
+The level is a word somebody gives («LOD1»), not an enumeration fixed here: the
+earlier refusal of a ``lod0/1/2`` vocabulary (the measures of ``ResourceNode``)
+still holds for what a CONSUMER compares — weight and primitives — while the
+level is the name a person uses to pick one.
+"""
+
+from __future__ import annotations
+
+import re
+import uuid
+from typing import Any, Dict, List, Optional, Sequence
+
+from .files import (_data, _is_resource, _node, add_resource, resource_files,
+                    revisions_of)
+
+DTC_KIND = "lod_generation"
+EDGE_HAD_INPUT = "dtc_had_input"
+EDGE_HAD_OUTPUT = "dtc_had_output"
+EDGE_HAS_LINKED = "has_linked_resource"
+
+_NS = uuid.uuid5(uuid.NAMESPACE_URL, "https://extendedmatrix.org/s3dgraphy/asset-version")
+
+
+def version_id_for(asset_id: str, level: str) -> str:
+    """The id of the version of ``asset_id`` at ``level``: derived, so adding
+    the same level twice lands on the same node."""
+    return str(uuid.uuid5(_NS, f"version|{asset_id}|{_level(level)}"))
+
+
+def _level(level: Any) -> str:
+    text = str(level or "").strip()
+    if not text:
+        raise ValueError("a version needs a level (for instance «LOD1»)")
+    return text
+
+
+def _level_key(level: Optional[str]):
+    """Natural order: LOD2 before LOD10, a level without a number last."""
+    text = str(level or "")
+    m = re.search(r"(\d+)", text)
+    return (0 if m else 1, int(m.group(1)) if m else 0, text)
+
+
+def _lod_process_of(graph, res_id: str):
+    """The ``lod_generation`` step that made ``res_id``, with its input, or
+    ``(None, None)``."""
+    for e in graph.edges:
+        if e.edge_type != EDGE_HAD_OUTPUT or e.edge_target != res_id:
+            continue
+        proc = _node(graph, e.edge_source)
+        if proc is None or _data(proc).get("dtc_kind") != DTC_KIND:
+            continue
+        inputs = [x.edge_target for x in graph.edges
+                  if x.edge_type == EDGE_HAD_INPUT and x.edge_source == proc.node_id]
+        res_inputs = [i for i in inputs
+                      if _node(graph, i) is not None and _is_resource(_node(graph, i))]
+        return proc, (sorted(res_inputs)[0] if res_inputs else None)
+    return None, None
+
+
+def _origin(graph, res_id: str) -> str:
+    """The first resource of the revision chain ``res_id`` is in: the one the
+    ``lod_generation`` step was declared on."""
+    try:
+        return revisions_of(graph, res_id)[0]
+    except ValueError:
+        return res_id
+
+
+def asset_of(graph, res_id: str) -> str:
+    """The asset (the master) ``res_id`` is a version of — ``res_id`` itself
+    when it is not a version. Walks a version of a version up to the master."""
+    node = _node(graph, res_id)
+    if node is None or not _is_resource(node):
+        raise ValueError(f"{res_id!r} is not a resource of this graph")
+    seen = set()
+    cur = res_id
+    while cur not in seen:
+        seen.add(cur)
+        _proc, source = _lod_process_of(graph, _origin(graph, cur))
+        if source is None:
+            return _origin(graph, cur)
+        cur = source
+    raise ValueError(f"the versions of {res_id!r} loop at {cur!r}")
+
+
+def _entry(graph, res_id: str, *, level, purpose, process_id, master: bool,
+           origin: str) -> Dict[str, Any]:
+    node = _node(graph, res_id)
+    d = _data(node)
+    try:
+        chain = revisions_of(graph, origin)
+    except ValueError:
+        chain = [origin]
+    checksum, url, media = d.get("checksum"), d.get("url"), d.get("media_type")
+    if not checksum:
+        #: a revision writes its files as nodes: one file (or the entry point)
+        #: carries the bytes the version is
+        files = resource_files(graph, res_id)
+        one = files[0] if len(files) == 1 else next(
+            (f for f in files if f["role"] == "entry_point"), None)
+        if one is not None:
+            fd = _data(one["node"])
+            checksum = fd.get("checksum") if len(files) == 1 else checksum
+            url = url or fd.get("url")
+            media = media or fd.get("media_type")
+    return {"id": res_id, "name": getattr(node, "name", ""),
+            "level": level, "purpose": purpose, "master": master,
+            "process_id": process_id, "checksum": checksum or "",
+            "url": url or "", "residency": d.get("residency") or "",
+            "media_type": media or "",
+            "revisions": chain}
+
+
+def _current(graph, res_id: str) -> str:
+    try:
+        return revisions_of(graph, res_id)[-1]
+    except ValueError:
+        return res_id
+
+
+def versions_of(graph, asset_id: str) -> List[Dict[str, Any]]:
+    """The asset and its versions, master first, then by level.
+
+    Each entry: ``{id, name, level, purpose, master, process_id, checksum, url,
+    residency, media_type, revisions}``. ``id`` is the CURRENT revision of the
+    version; ``revisions`` its chain, oldest first. The master's ``level`` is
+    the ``source_level`` its versions declared, or None when nobody said it.
+    """
+    asset = asset_of(graph, asset_id)
+    kids: List[Dict[str, Any]] = []
+    master_levels = set()
+    for e in graph.edges:
+        if e.edge_type != EDGE_HAD_INPUT or e.edge_target != asset:
+            continue
+        proc = _node(graph, e.edge_source)
+        if proc is None or _data(proc).get("dtc_kind") != DTC_KIND:
+            continue
+        params = _data(proc).get("parameters") or {}
+        if params.get("source_level"):
+            master_levels.add(str(params["source_level"]))
+        for o in graph.edges:
+            if o.edge_type != EDGE_HAD_OUTPUT or o.edge_source != proc.node_id:
+                continue
+            out = _node(graph, o.edge_target)
+            if out is None or not _is_resource(out):
+                continue
+            kids.append(_entry(graph, _current(graph, out.node_id),
+                               level=params.get("level"),
+                               purpose=params.get("purpose") or "",
+                               process_id=proc.node_id, master=False,
+                               origin=out.node_id))
+    master_level = sorted(master_levels)[0] if len(master_levels) == 1 else None
+    out = [_entry(graph, _current(graph, asset), level=master_level, purpose="",
+                  process_id=None, master=True, origin=asset)]
+    out += sorted(kids, key=lambda k: (_level_key(k["level"]), k["id"]))
+    return out
+
+
+def version_info(graph, res_id: str) -> Optional[Dict[str, Any]]:
+    """The entry of :func:`versions_of` ``res_id`` belongs to (any revision of
+    it), with ``asset_id``; None when ``res_id`` is neither an asset with
+    versions nor a version."""
+    asset = asset_of(graph, res_id)
+    entries = versions_of(graph, asset)
+    if len(entries) == 1:
+        return None
+    for entry in entries:
+        if res_id == entry["id"] or res_id in entry["revisions"]:
+            return {**entry, "asset_id": asset}
+    return None
+
+
+def inherited_links(graph, res_id: str) -> Dict[str, Any]:
+    """The semantic link of ``res_id``: what hats its ASSET.
+
+    ``{asset_id, inherited, facets: [{id, node_type, name}], binds: [{id,
+    node_type, name, via}]}`` — ``facets`` are the nodes that reach the asset
+    with ``has_linked_resource`` (the RM, the proxy's shape), ``binds`` what
+    those facets are for (epochs, units), read the way
+    :func:`s3dgraphy.geometry.store_backed.store_backed_geometry` reads them.
+    ``inherited`` is True when ``res_id`` is a version and the link was read on
+    its asset."""
+    from ..geometry.store_backed import _binds
+
+    asset = asset_of(graph, res_id)
+    by_id = {n.node_id: n for n in graph.nodes}
+    facets, binds, seen = [], [], set()
+    for e in graph.edges:
+        if e.edge_type != EDGE_HAS_LINKED or e.edge_target != asset:
+            continue
+        facet = by_id.get(e.edge_source)
+        if facet is None or facet.node_id in seen:
+            continue
+        seen.add(facet.node_id)
+        facets.append({"id": facet.node_id, "name": getattr(facet, "name", ""),
+                       "node_type": str(getattr(facet, "node_type", "") or "")})
+        for b in _binds(graph, facet.node_id, by_id):
+            if b["id"] not in {x["id"] for x in binds}:
+                binds.append(b)
+    return {"asset_id": asset, "inherited": asset != _origin(graph, res_id),
+            "facets": facets, "binds": binds}
+
+
+def add_version(graph, master_id: str, *, level: str, purpose: str = "",
+                files: Sequence[Dict[str, Any]] = (), name: Optional[str] = None,
+                master_level: Optional[str] = None,
+                technique: Optional[str] = None,
+                parameters: Optional[Dict[str, Any]] = None,
+                tool: Optional[str] = None,
+                software: Optional[Sequence[Dict[str, Any]]] = None,
+                residency: Optional[str] = None,
+                packaging: Optional[str] = None,
+                size_bytes: Optional[int] = None,
+                primitives: Optional[Dict[str, int]] = None,
+                version_id: Optional[str] = None,
+                author: Optional[str] = None,
+                at: Optional[str] = None) -> Dict[str, Any]:
+    """A new version of the asset ``master_id`` at ``level``, for ``purpose``.
+
+    Writes the version resource (kind of the master, ``tier: distribution``,
+    ``files`` as :func:`add_resource` takes them) and the ``lod_generation``
+    step from the master to it. Idempotent: the id is derived from (asset,
+    level), and adding the same level again with the same bytes changes
+    nothing. The same level with OTHER bytes is refused — that is a revision of
+    the version (``replace_file``), and the error says so.
+
+    ``master_id`` may itself be a version: a LOD2 decimated from LOD1 is a
+    different claim from a LOD2 made from the master, and it is written as it
+    is said; :func:`asset_of` walks up to the master either way.
+
+    Returns ``{version_id, process_id, created, asset_id, level, purpose,
+    warnings}``.
+    """
+    from ..dtc.ingest import declare_derivation
+
+    master = _node(graph, master_id)
+    if master is None or not _is_resource(master):
+        raise ValueError(f"{master_id!r} is not a resource of this graph")
+    lvl = _level(level)
+    asset = asset_of(graph, master_id)
+    vid = version_id or version_id_for(master_id, lvl)
+    for entry in versions_of(graph, asset):
+        if entry["level"] == lvl and not entry["master"] \
+                and vid not in entry["revisions"]:
+            raise ValueError(f"{asset!r} already has a version at {lvl!r} "
+                             f"({entry['id']}): replace its file to revise it")
+    specs = [dict(f) for f in files or ()]
+    node = _node(graph, vid)
+    created = node is None
+    if node is None:
+        add_resource(graph, name=name or f"{master.name} {lvl}",
+                     kind=_data(master).get("url_type") or "", files=specs,
+                     tier="distribution", residency=residency,
+                     packaging=packaging, size_bytes=size_bytes,
+                     primitives=primitives, resource_id=vid)
+    else:
+        if not _is_resource(node):
+            raise ValueError(f"{vid!r} is a {getattr(node, 'node_type', '?')}, "
+                             f"not a resource")
+        new_sum = next((s.get("checksum") for s in specs if s.get("checksum")), None)
+        old_sum = _data(node).get("checksum")
+        if new_sum and old_sum and new_sum != old_sum:
+            raise ValueError(f"the version {lvl!r} of {asset!r} holds other bytes "
+                             f"({old_sum}): replace its file to revise it")
+    params = dict(parameters or {})
+    params["level"] = lvl
+    if purpose:
+        params["purpose"] = str(purpose)
+    if master_level:
+        params["source_level"] = str(master_level).strip()
+    step = declare_derivation(
+        graph, output=vid, inputs=[master_id], dtc_kind=DTC_KIND,
+        process_id=str(uuid.uuid5(_NS, f"lod_generation|{vid}")),
+        name=f"LOD generation {lvl} of {master.name}",
+        technique=technique, parameters=params, tool=tool,
+        software=list(software) if software else None, author=author, at=at)
+    return {"version_id": vid, "process_id": step["process_id"],
+            "created": created, "asset_id": asset, "level": lvl,
+            "purpose": str(purpose or ""), "warnings": step["warnings"]}

{s3dgraphy-1.6.0.dev33 → s3dgraphy-1.6.0.dev34/src/s3dgraphy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev33
+Version: 1.6.0.dev34
 Summary: 3D Stratigraphic Graph Management Library for archaeological and heritage applications
 Author-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>
 Maintainer-email: Emanuel Demetrescu <emanuel.demetrescu@cnr.it>

{s3dgraphy-1.6.0.dev33 → s3dgraphy-1.6.0.dev34}/src/s3dgraphy.egg-info/SOURCES.txt

@@ -299,6 +299,7 @@ src/s3dgraphy/resources/fs_backend.py
 src/s3dgraphy/resources/minio_backend.py
 src/s3dgraphy/resources/resolver.py
 src/s3dgraphy/resources/tiles3tz.py
+src/s3dgraphy/resources/versions.py
 src/s3dgraphy/shelf/__init__.py
 src/s3dgraphy/shelf/core.py
 src/s3dgraphy/stamp/__init__.py
@@ -355,6 +356,7 @@ tests/test_add_resource.py
 tests/test_ai_validation_nodes.py
 tests/test_api_surface.py
 tests/test_asset_dtc_protocol.py
+tests/test_asset_versions.py
 tests/test_aton_shapes.py
 tests/test_attach_only.py
 tests/test_authority_projection.py

s3dgraphy-1.6.0.dev34/tests/test_asset_versions.py

@@ -0,0 +1,164 @@
+"""MICRO-ASSET-VERSIONI, A1 — an asset and its versions.
+
+E.D., 30 Sep / 3 Oct 2026: the asset is the master resource, each version
+(LOD1, LOD2…) a child resource made by a ``lod_generation`` step with
+``dtc_derived_from`` the master, a level and a purpose. The semantic link (RM,
+epoch, unit) is on the asset and the versions inherit it.
+"""
+
+from pathlib import Path
+
+import pytest
+
+from s3dgraphy import api
+from s3dgraphy.graph import Graph
+from s3dgraphy.nodes.epoch_node import EpochNode
+from s3dgraphy.nodes.representation_node import RepresentationModelNode
+
+SHA = {k: "sha256:" + c * 64 for k, c in (("lod0", "0"), ("lod1", "1"),
+                                          ("lod2", "2"), ("lod2b", "b"))}
+
+
+def _podio():
+    """OB_PODIO: the master LOD0 (resident obj), hatted by an RM in an epoch."""
+    g = Graph("templu")
+    api.add_resource(g, resource_id="podio", name="OB_PODIO", kind="3d_model",
+                     tier="master", residency="resident",
+                     files=[{"path": "LOD0/OB_PODIO_LOD0.obj", "checksum": SHA["lod0"],
+                             "media_type": "model/obj"}])
+    g.add_node(RepresentationModelNode("rm", name="OB_PODIO"))
+    g.add_edge("rm~podio", "rm", "podio", "has_linked_resource")
+    g.add_node(EpochNode("ep1", name="Phase I", start_time=-100, end_time=100))
+    g.add_edge("rm~ep1", "rm", "ep1", "has_first_epoch")
+    return g
+
+
+def _three(g):
+    one = api.add_version(g, "podio", level="LOD1", purpose="web",
+                          master_level="LOD0", residency="resident",
+                          files=[{"path": "LOD1/OB_PODIO_LOD1.obj",
+                                  "checksum": SHA["lod1"], "media_type": "model/obj"}])
+    two = api.add_version(g, "podio", level="LOD2", purpose="preview",
+                          master_level="LOD0", residency="resident",
+                          files=[{"path": "LOD2/OB_PODIO_LOD2.obj",
+                                  "checksum": SHA["lod2"], "media_type": "model/obj"}])
+    return one, two
+
+
+def test_a_version_is_a_child_resource_made_by_lod_generation():
+    g = _podio()
+    one, _ = _three(g)
+    v = g.find_node_by_id(one["version_id"])
+    assert v.node_type == "resource" and v.data["url_type"] == "3d_model"
+    assert v.data["tier"] == "distribution"
+    edges = {(e.edge_source, e.edge_target, e.edge_type) for e in g.edges}
+    assert (one["version_id"], "podio", "dtc_derived_from") in edges
+    proc = g.find_node_by_id(one["process_id"])
+    assert proc.node_type == "dtc_process"
+    assert proc.data["dtc_kind"] == "lod_generation"
+    assert proc.data["parameters"] == {"level": "LOD1", "purpose": "web",
+                                       "source_level": "LOD0"}
+    assert (one["process_id"], "podio", "dtc_had_input") in edges
+    assert (one["process_id"], one["version_id"], "dtc_had_output") in edges
+    assert one["asset_id"] == "podio" and one["created"]
+
+
+def test_versions_of_lists_master_then_levels():
+    g = _podio()
+    _three(g)
+    rows = api.versions_of(g, "podio")
+    assert [(r["level"], r["master"], r["purpose"]) for r in rows] == \
+        [("LOD0", True, ""), ("LOD1", False, "web"), ("LOD2", False, "preview")]
+    assert [r["checksum"] for r in rows] == [SHA["lod0"], SHA["lod1"], SHA["lod2"]]
+    # the same answer from any of them
+    assert api.versions_of(g, rows[2]["id"]) == rows
+
+
+def test_adding_the_same_level_twice_changes_nothing():
+    g = _podio()
+    one, _ = _three(g)
+    n, e = len(g.nodes), len(g.edges)
+    again = api.add_version(g, "podio", level="LOD1", purpose="web",
+                            files=[{"path": "LOD1/OB_PODIO_LOD1.obj",
+                                    "checksum": SHA["lod1"]}])
+    assert again["version_id"] == one["version_id"] and not again["created"]
+    assert (len(g.nodes), len(g.edges)) == (n, e)
+
+
+def test_other_bytes_at_a_level_are_a_revision_not_a_second_version():
+    g = _podio()
+    _three(g)
+    with pytest.raises(ValueError, match="replace its file"):
+        api.add_version(g, "podio", level="LOD2",
+                        files=[{"path": "x.obj", "checksum": SHA["lod2b"]}])
+
+
+def test_a_revised_version_keeps_its_level_and_versions_of_gives_the_current():
+    g = _podio()
+    _, two = _three(g)
+    out = api.replace_file(g, two["version_id"], None, checksum=SHA["lod2b"],
+                           media_type="model/obj")
+    rows = api.versions_of(g, "podio")
+    lod2 = rows[-1]
+    assert lod2["level"] == "LOD2" and lod2["id"] == out["new_resource_id"]
+    assert lod2["checksum"] == SHA["lod2b"]
+    assert lod2["revisions"] == [two["version_id"], out["new_resource_id"]]
+    assert api.asset_of(g, out["new_resource_id"]) == "podio"
+
+
+def test_versions_inherit_the_semantic_link_of_the_asset():
+    g = _podio()
+    one, _ = _three(g)
+    links = api.inherited_links(g, one["version_id"])
+    assert links["asset_id"] == "podio" and links["inherited"]
+    assert [f["id"] for f in links["facets"]] == ["rm"]
+    assert [b["id"] for b in links["binds"]] == ["ep1"]
+    # nothing copied onto the version: no edge reaches it but its genesis
+    touching = {e.edge_type for e in g.edges if one["version_id"] in
+                (e.edge_source, e.edge_target)}
+    assert touching == {"dtc_derived_from", "dtc_had_output"}
+    assert not api.inherited_links(g, "podio")["inherited"]
+
+
+def test_store_backed_lists_the_versions_where_the_asset_goes():
+    g = _podio()
+    _three(g)
+    rows = api.store_backed_geometry(g)
+    assert len(rows) == 3
+    assert {r["node_id"] for r in rows} == {"rm"}
+    assert sorted(r.get("level") for r in rows) == ["LOD0", "LOD1", "LOD2"]
+    assert all(r["asset_id"] == "podio" for r in rows)
+    assert all([b["id"] for b in r["bind"]] == ["ep1"] for r in rows)
+
+
+def test_a_resource_without_versions_reads_as_before():
+    g = _podio()
+    rows = api.store_backed_geometry(g)
+    assert len(rows) == 1 and "level" not in rows[0] and "asset_id" not in rows[0]
+    assert api.versions_of(g, "podio")[0]["level"] is None
+
+
+def test_versions_survive_the_emjson_round_trip():
+    g = _podio()
+    _three(g)
+    g2, _ = api.load_emjson(api.graph_to_emjson(g))
+    assert [(r["level"], r["purpose"], r["checksum"]) for r in api.versions_of(g2, "podio")] == \
+        [(r["level"], r["purpose"], r["checksum"]) for r in api.versions_of(g, "podio")]
+
+
+def test_versions_survive_rdf(tmp_path):
+    pytest.importorskip("rdflib")
+    from s3dgraphy.exporter.rdf_exporter import RDFExporter
+    from s3dgraphy.importer.rdf_importer import RDFImporter
+    g = _podio()
+    _three(g)
+    ttl = RDFExporter(str(tmp_path / "g.ttl"), format="turtle").export_single_graph(g)
+    back = RDFImporter().parse(ttl)[0]
+    assert [(r["level"], r["purpose"]) for r in api.versions_of(back, "podio")] == \
+        [("LOD0", ""), ("LOD1", "web"), ("LOD2", "preview")]
+
+
+def test_a_level_is_required():
+    g = _podio()
+    with pytest.raises(ValueError, match="level"):
+        api.add_version(g, "podio", level="  ")