s3dgraphy 1.6.0.dev46__tar.gz → 1.6.0.dev47__tar.gz

{s3dgraphy-1.6.0.dev46/src/s3dgraphy.egg-info → s3dgraphy-1.6.0.dev47}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: s3dgraphy
-Version: 1.6.0.dev46
+Version: 1.6.0.dev47
 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.dev46 → s3dgraphy-1.6.0.dev47}/pyproject.toml

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

{s3dgraphy-1.6.0.dev46 → s3dgraphy-1.6.0.dev47}/src/s3dgraphy/__init__.py

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

{s3dgraphy-1.6.0.dev46 → s3dgraphy-1.6.0.dev47}/src/s3dgraphy/api.py

@@ -3058,6 +3058,68 @@ def resolve_file(entry: Dict[str, Any], **kwargs) -> Dict[str, Any]:
     return resolve(entry, **kwargs)
 
 
+# ── S1 · the Storage list and «find moved» (E.D., 11 Oct 2026) ────────────────
+def storage_rows(graph: Graph, results: Sequence[Dict[str, Any]],
+                 graph_name: str = "") -> List[Dict[str, Any]]:
+    """The files of ``graph`` as ONE list: master, versions by computed level,
+    files of a set, links of a document — with uses, tier, document, the RMs
+    that use each, and its state. ``results`` is :func:`resolve_files`. EMtools
+    and EMStudio draw these rows. See :mod:`s3dgraphy.resources.storage_rows`."""
+    from .resources.storage_rows import storage_rows as _rows
+    return _rows(graph, list(results), graph_name)
+
+
+def find_moved_files(graph: Graph, results: Sequence[Dict[str, Any]],
+                     folders: Sequence[str], **kwargs) -> List[Dict[str, Any]]:
+    """For the files that are ``missing`` (or an empty copy), the candidates found
+    in ``folders`` — by sha256, then by name and size — each saying HOW it was
+    recognised. Proposes only: nothing is changed. See
+    :mod:`s3dgraphy.resources.moved`."""
+    from .resources.moved import find_moved
+    return find_moved(graph, list(results), folders, **kwargs)
+
+
+# ── B1 · disk ↔ bucket: the two copies, and what may be let go (E.D., 11 Oct 2026) ──
+def open_object_store(name: Optional[str] = None, config: Any = None):
+    """The object store of the Resource layer — any S3-compatible one (MinIO
+    today). ``S3_*`` environment, ``EM_OBJECT_STORE`` to choose another
+    implementation (:func:`s3dgraphy.resources.object_store.register_store`)."""
+    from .resources.object_store import open_store
+    return open_store(name, config)
+
+
+def bucket_alignment(graph: Graph, results: Sequence[Dict[str, Any]], store: Any = None, *,
+                     deep: bool = False, **kwargs) -> List[Dict[str, Any]]:
+    """How the disk copy and the bucket copy of each file stand: ``aligned`` (the
+    sha256 of both, read now), ``same_size``, ``differ``, ``disk_only``,
+    ``bucket_only``, ``neither``, ``unknown``. Reads only. See
+    :mod:`s3dgraphy.resources.alignment`."""
+    from .resources.alignment import bucket_alignment as _al
+    return _al(graph, list(results), store or open_object_store(), deep=deep, **kwargs)
+
+
+def plan_free_local(graph: Graph, aligned: Sequence[Dict[str, Any]], **kwargs) -> List[Dict[str, Any]]:
+    """The files whose local copy may be freed (aligned, verified): ``safe`` for a
+    distribution, ``confirm`` for a master or an original, each with its warning."""
+    from .resources.alignment import free_plan
+    return free_plan(graph, list(aligned), **kwargs)
+
+
+def free_local_copies(plan: Sequence[Dict[str, Any]], store: Any = None, **kwargs) -> List[Dict[str, Any]]:
+    """Free the local copies of a plan: the bytes are compared again just before
+    each one leaves; moved to a quarantine folder, or deleted with
+    ``permanent=True``; a master only with ``confirm_masters=True``."""
+    from .resources.alignment import free_local
+    return free_local(list(plan), store or open_object_store(), **kwargs)
+
+
+def promote_to_bucket(graph: Graph, resource_id: str, path: str, store: Any = None, **kwargs) -> Dict[str, Any]:
+    """Upload, READ BACK and verify, then record the bucket as the primary address
+    and keep the disk path as an address too."""
+    from .resources.alignment import promote_verified
+    return promote_verified(graph, resource_id, path, store or open_object_store(), **kwargs)
+
+
 # ── C1 · the standard tree of an EM project (E.D., 4 Oct 2026) ─────────────────
 def create_em_project(parent: str, name: str, **kwargs) -> Dict[str, Any]:
     """«New EM project…»: EM/ (DosCo/, proxies/), RB/, SB/, RM/, README.md,

s3dgraphy-1.6.0.dev47/src/s3dgraphy/resources/alignment.py

@@ -0,0 +1,273 @@
+"""Disk ↔ bucket · are the two copies the same bytes, and what may be let go.
+
+A resource may live on the disk and in the bucket at once (two addresses of ONE
+resource, :mod:`s3dgraphy.resources.addresses`). This says, for each file, how
+the two stand — and plans, and carries out, the freeing of the local copy once
+the bucket holds it.
+
+ALIGNMENT, per file (``bucket_alignment``):
+
+* ``aligned``    — on both, and the sha256 of the bucket's bytes is the disk
+                   file's (read this time: the only state that is a proof);
+* ``same_size``  — on both, same size, digests not compared (the light check);
+* ``differ``     — on both and NOT the same: another size, or another sha256.
+                   Stop and look: neither copy is to be trusted over the other
+                   without a date;
+* ``disk_only``  — on the disk; the bucket has no object for it;
+* ``bucket_only``— in the bucket; no copy on this computer;
+* ``neither``    — recorded in the bucket, not found there, not on the disk;
+* ``unknown``    — the store did not answer, or there is nothing to compare.
+
+FREEING (``free_plan`` → ``free_local``): only an ``aligned`` file can be freed,
+and the bytes are compared AGAIN right before anything leaves the disk — a check
+of yesterday is not a check. A DISTRIBUTION (a LOD, a GLB for the web) is remade
+from its master: freeing it costs a button. A MASTER, an untiered resource and
+the original documents are NOT remade by anybody: they are freed only on an
+explicit confirm, and the plan says how many OTHER independent copies the graph
+knows. By default the file is moved to a quarantine folder (reversible);
+``permanent=True`` deletes it. Nothing is written into the graph here except
+what ``promote_verified`` records.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+from typing import Any, Callable, Dict, Iterable, List, Optional
+
+from .addresses import addresses, _write
+from .locate import entries_of, sha256_hex
+from .object_store import ObjectStore, StoreError
+
+STATES = ("aligned", "same_size", "differ", "disk_only", "bucket_only", "neither", "unknown")
+SURE = ("aligned",)
+
+
+def _sha256_file(path: str) -> str:
+    import hashlib
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _tier_and_copies(graph, node_id: str, nodes, set_of):
+    node = nodes.get(node_id)
+    d = getattr(node, "data", None) or {}
+    owner = nodes.get(set_of.get(node_id)) if set_of.get(node_id) else None
+    od = getattr(owner, "data", None) or {}
+    return str(d.get("tier") or od.get("tier") or "")
+
+
+def _bucket_locator(node, store: ObjectStore) -> Optional[str]:
+    for a in addresses(node):
+        if store.key_of(a["locator"]) is not None:
+            return a["locator"]
+    return None
+
+
+def bucket_alignment(graph, results: List[Dict[str, Any]], store: ObjectStore, *,
+                     deep: bool = False, hasher: Optional[Callable[[str], str]] = None,
+                     only: Optional[Iterable[str]] = None) -> List[Dict[str, Any]]:
+    """For every resource that is on the disk or has a bucket address, how the
+    two stand. ``results`` is what ``resolve_files`` answered (its ``path`` is
+    the disk copy). ``deep`` reads the bucket's bytes and compares the sha256;
+    without it only existence and size are compared (no bytes leave the store).
+    ``only`` limits the check to some resource ids. Reads only."""
+    hasher = hasher or _sha256_file
+    wanted = set(only) if only is not None else None
+    nodes = {n.node_id: n for n in getattr(graph, "nodes", [])}
+    set_of = {e.edge_target: e.edge_source for e in getattr(graph, "edges", [])
+              if e.edge_type == "has_file"}
+    by_id = {r["id"]: r for r in results}
+    out: List[Dict[str, Any]] = []
+    for e in entries_of(graph):
+        rid = e["id"]
+        if wanted is not None and rid not in wanted:
+            continue
+        node = nodes.get(rid)
+        r = by_id.get(rid) or {}
+        path = r.get("path") or ""
+        on_disk = bool(path) and os.path.isfile(path)
+        loc = _bucket_locator(node, store)
+        if not on_disk and not loc:
+            continue
+        row = {"id": rid, "name": e["name"], "path": path if on_disk else "",
+               "bucket": loc or "", "key": store.key_of(loc) if loc else "",
+               "tier": _tier_and_copies(graph, rid, nodes, set_of),
+               "size_disk": os.path.getsize(path) if on_disk else None,
+               "size_bucket": None, "sha256": sha256_hex(r.get("sha256") or e["checksum"]),
+               "state": "unknown", "note": "", "verified": False}
+        if not loc:
+            row["state"], row["note"] = "disk_only", "the graph records no bucket copy"
+            out.append(row)
+            continue
+        try:
+            st = store.stat(row["key"])
+        except StoreError as exc:
+            row["note"] = str(exc)
+            out.append(row)
+            continue
+        if st is None:
+            row["state"] = "disk_only" if on_disk else "neither"
+            row["note"] = "the graph says the bucket has it; the object is not there"
+            out.append(row)
+            continue
+        row["size_bucket"] = st["size"]
+        if not on_disk:
+            row["state"] = "bucket_only"
+            out.append(row)
+            continue
+        if st["size"] != row["size_disk"]:
+            row["state"], row["note"] = "differ", "not the same size"
+            out.append(row)
+            continue
+        row["state"] = "same_size"
+        if deep:
+            try:
+                theirs = store.sha256(row["key"])
+                mine = hasher(path)
+            except (StoreError, OSError) as exc:
+                row["note"] = str(exc)
+                out.append(row)
+                continue
+            row["sha256"] = mine
+            if theirs == mine:
+                row["state"], row["verified"] = "aligned", True
+            else:
+                row["state"], row["note"] = "differ", "same size, not the same bytes"
+        out.append(row)
+    return out
+
+
+def free_plan(graph, aligned: List[Dict[str, Any]], *, protect: Iterable[str] = ()) -> List[Dict[str, Any]]:
+    """What may be freed from the rows ``bucket_alignment`` gave (only the
+    ``aligned`` ones; run it with ``deep=True``). Each item: ``{id, name, path,
+    size, level, warning, copies}`` — ``level`` is ``safe`` (a distribution: it
+    is remade from its master) or ``confirm`` (a master, an untiered resource,
+    a document: nobody remakes it). ``copies`` counts the OTHER addresses the
+    graph records (not this disk path, not the bucket). ``protect`` lists
+    folders whose files are never planned (the cache, a project's ``.em_cache``)."""
+    nodes = {n.node_id: n for n in getattr(graph, "nodes", [])}
+    keep = [os.path.abspath(p) for p in protect if p]
+    plan = []
+    for r in aligned:
+        if r["state"] != "aligned" or not r["path"]:
+            continue
+        if any(os.path.abspath(r["path"]).startswith(k + os.sep) for k in keep):
+            continue
+        others = [a for a in addresses(nodes.get(r["id"]))
+                  if a["locator"] != r["bucket"] and os.path.abspath(a["locator"]) != os.path.abspath(r["path"])
+                  and a.get("ok") is not False]
+        distribution = r["tier"] == "distribution"
+        warning = ("" if distribution else
+                   ("This is a MASTER or an original: nobody can remake it. "
+                    if r["tier"] == "master" else
+                    "This is an original (not a derived version): nobody can remake it. ")
+                   + (f"The graph knows {len(others)} other copy(ies)." if others else
+                      "The graph knows NO other copy than the bucket's."))
+        plan.append({"id": r["id"], "name": r["name"], "path": r["path"],
+                     "size": r["size_disk"] or 0, "level": "safe" if distribution else "confirm",
+                     "warning": warning, "copies": len(others), "bucket": r["bucket"],
+                     "key": r["key"]})
+    return plan
+
+
+def free_local(plan: List[Dict[str, Any]], store: ObjectStore, *, confirm_masters: bool = False,
+               permanent: bool = False, quarantine: str = "",
+               hasher: Optional[Callable[[str], str]] = None) -> List[Dict[str, Any]]:
+    """Carry the plan out. For EVERY file the bucket's sha256 and the disk
+    file's are compared again just before it leaves; a difference, an error or
+    a missing object refuses that file and touches nothing. ``confirm`` items
+    are skipped unless ``confirm_masters``. The file is moved into
+    ``quarantine`` (kept relative to its own folder's name, never overwriting),
+    or deleted when ``permanent``. Returns ``[{id, path, action, reason,
+    bytes}]`` with action ``freed`` | ``quarantined`` | ``refused`` | ``skipped``."""
+    hasher = hasher or _sha256_file
+    report = []
+
+    def rec(item, action, reason="", moved_to=""):
+        report.append({"id": item["id"], "path": item["path"], "action": action,
+                       "reason": reason, "bytes": item["size"] if action in ("freed", "quarantined") else 0,
+                       "moved_to": moved_to})
+
+    for item in plan:
+        path = item["path"]
+        if item["level"] == "confirm" and not confirm_masters:
+            rec(item, "skipped", "a master or an original: it needs your explicit confirm")
+            continue
+        if not os.path.isfile(path):
+            rec(item, "refused", "the file is not on the disk any more")
+            continue
+        try:
+            st = store.stat(item["key"])
+            if st is None:
+                rec(item, "refused", "the bucket does not have the object")
+                continue
+            theirs, mine = store.sha256(item["key"]), hasher(path)
+        except (StoreError, OSError) as exc:
+            rec(item, "refused", f"could not verify: {exc}")
+            continue
+        if theirs != mine:
+            rec(item, "refused", "the bytes of the bucket are not the disk file's: nothing was touched")
+            continue
+        try:
+            if permanent:
+                os.remove(path)
+                rec(item, "freed")
+            else:
+                if not quarantine:
+                    rec(item, "refused", "no quarantine folder given")
+                    continue
+                os.makedirs(quarantine, exist_ok=True)
+                dest = os.path.join(quarantine, os.path.basename(path))
+                n = 1
+                while os.path.exists(dest):
+                    n += 1
+                    stem, ext = os.path.splitext(os.path.basename(path))
+                    dest = os.path.join(quarantine, f"{stem}.{n}{ext}")
+                shutil.move(path, dest)
+                rec(item, "quarantined", moved_to=dest)
+        except OSError as exc:
+            rec(item, "refused", f"could not remove it: {exc}")
+    return report
+
+
+def promote_verified(graph, resource_id: str, path: str, store: ObjectStore, *,
+                     hasher: Optional[Callable[[str], str]] = None) -> Dict[str, Any]:
+    """Upload ``path`` to the bucket under the resource's own id, READ IT BACK
+    and compare the sha256, and only then record the bucket as an address of the
+    resource — keeping the disk copy as an address too (the older promotion
+    replaced ``data.url`` and the disk path was lost). The bucket address becomes
+    the primary (``data.url``: what Heriverse reads); the disk path stays in
+    ``data.addresses`` as ``resident``. Refuses, writing nothing, when the bytes
+    read back are not the file's."""
+    node = graph.find_node_by_id(resource_id)
+    if node is None:
+        raise ValueError(f"no resource {resource_id!r}")
+    hasher = hasher or _sha256_file
+    if not os.path.isfile(path):
+        raise ValueError(f"{path!r} is not a file")
+    key = store.key_for(resource_id, os.path.basename(path))
+    store.put(path, key)
+    mine, theirs = hasher(path), store.sha256(key)
+    if mine != theirs:
+        raise StoreError(f"the bucket's bytes are not the file's after the upload "
+                         f"({theirs[:12]}… ≠ {mine[:12]}…): nothing was recorded")
+    data = node.data if isinstance(getattr(node, "data", None), dict) else {}
+    node.data = data
+    data.setdefault("checksum", "sha256:" + mine)
+    bucket = store.locator(key)
+    current = addresses(node)
+    # the disk path is recorded unless the resource already has a local address
+    disk = path if not any("://" not in a["locator"] for a in current) else None
+    entries = [{"locator": bucket, "residency": "resident"}]
+    for a in current:
+        if a["locator"] != bucket:
+            entries.append({k: v for k, v in a.items() if k != "primary"})
+    if disk:
+        entries.append({"locator": path, "residency": "resident"})
+    data["url"] = bucket
+    _write(node, entries)
+    return {"id": resource_id, "key": key, "bucket": bucket, "sha256": mine}

{s3dgraphy-1.6.0.dev46 → s3dgraphy-1.6.0.dev47}/src/s3dgraphy/resources/locate.py

@@ -171,15 +171,24 @@ def resolve(entry: Dict[str, Any], *, project_root: Optional[str] = None,
         look = parsed[0] if parsed else ""
     elif locator.startswith("psx://"):
         look = ""
-    if not path and look and not remote and not look.startswith(("blend://", "psx://")):
-        for cand in local_candidates(look, bases):
+    # a resource may have SEVERAL addresses of the same bytes (the disk and the
+    # bucket): when the primary is not a local one, a local address is tried too
+    cand_look = "" if remote else look
+    if not cand_look:
+        for other in entry.get("addresses") or ():
+            o = str(other or "")
+            if o and o != locator and not o.lower().startswith(_REMOTE + ("blend://", "psx://")):
+                cand_look = o
+                break
+    if not path and cand_look and not cand_look.startswith(("blend://", "psx://")):
+        for cand in local_candidates(cand_look, bases):
             if os.path.isfile(cand) or os.path.isdir(cand):
                 if os.path.isfile(cand) and is_empty_copy(cand):
                     empty = empty or cand
                     continue
                 path = cand
                 break
-        positions.append({"kind": "path", "where": path or empty or locator,
+        positions.append({"kind": "path", "where": path or empty or cand_look,
                           "ok": bool(path)})
     elif locator.startswith(("blend://", "psx://")) and not look:
         positions.append({"kind": "path", "where": locator, "ok": None})
@@ -236,6 +245,8 @@ def entries_of(graph: Any) -> List[Dict[str, Any]]:
         out.append({"id": node.node_id, "name": str(getattr(node, "name", "") or ""),
                     "node_type": node.node_type,
                     "locator": str(data.get("url") or getattr(node, "url", "") or ""),
+                    "addresses": [str(a["locator"]) for a in (data.get("addresses") or [])
+                                  if isinstance(a, dict) and a.get("locator")],
                     "checksum": data.get("checksum") or ""})
     return out
 

s3dgraphy-1.6.0.dev47/src/s3dgraphy/resources/moved.py

@@ -0,0 +1,149 @@
+"""Find moved · where did the files that are not here any more go?
+
+A file the graph points at can be «missing» because the folder was renamed, the
+project copied to another disk, a DosCo reordered. The identity of the file did
+not change: its sha256 (when the graph has it), its size and its name. This
+looks for it in the folders it is given and PROPOSES — it never changes the
+graph and never moves a byte; the tool that calls it shows the candidates and
+the person says yes (the relink is the one ``Find here…`` already makes).
+
+Each candidate says HOW it was recognised, from the surest:
+
+* ``exact``          — the same name and the same sha256;
+* ``exact_renamed``  — another name, the same sha256 (the bytes are the file's);
+* ``probable``       — the same name and the same size, the graph has no sha256;
+* ``possible``       — the same name only.
+
+One walk of the folders serves every missing file; bytes are hashed only for
+files of the expected size, and within a budget (``max_hash_bytes``), so a
+project of hundreds of gigabytes is not read whole. Pure I/O on the local disk.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import os
+from typing import Any, Callable, Dict, Iterable, List, Optional
+
+from .locate import entries_of, sha256_hex
+from .storage_rows import last_segment
+
+HOW = ("exact", "exact_renamed", "probable", "possible")
+_SKIP_DIRS = {".git", "node_modules", "__pycache__", ".Trash", ".Spotlight-V100", ".fseventsd"}
+
+
+def _sha256_file(path: str) -> str:
+    h = hashlib.sha256()
+    with open(path, "rb") as fh:
+        for chunk in iter(lambda: fh.read(1 << 20), b""):
+            h.update(chunk)
+    return h.hexdigest()
+
+
+def _walk(folders: Iterable[str], max_files: int):
+    """``(by_name, by_size)`` of every file under ``folders`` (hidden folders of
+    tools and the cache are not entered; a symlink to a folder is not followed)."""
+    by_name: Dict[str, List[str]] = {}
+    by_size: Dict[int, List[str]] = {}
+    seen, count = set(), 0
+    for top in folders:
+        top = os.path.abspath(os.path.expanduser(str(top or "")))
+        if not os.path.isdir(top):
+            continue
+        for dirpath, dirnames, filenames in os.walk(top, followlinks=False):
+            dirnames[:] = [d for d in dirnames if d not in _SKIP_DIRS]
+            for fn in filenames:
+                full = os.path.join(dirpath, fn)
+                if full in seen:
+                    continue
+                seen.add(full)
+                try:
+                    size = os.path.getsize(full)
+                except OSError:
+                    continue
+                if size == 0:
+                    continue                      # an empty copy is not a find
+                by_name.setdefault(fn.lower(), []).append(full)
+                by_size.setdefault(size, []).append(full)
+                count += 1
+                if count >= max_files:
+                    return by_name, by_size
+    return by_name, by_size
+
+
+def find_moved(graph, results: List[Dict[str, Any]], folders: Iterable[str], *,
+               hasher: Optional[Callable[[str], str]] = None,
+               max_files: int = 400_000, max_hash_bytes: int = 4 << 30,
+               states: Iterable[str] = ("missing", "empty_copy")) -> List[Dict[str, Any]]:
+    """For every resource of ``results`` in one of ``states``, the files found
+    in ``folders`` that may be it: ``[{id, name, state, wanted: {sha256, size,
+    name}, matches: [{path, how, size}]}]`` — only resources with at least one
+    match, the surest match first. ``results`` is what ``resolve_files``
+    answered; nothing is written."""
+    hasher = hasher or _sha256_file
+    states = set(states)
+    info = {e["id"]: e for e in entries_of(graph)}
+    nodes = {n.node_id: n for n in getattr(graph, "nodes", [])}
+    wanted_rows = []
+    for r in results:
+        if r.get("state") not in states or r.get("files"):
+            continue                              # a set's state is its files' own
+        e = info.get(r["id"])
+        if e is None:
+            continue
+        data = getattr(nodes.get(r["id"]), "data", None) or {}
+        locs = [e["locator"]] + [a.get("locator") for a in (data.get("addresses") or [])
+                                 if isinstance(a, dict)]
+        name = next((s for s in (last_segment(x) for x in locs if isinstance(x, str) and x)
+                     if s and not s.lower().startswith("sha256:")), "")
+        size = data.get("size_bytes")
+        wanted_rows.append((r, {"sha256": sha256_hex(e["checksum"]), "name": name,
+                                "size": int(size) if isinstance(size, (int, float)) else 0}))
+    if not wanted_rows:
+        return []
+    by_name, by_size = _walk(folders, max_files)
+    budget = [max_hash_bytes]
+    cache: Dict[str, str] = {}
+
+    def digest(path: str, size: int) -> str:
+        if path in cache:
+            return cache[path]
+        if size > budget[0]:
+            return ""
+        budget[0] -= size
+        try:
+            cache[path] = hasher(path) or ""
+        except OSError:
+            cache[path] = ""
+        return cache[path]
+
+    out = []
+    for r, w in wanted_rows:
+        found: Dict[str, Dict[str, Any]] = {}
+
+        def add(path: str, how: str) -> None:
+            if path not in found or HOW.index(how) < HOW.index(found[path]["how"]):
+                found[path] = {"path": path, "how": how, "size": os.path.getsize(path)}
+
+        same_name = by_name.get(w["name"].lower(), []) if w["name"] else []
+        if w["sha256"]:
+            pool = {p: True for p in same_name}
+            if w["size"]:
+                for p in by_size.get(w["size"], []):
+                    pool.setdefault(p, False)
+            for path, named in pool.items():
+                if digest(path, os.path.getsize(path)) == w["sha256"]:
+                    add(path, "exact" if named else "exact_renamed")
+            for path in same_name:               # the name is here, the bytes are not the graph's
+                if path not in found:
+                    add(path, "possible")
+        else:
+            for path in same_name:
+                size_ok = bool(w["size"]) and os.path.getsize(path) == w["size"]
+                add(path, "probable" if size_ok else "possible")
+        if found:
+            out.append({"id": r["id"], "name": r.get("name") or w["name"], "state": r["state"],
+                        "wanted": w,
+                        "matches": sorted(found.values(),
+                                          key=lambda m: (HOW.index(m["how"]), m["path"]))})
+    return out