simulo 0.26.0__py3-none-any.whl

simulo/_client/asset_package.py

@@ -0,0 +1,1103 @@
+"""Asset-package inspection + assembly for ``simulo asset publish``/``validate``.
+
+The client half of the USD Asset Catalogs publish flow (wire truth in
+``simulo.interfaces.platform.asset_catalog``): given a directory or file the
+user pointed at, produce everything the initiate request needs —
+
+* the **source format** (``usd`` or ``urdf``) and the **entry** path,
+  auto-detected where unambiguous and refused with a corrected, copyable
+  command where not (``--entry`` is required only when the entry is ambiguous);
+* the **file manifest** (package-root-relative POSIX paths, sizes, bare-hex
+  sha256s) over the SOURCE files;
+* the **content digest** — the package content-identity key (kind + name +
+  entry + the sorted source-file digests), **algo-prefixed** ``sha256:<hex>``
+  per the shared asset-catalog interface ("content_digest canonical form: algo-prefixed everywhere");
+* a **deterministic tar** of the package (sorted members, zeroed metadata) so
+  identical trees produce identical archive bytes — idempotent re-publish is
+  byte-stable end to end.
+
+**The refusal catalog lives here.** Absolute paths, relative references
+that escape the package root, ``nucleus://`` paths, the removed legacy
+``simulo://`` alias (never valid inside a published asset), and URLs inside
+the package all FAIL publication, each named with the exact authored
+reference and the file that contains it, plus how to fix it. The ``--root``
+flag is a security and portability boundary: dependencies are collected
+beneath it and never swept from elsewhere on the workstation.
+
+**Heavy-import discipline.** The USD path needs ``pxr`` (``usd-core``), which
+ships behind the ``simulo[assets]`` extra — imported LAZILY inside
+:func:`_load_pxr_usdutils` only, so ``import simulo`` and every non-USD command
+(including all URDF publishes, which need no OPT-IN extra: ``defusedxml``
+(hardened XML — security NIT, PR-12 fix loop 2) + path math, both tiny,
+always-installed base dependencies, not the ``simulo[assets]`` extra) stay
+featherweight. A missing USD extra fails with the one-line copyable install
+command.
+
+**Windows-safety.** Every path this module puts in a manifest or tar is
+NTFS-clean: a source file whose package-relative path contains ``:`` or ``\\``,
+names a reserved device (``CON``, ``NUL``, ``COM1``…), or ends a segment with
+``.``/space is REFUSED here (naming the file), because PR-8's cache extraction
+on Windows could not represent it faithfully. Mirrors ``cli.py``'s
+``_is_windows_unsafe_basename`` reasoning (kept self-contained here — ``cli``
+imports this module, so importing back would cycle).
+
+**Symlink / realpath containment (security HIGH, PR-7 trio review; freeze
+"Packaging containment is REALPATH-based").** Every authored reference this
+module resolves (``_resolve_relative_reference``, ``_resolve_package_uri``) is
+checked two ways before it is trusted: its literal path must never itself be a
+symlink (refused outright, regardless of target — a symlink is never trusted
+content, matching :func:`_collect_tree_files`'s tree-walk policy), and its
+``os.path.realpath()`` — which resolves every symlinked directory in the whole
+chain, not just the leaf — must stay under ``root``'s own realpath. A plain
+``os.path.normpath`` + string ``commonpath`` check (the pre-review
+implementation) cannot see a symlinked INTERMEDIATE directory that walks the
+resolved path outside the root; realpath does. :func:`build_archive` asserts
+the same property one more time, immediately before each file's bytes are
+read into the tar — the last point before bytes leave this process.
+"""
+
+from __future__ import annotations
+
+import io
+import os
+import re
+import tarfile
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from hashlib import sha256
+from pathlib import Path, PurePosixPath
+from types import ModuleType
+from typing import Callable, Iterable, Optional
+
+import defusedxml.ElementTree as DefusedET
+from defusedxml.common import DefusedXmlException
+
+from simulo.interfaces.platform.asset_catalog import (
+    MAX_ASSET_FILES,
+    MAX_ASSET_VERSION_BYTES,
+    format_asset_ref,
+)
+
+#: Version tag folded into the content digest so a future change to the digest
+#: recipe can never silently collide with today's identities.
+_CONTENT_DIGEST_SCHEMA = "simulo.asset_content.v1"
+
+#: USD layer suffixes the inspector parses for references. ``.usdz`` is a
+#: sealed package — included as an opaque file, valid as an entry only when
+#: named explicitly via ``--entry`` (never auto-detected).
+_USD_LAYER_SUFFIXES = (".usd", ".usda", ".usdc")
+_USD_ALL_SUFFIXES = _USD_LAYER_SUFFIXES + (".usdz",)
+
+#: Chunk size for streaming file hashing (bounded memory on multi-GB meshes).
+_HASH_CHUNK_BYTES = 8 * 1024 * 1024
+
+_WINDOWS_RESERVED_DEVICE_NAMES = frozenset(
+    {"CON", "PRN", "AUX", "NUL"}
+    | {f"COM{i}" for i in range(1, 10)}
+    | {f"LPT{i}" for i in range(1, 10)}
+    | {"COM¹", "COM²", "COM³", "LPT¹", "LPT²", "LPT³"}
+)
+
+#: ``<scheme>://`` or ``<scheme>:`` URI detector for authored references. A
+#: single letter followed by ``:`` is treated as a Windows drive (absolute
+#: path), not a scheme — both are refused, with different copy.
+_URI_SCHEME_RE = re.compile(r"^([A-Za-z][A-Za-z0-9+.-]*):")
+
+#: Authored-reference wildcard/pattern markers (UDIM tiles, clip patterns).
+#: A ref containing one cannot be stat-ed literally; it is checked for
+#: escaping-by-syntax only.
+_PATTERN_MARKERS = ("<", ">", "*")
+
+
+class AssetPackageError(ValueError):
+    """A package cannot be published as-is (refusal catalog, missing deps, caps).
+
+    The message is finished, user-language-first copy — callers print it
+    verbatim (exit 1)."""
+
+
+class AssetUsageError(AssetPackageError):
+    """The invocation needs a corrected command (e.g. ambiguous ``--entry``).
+
+    Distinct from :class:`AssetPackageError` so the CLI can exit 2 (usage)
+    instead of 1 — the message always contains the corrected, copyable
+    command (non-interactive use always prints the corrected, copyable
+    command)."""
+
+
+class AssetsExtraMissingError(AssetPackageError):
+    """The USD inspection extra (``usd-core``) is not installed."""
+
+
+#: The one-line copyable fix for a missing ``[assets]`` extra.
+ASSETS_EXTRA_INSTALL_HINT = 'pip install "simulo[assets]"'
+
+
+def _load_pxr_usdutils() -> ModuleType:  # pragma: no cover - exercised via _extract_usd_references seam
+    """Import ``pxr.UsdUtils`` lazily — the ONLY place ``pxr`` is ever imported.
+
+    Raises :class:`AssetsExtraMissingError` with the copyable install command
+    when the ``[assets]`` extra is absent. Never called on the URDF path.
+    """
+    try:
+        from pxr import UsdUtils  # noqa: PLC0415 — lazy by design (heavy optional extra)
+    except ImportError as exc:
+        raise AssetsExtraMissingError(
+            "Publishing or validating a USD package needs the USD inspection extra. "
+            f"Install it with: {ASSETS_EXTRA_INSTALL_HINT}"
+        ) from exc
+    # `pxr` publishes no stubs (see the mypy override in pyproject.toml), so
+    # `UsdUtils` arrives as Any. Bind through a typed local so this function
+    # hands its caller a real ModuleType instead of leaking Any across the seam.
+    usd_utils: ModuleType = UsdUtils
+    return usd_utils
+
+
+def _extract_usd_references(layer_path: Path) -> list[str]:
+    """Every authored external reference string in one USD layer file.
+
+    ``UsdUtils.ExtractExternalReferences`` returns ``(subLayers, references,
+    payloads)`` — all three are authored asset-path strings, exactly what the
+    refusal catalog must judge (it judges what the user AUTHORED, not what a
+    resolver would make of it). Module-level seam so tests can fake it without
+    installing ``usd-core``.
+    """
+    usd_utils = _load_pxr_usdutils()
+    sublayers, references, payloads = usd_utils.ExtractExternalReferences(str(layer_path))
+    return [ref for ref in (*sublayers, *references, *payloads) if ref]
+
+
+@dataclass(frozen=True)
+class ManifestEntry:
+    """One manifest row — mirrors the wire ``FileManifestEntry`` (bare-hex sha)."""
+
+    path: str
+    size_bytes: int
+    sha256: str
+
+
+@dataclass(frozen=True)
+class InspectedPackage:
+    """Everything ``publish``/``validate`` need about one inspected package."""
+
+    source_format: str
+    """``"usd"`` or ``"urdf"``."""
+
+    root: Path
+    """The package root every manifest path is relative to."""
+
+    entry: str
+    """Package-root-relative POSIX path of the entry file."""
+
+    entry_auto_detected: bool
+    """``True`` when the entry was inferred rather than passed via ``--entry``."""
+
+    manifest: tuple[ManifestEntry, ...]
+    """Sorted (by path) manifest over the PACKAGED bytes."""
+
+    content_digest: str
+    """The package content-identity key, algo-prefixed (``sha256:<hex>``)."""
+
+    base_mode: Optional[str]
+    """``fixed``/``floating`` for a robot where declared, else ``None``."""
+
+    reference_count: int
+    """How many authored references were checked and resolved in-package."""
+
+    warnings: tuple[str, ...]
+    """Non-fatal disclosures — every one is printed to the user."""
+
+    scale: Optional[float] = None
+    """The ``--scale`` global import unit-scale (URDF only, PR-12) — folded
+    into :attr:`content_digest` and sent as the initiate ``options.scale``;
+    ``None`` when not declared."""
+
+    entry_override_bytes: Optional[bytes] = field(repr=False, default=None)
+    """The REWRITTEN entry bytes (PR-12 fix loop 2 — URDF mesh-path
+    normalization: every ``<mesh>``/``<texture> filename`` is rewritten from
+    its original form (``package://...`` or an already-relative ref) to a
+    self-contained, entry-directory-relative path, so the uploaded URDF
+    never depends on ``package://`` resolution the cloud converter cannot
+    safely perform — see :func:`_inspect_urdf`). ``None`` for every USD
+    package and for a URDF with no mesh/texture references at all (nothing
+    to rewrite — the packaged entry is the on-disk file, byte-for-byte, an
+    unchanged invariant for that common case). When set, :func:`build_archive`
+    packages THESE bytes for the entry instead of streaming
+    ``source_path(entry)`` from disk, and :func:`_build_manifest` hashed
+    THESE bytes (via its ``overrides`` argument) to produce the entry's
+    manifest row and, transitively, the content digest — the digest is
+    always computed over what gets uploaded, never the pre-rewrite
+    original."""
+
+    _files: tuple[tuple[str, Path], ...] = field(repr=False, default=())
+    """(rel_posix, abs_path) for every packaged file, sorted by rel path."""
+
+    @property
+    def total_size_bytes(self) -> int:
+        return sum(entry.size_bytes for entry in self.manifest)
+
+    @property
+    def file_count(self) -> int:
+        return len(self.manifest)
+
+    def source_path(self, rel_path: str) -> Path:
+        """The on-disk path that will be packaged for *rel_path*."""
+        for path, abspath in self._files:
+            if path == rel_path:
+                return abspath
+        raise KeyError(rel_path)
+
+
+# ---------------------------------------------------------------------------
+# Shared helpers — naming, Windows safety, hashing, refusal judgments
+# ---------------------------------------------------------------------------
+
+
+def slugify_name(text: str) -> str:
+    """Reduce a file/directory name to an asset-name slug (the ``--name`` default)."""
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower()).strip("-")
+    return slug[:63].rstrip("-")
+
+
+def validate_asset_name(name: str, *, kind: str, origin_hint: str) -> None:
+    """Validate *name* against the contract grammar; raise finished copy if bad.
+
+    ``format_asset_ref`` is the shared grammar implementation — it rejects bad
+    slugs AND reserved catalog words in the name position, with the contract's
+    own user-language message; this wraps that in "pass --name" guidance.
+    """
+    try:
+        format_asset_ref(kind=kind, name=name)
+    except ValueError as exc:
+        raise AssetUsageError(
+            f"Cannot use {name!r} as the asset name ({origin_hint}): {exc}\n" f"Pass an explicit name: --name <slug>"
+        ) from exc
+
+
+def _is_windows_unsafe_segment(segment: str) -> bool:
+    """Mirror of ``cli._is_windows_unsafe_basename``, applied per path segment."""
+    if ":" in segment or "\x00" in segment:
+        return True
+    if segment != segment.rstrip(". "):
+        return True
+    stem = segment.split(".", 1)[0].rstrip(" ")
+    return stem.upper() in _WINDOWS_RESERVED_DEVICE_NAMES
+
+
+def _require_ntfs_clean_relpath(rel: str) -> None:
+    if "\\" in rel:
+        raise AssetPackageError(
+            f"Cannot package {rel!r}: the path contains a backslash, which is not a valid "
+            "path separator inside an asset package. Rename the file and re-run."
+        )
+    for segment in rel.split("/"):
+        if _is_windows_unsafe_segment(segment):
+            raise AssetPackageError(
+                f"Cannot package {rel!r}: the path segment {segment!r} is not portable to "
+                "Windows (':' writes an NTFS alternate data stream; CON/NUL/COM1… name "
+                "devices; a trailing '.' or space is silently stripped). Rename the file "
+                "and re-run."
+            )
+
+
+def _hash_file(path: Path) -> tuple[str, int]:
+    digest = sha256()
+    size = 0
+    with path.open("rb") as fh:
+        while True:
+            chunk = fh.read(_HASH_CHUNK_BYTES)
+            if not chunk:
+                break
+            digest.update(chunk)
+            size += len(chunk)
+    return digest.hexdigest(), size
+
+
+def canonical_scale_token(scale: float) -> str:
+    """The canonical string form of a ``--scale`` value as folded into the
+    content digest: ``repr(float(scale))`` — Python's shortest round-tripping
+    repr, identical for the same IEEE-754 double everywhere, and a JSON
+    number round-trips to the same double, so this client (folding the flag
+    at publish) and the cloud validator (folding the job args'
+    ``options.scale`` in its digest recompute) always derive the same token.
+    VALUE-MIRROR of ``simulo.backend.validation.urdf_convert.
+    canonical_scale_token`` (mirrored, not imported — the thin client never
+    depends on the backend; this docstring is the drift anchor)."""
+    return repr(float(scale))
+
+
+def compute_content_digest(
+    *, kind: str, name: str, entry: str, manifest: Iterable[ManifestEntry], scale: Optional[float] = None
+) -> str:
+    """The package content identity: kind + name + entry + sorted file digests.
+
+    Algo-prefixed ``sha256:<hex>`` (freeze: "content_digest canonical form:
+    algo-prefixed everywhere it is written/compared"). The server deduplicates
+    by string equality on this exact value, so the recipe is pinned by
+    :data:`_CONTENT_DIGEST_SCHEMA` and must never change silently.
+
+    ``scale`` (PR-12 — the freeze's "## PR-7 amendments": scale "folds into
+    the content-digest recipe, no file rewrite ever") appends a
+    ``scale:<token>`` line between the entry and the file digests when set:
+    the same source at a different global unit-scale is a DIFFERENT version
+    (the cloud-generated USD differs) while the source bytes stay pristine.
+    ``None`` produces the exact pre-PR-12 recipe — every existing digest is
+    unchanged. Mirrored line-for-line by the validator's recompute
+    (``simulo.backend.validation.structural.compute_content_digest``).
+    """
+    lines = [_CONTENT_DIGEST_SCHEMA, kind, name, entry]
+    if scale is not None:
+        lines.append(f"scale:{canonical_scale_token(scale)}")
+    lines.extend(f"{item.path}:{item.sha256}" for item in sorted(manifest, key=lambda item: item.path))
+    return "sha256:" + sha256("\n".join(lines).encode("utf-8")).hexdigest()
+
+
+def _is_absolute_reference(ref: str) -> bool:
+    if ref.startswith(("/", "\\")):
+        return True
+    # A Windows drive path ("C:\..." / "C:/..."): one letter + colon.
+    return len(ref) >= 2 and ref[1] == ":" and ref[0].isalpha()
+
+
+def _refusal_for_reference(ref: str, containing: str) -> Optional[str]:
+    """The refusal-catalog judgment for one authored reference string.
+
+    Returns finished copy naming the authored reference and the file
+    containing it, or ``None`` when the reference is a well-formed relative
+    path (escaping and existence are judged separately, against the root).
+    """
+    if _is_absolute_reference(ref):
+        return (
+            f"Absolute path {ref!r} (in {containing}) — an asset package must be "
+            "self-contained, so every reference must be relative to the package root. "
+            "Make the reference relative and re-run."
+        )
+    match = _URI_SCHEME_RE.match(ref)
+    if match is None:
+        return None
+    scheme = match.group(1).lower()
+    if scheme == "nucleus":
+        return (
+            f"nucleus:// path {ref!r} (in {containing}) — Nucleus paths are an escape "
+            "hatch for self-hosted runtimes and are never valid inside a published "
+            "asset. Copy the file into the package and reference it relatively."
+        )
+    if scheme == "simulo":
+        return (
+            f"simulo:// path {ref!r} (in {containing}) — the legacy simulo:// alias is "
+            "removed; 'simulo/…' has exactly one meaning (the global catalog publisher). "
+            "Copy the file into the package and reference it relatively."
+        )
+    return (
+        f"URL {ref!r} (in {containing}) — an asset package must be self-contained, so "
+        "a reference can never point at a URL. Download the file into the package and "
+        "reference it relatively."
+    )
+
+
+def _resolve_relative_reference(
+    ref: str, *, base_dir: Path, root: Path, containing: str, refusals: list[str]
+) -> Optional[Path]:
+    """Resolve one relative authored reference against its layer's directory.
+
+    Appends symlink / escaping-root / missing-file refusals to *refusals*;
+    returns the resolved in-root path (or ``None`` for refused/pattern
+    references). Containment is REALPATH-based (:func:`_escapes_root_realpath`),
+    not a plain string prefix check — see the module docstring's "Symlink /
+    realpath containment" note.
+    """
+    if any(marker in ref for marker in _PATTERN_MARKERS):
+        # A UDIM/clip pattern cannot be stat-ed literally — judge escape by
+        # syntax only (its directory part must stay under the root).
+        candidate_dir = os.path.normpath(os.path.join(str(base_dir), os.path.dirname(ref) or "."))
+        if _escapes_root_realpath(Path(candidate_dir), root):
+            refusals.append(_escaping_refusal(ref, containing, root))
+        return None
+    candidate = Path(os.path.normpath(os.path.join(str(base_dir), ref)))
+    refusal = _reference_refusal(ref, containing, candidate, root)
+    if refusal is not None:
+        refusals.append(refusal)
+        return None
+    if not candidate.is_file():
+        refusals.append(
+            f"Missing dependency {ref!r} (referenced by {containing}) — the file does not "
+            f"exist inside the package root {root}. Add it to the package, or fix the "
+            "reference."
+        )
+        return None
+    return candidate
+
+
+def _escaping_refusal(ref: str, containing: str, root: Path) -> str:
+    return (
+        f"Reference {ref!r} (in {containing}) escapes the package root {root} — the CLI "
+        "only packages files beneath the root, never elsewhere on this machine. Move the "
+        "file under the root, or re-run with --root pointing at a directory that "
+        "contains everything the package needs."
+    )
+
+
+def _symlink_refusal(ref: str, containing: str) -> str:
+    return (
+        f"Reference {ref!r} (in {containing}) names a symlink — symlinks are never "
+        "packaged (their target could point anywhere on this machine, including outside "
+        "the package root). Replace it with a real file inside the package root and "
+        "re-run."
+    )
+
+
+def _escapes_root_realpath(candidate: Path, root: Path) -> bool:
+    """``True`` when *candidate*'s REALPATH does not stay under *root*'s own
+    realpath (security HIGH, PR-7 trio review — freeze "Packaging containment
+    is REALPATH-based"). ``os.path.realpath`` resolves every symlinked
+    directory in the whole chain from *candidate* up to the filesystem root,
+    not just its leaf component — closing the dir-symlink escape a plain
+    ``os.path.normpath`` + string ``commonpath`` check cannot see (a
+    symlinked directory earlier in the path can make the NOMINAL path read as
+    "inside root" while the REAL target is elsewhere). Any resolution failure
+    (broken symlink loop, permission error, cross-drive ``ValueError`` on
+    Windows) is treated conservatively as an escape — never silently allowed.
+    """
+    real_root = os.path.realpath(str(root))
+    try:
+        real_candidate = os.path.realpath(str(candidate))
+    except OSError:
+        return True
+    try:
+        return os.path.commonpath([real_root, real_candidate]) != real_root
+    except ValueError:  # different drives (Windows) — definitionally outside
+        return True
+
+
+def _reference_refusal(ref: str, containing: str, candidate: Path, root: Path) -> Optional[str]:
+    """The refusal for *candidate* if unsafe to read, else ``None``.
+
+    Two independent checks, in order: the candidate's LITERAL path must not
+    itself name a symlink (checked first via ``lstat`` — refused regardless
+    of where the symlink points, matching the tree-walk's blanket symlink
+    exclusion), then its realpath must stay contained under *root*
+    (:func:`_escapes_root_realpath`).
+    """
+    if candidate.is_symlink():
+        return _symlink_refusal(ref, containing)
+    if _escapes_root_realpath(candidate, root):
+        return _escaping_refusal(ref, containing, root)
+    return None
+
+
+def _raise_refusals(refusals: list[str]) -> None:
+    if not refusals:
+        return
+    shown = refusals[:20]
+    lines = "\n".join(f"  ✗ {refusal}" for refusal in shown)
+    more = f"\n  … and {len(refusals) - len(shown)} more." if len(refusals) > len(shown) else ""
+    raise AssetPackageError(f"This package cannot be published:\n{lines}{more}")
+
+
+# ---------------------------------------------------------------------------
+# File collection
+# ---------------------------------------------------------------------------
+
+
+def _collect_tree_files(root: Path) -> list[tuple[str, Path]]:
+    """Every packageable file under *root*: symlinks skipped (out-of-tree bytes
+    must never ride into an upload — the ``packaging.py`` precedent), dot-files
+    and ``__pycache__``/``*.pyc`` excluded, sorted by relative POSIX path."""
+    collected: list[tuple[str, Path]] = []
+    for dirpath, dirnames, filenames in os.walk(root):
+        here = Path(dirpath)
+        dirnames[:] = sorted(
+            d for d in dirnames if not d.startswith(".") and d != "__pycache__" and not (here / d).is_symlink()
+        )
+        for filename in sorted(filenames):
+            if filename.startswith(".") or filename.endswith(".pyc"):
+                continue
+            abspath = here / filename
+            if abspath.is_symlink():
+                continue
+            rel = PurePosixPath(abspath.relative_to(root).as_posix())
+            collected.append((str(rel), abspath))
+    collected.sort(key=lambda item: item[0])
+    return collected
+
+
+def _rel_to_root(path: Path, root: Path) -> str:
+    return path.relative_to(root).as_posix()
+
+
+def _relative_mesh_path(target_root_rel: str, entry_root_rel: str) -> str:
+    """*target_root_rel* (package-root-relative, POSIX) expressed relative to
+    *entry_root_rel*'s OWN DIRECTORY (also package-root-relative, POSIX) —
+    the form a rewritten ``<mesh filename=...>``/``<texture filename=...>``
+    attribute needs (PR-12 fix loop 2).
+
+    Pure string arithmetic over :class:`~pathlib.PurePosixPath` segments — no
+    filesystem access, no ``os.getcwd()`` dependency (unlike
+    ``posixpath.relpath``, which internally calls ``abspath()`` and would tie
+    the result to the process's working directory for no reason two
+    already-root-relative paths need one).
+
+    This is a DELIBERATE GENERALIZATION of "root-relative": when the entry
+    sits directly at the package root (the common single-folder-publish
+    case), ``entry_root_rel`` has no directory component and this collapses
+    to exactly ``target_root_rel`` unchanged. When the entry is nested (a
+    real ROS package layout — ``urdf/robot.urdf`` beside a sibling
+    ``meshes/`` directory), a literal root-relative rewrite would be WRONG
+    (a relative reference resolves against the FILE's own directory, the
+    universal URDF/mesh-tooling convention — and the one this module's own
+    pre-existing plain-relative-ref resolution, :func:`_resolve_relative_reference`
+    with ``base_dir=entry_abs.parent``, and the server-side containment
+    pre-check (``check_mesh_containment``'s ``base_dir=urdf_abs.parent``)
+    both already use); this function generalizes correctly to that case too,
+    so a plain pre-existing relative ref, a rewritten ``package://`` ref, and
+    both sides' resolution logic all agree on ONE base.
+    """
+    target_parts = PurePosixPath(target_root_rel).parts
+    entry_dir_parts = PurePosixPath(entry_root_rel).parent.parts
+    common = 0
+    for a, b in zip(entry_dir_parts, target_parts):
+        if a != b:
+            break
+        common += 1
+    up_levels = len(entry_dir_parts) - common
+    pieces = [".."] * up_levels + list(target_parts[common:])
+    return "/".join(pieces) if pieces else "."
+
+
+def _build_manifest(
+    files: list[tuple[str, Path]], *, overrides: Optional[dict[str, bytes]] = None
+) -> tuple[ManifestEntry, ...]:
+    """Manifest over the PACKAGED bytes for every (rel, abspath) pair.
+
+    ``overrides`` (PR-12 fix loop 2): a rel path present here is hashed from
+    the given IN-MEMORY bytes instead of the on-disk file at ``abspath`` —
+    the rewritten-URDF-entry seam (:func:`_inspect_urdf`); the manifest must
+    describe what actually gets UPLOADED, never the pre-rewrite original.
+    """
+    entries: list[ManifestEntry] = []
+    for rel, abspath in files:
+        _require_ntfs_clean_relpath(rel)
+        if overrides and rel in overrides:
+            data = overrides[rel]
+            digest, size = sha256(data).hexdigest(), len(data)
+        else:
+            digest, size = _hash_file(abspath)
+        entries.append(ManifestEntry(path=rel, size_bytes=size, sha256=digest))
+    entries.sort(key=lambda item: item.path)
+    return tuple(entries)
+
+
+def _enforce_caps(manifest: tuple[ManifestEntry, ...]) -> None:
+    if len(manifest) == 0:
+        raise AssetPackageError("The package contains no files — nothing to publish.")
+    if len(manifest) > MAX_ASSET_FILES:
+        raise AssetPackageError(
+            f"The package contains {len(manifest)} files — more than the {MAX_ASSET_FILES}-file "
+            "limit for one asset version. Trim the package (or split it) and re-run."
+        )
+    total = sum(item.size_bytes for item in manifest)
+    if total > MAX_ASSET_VERSION_BYTES:
+        raise AssetPackageError(
+            f"The package is {total} bytes — larger than the "
+            f"{MAX_ASSET_VERSION_BYTES}-byte ({MAX_ASSET_VERSION_BYTES // (1024 ** 3)} GiB) "
+            "per-version limit. Trim the package and re-run."
+        )
+
+
+# ---------------------------------------------------------------------------
+# USD inspection
+# ---------------------------------------------------------------------------
+
+
+def _inspect_usd(
+    *,
+    source: Path,
+    root: Path,
+    entry_arg: Optional[str],
+    corrected_command: Callable[[str], str],
+) -> tuple[str, bool, list[tuple[str, Path]], int, list[str]]:
+    """USD closure + entry detection. Returns
+    ``(entry_rel, auto_detected, files, reference_count, warnings)``."""
+    warnings: list[str] = []
+    refusals: list[str] = []
+
+    if source.is_dir():
+        files = _collect_tree_files(root)
+    else:
+        files = []  # single-file input: closure computed below
+
+    layer_files = (
+        [abspath for _, abspath in files if abspath.suffix.lower() in _USD_LAYER_SUFFIXES] if source.is_dir() else []
+    )
+
+    referenced: set[Path] = set()
+    reference_count = 0
+
+    def _parse_layer(layer: Path) -> list[Path]:
+        nonlocal reference_count
+        resolved_paths: list[Path] = []
+        containing = _rel_to_root(layer, root)
+        for ref in _extract_usd_references(layer):
+            refusal = _refusal_for_reference(ref, containing)
+            if refusal is not None:
+                refusals.append(refusal)
+                continue
+            resolved = _resolve_relative_reference(
+                ref, base_dir=layer.parent, root=root, containing=containing, refusals=refusals
+            )
+            if resolved is not None:
+                reference_count += 1
+                resolved_paths.append(resolved)
+        return resolved_paths
+
+    if source.is_dir():
+        for layer in layer_files:
+            referenced.update(_parse_layer(layer))
+        _raise_refusals(refusals)
+        entry_rel, auto = _pick_usd_entry(
+            root=root,
+            files=files,
+            referenced=referenced,
+            entry_arg=entry_arg,
+            corrected_command=corrected_command,
+        )
+    else:
+        # Single-file input: the file IS the entry; the package is its closure.
+        entry_abs = source
+        entry_rel = _rel_to_root(entry_abs, root)
+        auto = entry_arg is None
+        closure: dict[str, Path] = {entry_rel: entry_abs}
+        frontier = [entry_abs]
+        while frontier:
+            current = frontier.pop()
+            if current.suffix.lower() not in _USD_LAYER_SUFFIXES:
+                continue
+            for resolved in _parse_layer(current):
+                rel = _rel_to_root(resolved, root)
+                if rel not in closure:
+                    closure[rel] = resolved
+                    frontier.append(resolved)
+        _raise_refusals(refusals)
+        files = sorted(closure.items(), key=lambda item: item[0])
+
+    return entry_rel, auto, files, reference_count, warnings
+
+
+def _pick_usd_entry(
+    *,
+    root: Path,
+    files: list[tuple[str, Path]],
+    referenced: set[Path],
+    entry_arg: Optional[str],
+    corrected_command: Callable[[str], str],
+) -> tuple[str, bool]:
+    if entry_arg is not None:
+        entry_path = (root / entry_arg).resolve()
+        rel_names = {rel for rel, _ in files}
+        entry_rel = PurePosixPath(entry_arg).as_posix()
+        if entry_rel not in rel_names:
+            raise AssetUsageError(
+                f"--entry {entry_arg!r} does not name a file inside the package root {root}. "
+                f"Pick one of the package's USD files, e.g.:\n    {corrected_command('<entry.usd>')}"
+            )
+        if entry_path.suffix.lower() not in _USD_ALL_SUFFIXES:
+            raise AssetUsageError(f"--entry {entry_arg!r} is not a USD file (.usd/.usda/.usdc/.usdz).")
+        return entry_rel, False
+
+    referenced_rel = {_rel_to_root(path, root) for path in referenced}
+    candidates = [
+        rel for rel, abspath in files if abspath.suffix.lower() in _USD_LAYER_SUFFIXES and rel not in referenced_rel
+    ]
+    if len(candidates) == 1:
+        return candidates[0], True
+    if not candidates:
+        raise AssetPackageError(
+            "No entry USD could be detected: every USD layer in the package is referenced "
+            "by another (or the package contains no USD layers). Name the entry "
+            f"explicitly:\n    {corrected_command('<entry.usd>')}"
+        )
+    listing = "\n".join(f"    {candidate}" for candidate in candidates[:10])
+    return _raise_entry_ambiguity(candidates, listing, corrected_command)
+
+
+def _raise_entry_ambiguity(
+    candidates: list[str], listing: str, corrected_command: Callable[[str], str]
+) -> tuple[str, bool]:
+    raise AssetUsageError(
+        f"The package has {len(candidates)} top-level USD layers and the entry is "
+        f"ambiguous:\n{listing}\n"
+        f"Re-run naming the entry, e.g.:\n    {corrected_command(candidates[0])}"
+    )
+
+
+# ---------------------------------------------------------------------------
+# URDF inspection (no OPT-IN extra required — defusedxml + path math only,
+# both tiny always-installed base dependencies; contrast the USD path's
+# lazy usd-core extra above)
+# ---------------------------------------------------------------------------
+
+
+def _find_urdf_entry(
+    root: Path, source: Path, entry_arg: Optional[str], corrected_command: Callable[[str], str]
+) -> tuple[Path, bool]:
+    if entry_arg is not None:
+        entry_path = root / entry_arg
+        if not entry_path.is_file() or entry_path.suffix.lower() != ".urdf":
+            raise AssetUsageError(
+                f"--entry {entry_arg!r} does not name a .urdf file inside the package root " f"{root}."
+            )
+        return entry_path, False
+    if source.is_file():
+        return source, False
+    urdfs = sorted(root.rglob("*.urdf"))
+    if len(urdfs) == 1:
+        return urdfs[0], True
+    if not urdfs:
+        raise AssetPackageError(f"No .urdf file found under {root}.")
+    listing = "\n".join(f"    {_rel_to_root(u, root)}" for u in urdfs[:10])
+    raise AssetUsageError(
+        f"The package contains {len(urdfs)} URDF files and the entry is ambiguous:\n"
+        f"{listing}\nRe-run naming the entry, e.g.:\n"
+        f"    {corrected_command(_rel_to_root(urdfs[0], root))}"
+    )
+
+
+def _is_safe_contained_dir(path: Path, root: Path) -> bool:
+    """A candidate ``package://`` package DIRECTORY: real, not a symlink, and
+    realpath-contained under *root* (security HIGH — folds ``package://``
+    into the same containment discipline as every other reference)."""
+    return path.is_dir() and not path.is_symlink() and not _escapes_root_realpath(path, root)
+
+
+def _is_safe_contained_file(path: Path, root: Path) -> bool:
+    """The ``package://`` file-leaf twin of :func:`_is_safe_contained_dir`."""
+    return path.is_file() and not path.is_symlink() and not _escapes_root_realpath(path, root)
+
+
+def _resolve_package_uri(ref: str, *, root: Path, containing: str, refusals: list[str]) -> Optional[Path]:
+    """Resolve ``package://<pkg>/<rest>`` beneath the root.
+
+    Every candidate — the direct ``root/pkg/rest`` guess AND every ``pkg``-named
+    directory :meth:`Path.rglob` turns up — is realpath-contained and
+    symlink-free (:func:`_is_safe_contained_dir` / :func:`_is_safe_contained_file`)
+    before it is trusted; a symlinked ``pkg`` directory or a symlinked leaf file
+    is refused outright, never silently followed.
+
+    SECURITY NIT (fix loop 3): the RETURNED candidate is ``os.path.normpath``-
+    collapsed, mirroring :func:`_resolve_relative_reference` exactly (which
+    already does this). Without it, a valid ``package://pkg/../sibling/x.obj``
+    (realpath stays in-root — the containment check below is realpath-based
+    and already handles ``..`` correctly regardless) would return a Path whose
+    STRING form still embeds the literal ``..`` segment; that string becomes
+    the closure key / tar member name (via ``_rel_to_root`` + the fix-loop-2
+    mesh-path rewrite), and the server's ``safe_extract_archive`` rejects any
+    archive member NAME containing ``..`` outright (its own, correct, blanket
+    anti-traversal policy for untrusted archive input) — a confusing
+    server-side failure for a perfectly legitimate reference. Normalizing here
+    means the closure/tar/rewrite only ever see the collapsed, clean form.
+    """
+    body = ref[len("package://") :]
+    pkg, _, rest = body.partition("/")
+    if not pkg or not rest:
+        refusals.append(
+            f"Malformed package:// reference {ref!r} (in {containing}) — expected " "'package://<package>/<path>'."
+        )
+        return None
+    direct = Path(os.path.normpath(str(root / pkg / Path(rest))))
+    if direct.is_file() or direct.is_symlink():
+        refusal = _reference_refusal(ref, containing, direct, root)
+        if refusal is not None:
+            refusals.append(refusal)
+            return None
+        return direct
+    matches = sorted(
+        d for d in root.rglob(pkg) if _is_safe_contained_dir(d, root) and _is_safe_contained_file(d / Path(rest), root)
+    )
+    if len(matches) == 1:
+        return Path(os.path.normpath(str(matches[0] / Path(rest))))
+    if not matches:
+        refusals.append(
+            f"Cannot resolve {ref!r} (in {containing}): no directory named {pkg!r} "
+            f"containing {rest!r} exists under the package root {root}. Re-run with "
+            f"--root <directory that contains {pkg}/>."
+        )
+        return None
+    listing = ", ".join(_rel_to_root(m, root) for m in matches[:5])
+    refusals.append(
+        f"Ambiguous package:// reference {ref!r} (in {containing}): {len(matches)} "
+        f"directories named {pkg!r} under the root contain {rest!r} ({listing}). "
+        "Re-run with a --root that contains exactly one."
+    )
+    return None
+
+
+def _inspect_urdf(
+    *,
+    source: Path,
+    root: Path,
+    entry_arg: Optional[str],
+    corrected_command: Callable[[str], str],
+) -> tuple[str, bool, list[tuple[str, Path]], int, list[str], Optional[bytes]]:
+    """URDF closure: the URDF + every mesh/texture it references, resolved
+    beneath the root. Returns ``(entry_rel, auto, files, reference_count,
+    warnings, entry_override_bytes)``.
+
+    (``--scale`` was removed here — DEFERRED to Wave 3/PR-12 per the freeze's
+    "## PR-7 amendments": mesh-only client-side scaling was adjudicated wrong
+    on identity, server-side-conversion, and physics-completeness grounds; a
+    future ``options: {scale}`` field threads through the initiate body
+    unrewritten, source stays byte-for-byte pristine. Distinct from the
+    MESH-PATH rewrite below: that one is about self-containment, not scale,
+    and DOES rewrite — the two are orthogonal.)
+
+    **Mesh-path rewrite (PR-12 fix loop 2 — critic MAJOR).** ``package://``
+    resolution here previously only COLLECTED the referenced mesh into the
+    closure (so its bytes rode along in the archive) but never rewrote the
+    URDF text itself — a standard ROS URDF (``package://`` is the dominant
+    ROS mesh-reference convention) packaged fine, then failed the cloud's
+    server-side mesh-containment gate (``check_mesh_containment``, fix loop
+    1), which correctly refuses ``package://`` as unresolvable server-side.
+    URDF conversion that rejects the dominant ROS convention is a broken
+    headline feature — so every successfully-resolved ``<mesh>``/``<texture>``
+    ``filename`` attribute is now REWRITTEN, in place on the parsed tree, to
+    :func:`_relative_mesh_path`'s entry-directory-relative form (computed
+    from the SAME resolved closure path this function already collects) —
+    self-contained, and exactly what the server's containment gate and a
+    real URDF-consuming tool both resolve against. An unresolvable
+    ``package://`` (unknown package, no ``--root`` mapping) still FAILS HERE
+    at publish time via the existing refusal catalog (:func:`_raise_refusals`)
+    — naming the unresolved package — never a silent upload the server later
+    rejects.
+
+    The rewrite runs ONLY when at least one mesh/texture reference was
+    resolved (``reference_count > 0``); a URDF with none (primitives only)
+    packages its on-disk bytes byte-for-byte, unchanged — the common case's
+    behavior is untouched. When it does run, EVERY resolved reference is
+    rewritten uniformly (a plain already-relative ref included) rather than
+    special-casing "package:// only": one code path, and it guarantees the
+    uploaded URDF's mesh paths are always expressed in the ONE convention
+    both this module's own resolvers and the server side already share.
+
+    DETERMINISM: the tree is mutated via ``Element.set()`` on EXISTING
+    attributes only (never added/removed), so attribute insertion order —
+    preserved by ElementTree since Python 3.8 — never changes; re-parsing
+    and re-rewriting the SAME input, twice, produces byte-identical
+    serialized output (:func:`~xml.etree.ElementTree.tostring` over a
+    deterministic tree is itself deterministic). Comments and processing
+    instructions in the original file are NOT preserved through this path
+    (plain ``ElementTree`` parsing already drops them, before this change
+    existed) — an accepted, pre-existing property of ET-based inspection,
+    not a new regression.
+    """
+    warnings: list[str] = []
+    refusals: list[str] = []
+    entry_abs, auto = _find_urdf_entry(root, source, entry_arg, corrected_command)
+    entry_rel = _rel_to_root(entry_abs, root)
+
+    try:
+        tree = DefusedET.parse(entry_abs)
+    except ET.ParseError as exc:
+        raise AssetPackageError(f"{entry_rel} is not parseable as URDF XML: {exc}. Fix the file and re-run.") from exc
+    except DefusedXmlException as exc:
+        # SECURITY (fix loop 2 NIT): a hostile DOCTYPE/entity construct (XXE,
+        # billion-laughs) — a clear, fail-fast publish-time error, never a
+        # crash and never a silent parse of dangerous content. exc's own
+        # message names the forbidden construct (e.g. the entity name), not
+        # host filesystem details, so it is safe to surface verbatim.
+        raise AssetPackageError(
+            f"{entry_rel} uses a disallowed XML construct (a DOCTYPE or external/internal "
+            f"entity declaration): {exc}. Remove any <!DOCTYPE ...> or <!ENTITY ...> "
+            "declarations and re-run."
+        ) from exc
+
+    # ElementTree types getroot() as Optional because a tree can be constructed
+    # empty; a tree returned by a SUCCESSFUL parse always has a root, so this
+    # branch is unreachable in practice. It is a real check rather than a cast
+    # so that if it ever were reached, it surfaces as the same clean
+    # publish-time error as every other URDF problem — never an AttributeError.
+    root_element = tree.getroot()
+    if root_element is None:  # pragma: no cover - unreachable after a successful parse
+        raise AssetPackageError(
+            f"{entry_rel} is not parseable as URDF XML: it has no root element. Fix the file and re-run."
+        )
+
+    closure: dict[str, Path] = {entry_rel: entry_abs}
+    reference_count = 0
+    rewrites: list[tuple[ET.Element, str]] = []  # (element, new entry-relative filename)
+    for element in root_element.iter():
+        if element.tag not in ("mesh", "texture"):
+            continue
+        ref = element.get("filename")
+        if not ref:
+            continue
+        if ref.startswith("package://"):
+            resolved = _resolve_package_uri(ref, root=root, containing=entry_rel, refusals=refusals)
+        else:
+            refusal = _refusal_for_reference(ref, entry_rel)
+            if refusal is not None:
+                refusals.append(refusal)
+                continue
+            resolved = _resolve_relative_reference(
+                ref, base_dir=entry_abs.parent, root=root, containing=entry_rel, refusals=refusals
+            )
+        if resolved is not None:
+            reference_count += 1
+            target_rel = _rel_to_root(resolved, root)
+            closure[target_rel] = resolved
+            rewrites.append((element, _relative_mesh_path(target_rel, entry_rel)))
+    _raise_refusals(refusals)
+
+    entry_override_bytes: Optional[bytes] = None
+    if reference_count > 0:
+        for element, new_filename in rewrites:
+            element.set("filename", new_filename)
+        entry_override_bytes = ET.tostring(root_element, encoding="utf-8", xml_declaration=True)
+
+    files = sorted(closure.items(), key=lambda item: item[0])
+    return entry_rel, auto, files, reference_count, warnings, entry_override_bytes
+
+
+# ---------------------------------------------------------------------------
+# Public entry point + archive assembly
+# ---------------------------------------------------------------------------
+
+
+def detect_source_format(source: Path, entry_arg: Optional[str]) -> str:
+    """``"urdf"`` or ``"usd"`` from the input path (``--entry`` wins when given)."""
+    if entry_arg is not None:
+        return "urdf" if entry_arg.lower().endswith(".urdf") else "usd"
+    if source.is_file():
+        return "urdf" if source.suffix.lower() == ".urdf" else "usd"
+    has_urdf = any(source.rglob("*.urdf"))
+    has_usd = any(path for suffix in _USD_ALL_SUFFIXES for path in source.rglob(f"*{suffix}"))
+    if has_urdf and has_usd:
+        raise AssetUsageError(
+            f"{source} contains both URDF and USD files — name the entry explicitly with "
+            "--entry <file> so the source format is unambiguous."
+        )
+    if has_urdf:
+        return "urdf"
+    if has_usd:
+        return "usd"
+    raise AssetPackageError(
+        f"{source} contains no USD (.usd/.usda/.usdc/.usdz) or URDF (.urdf) files — " "nothing to publish."
+    )
+
+
+def inspect_package(
+    source: Path,
+    *,
+    kind: str,
+    name: str,
+    entry_arg: Optional[str] = None,
+    root_arg: Optional[Path] = None,
+    base_mode: Optional[str] = None,
+    scale: Optional[float] = None,
+    corrected_command: Optional[Callable[[str], str]] = None,
+) -> InspectedPackage:
+    """Inspect *source* (directory or file) into an :class:`InspectedPackage`.
+
+    Raises :class:`AssetPackageError` (refusal catalog / caps, exit 1) or
+    :class:`AssetUsageError` (needs a corrected command, exit 2).
+    ``corrected_command`` renders the copyable fix for entry ambiguity —
+    ``corrected_command("robot.usd")`` returns the full command line to print.
+    """
+    source = source.resolve()
+    if not source.exists():
+        raise AssetPackageError(f"{source} does not exist.")
+    root = root_arg.resolve() if root_arg is not None else (source if source.is_dir() else source.parent)
+    if not root.is_dir():
+        raise AssetUsageError(f"--root {root} is not a directory.")
+    if source != root and root not in source.parents:
+        raise AssetUsageError(f"{source} is not inside the package root {root} (--root).")
+    command_for = corrected_command or (lambda entry: f"--entry {entry}")
+
+    source_format = detect_source_format(source, entry_arg)
+    entry_override_bytes: Optional[bytes] = None
+    if source_format == "urdf":
+        entry_rel, auto, files, reference_count, warnings, entry_override_bytes = _inspect_urdf(
+            source=source,
+            root=root,
+            entry_arg=entry_arg,
+            corrected_command=command_for,
+        )
+    else:
+        entry_rel, auto, files, reference_count, warnings = _inspect_usd(
+            source=source, root=root, entry_arg=entry_arg, corrected_command=command_for
+        )
+
+    if scale is not None and source_format != "urdf":
+        raise AssetUsageError(
+            "--scale is a URDF conversion option (a global unit-scale applied by the cloud converter) "
+            "— it does not apply to USD sources. Author the correct metersPerUnit in your USD instead."
+        )
+
+    overrides = {entry_rel: entry_override_bytes} if entry_override_bytes is not None else None
+    manifest = _build_manifest(files, overrides=overrides)
+    _enforce_caps(manifest)
+    content_digest = compute_content_digest(kind=kind, name=name, entry=entry_rel, manifest=manifest, scale=scale)
+    return InspectedPackage(
+        source_format=source_format,
+        root=root,
+        entry=entry_rel,
+        entry_auto_detected=auto,
+        manifest=manifest,
+        content_digest=content_digest,
+        base_mode=base_mode,
+        reference_count=reference_count,
+        warnings=tuple(warnings),
+        scale=scale,
+        entry_override_bytes=entry_override_bytes,
+        _files=tuple(files),
+    )
+
+
+def build_archive(package: InspectedPackage, tar_path: Path) -> tuple[str, int]:
+    """Write the deterministic package tar; return ``(bare_sha256_hex, size)``.
+
+    Sorted members, zeroed mtime/uid/gid, mode 0644, POSIX arcnames — identical
+    trees produce identical bytes on every OS (the ``packaging.py`` recipe), so
+    the archive digest is as idempotent as the content digest.
+
+    **Last-line symlink/regular-file assertion (security HIGH, PR-7 trio
+    review).** Every source this function reads has already passed the
+    resolvers' realpath-containment + symlink checks — but this is the LAST
+    point before bytes leave the process, so it re-asserts the property one
+    more time, defensively, so a future resolver bug can never smuggle a
+    symlink, FIFO, device, or directory into the tar as if it were a file.
+
+    **Rewritten-entry seam (PR-12 fix loop 2).** When
+    ``package.entry_override_bytes`` is set, the entry's tar member is built
+    from THOSE bytes directly (``tarfile.addfile`` + ``io.BytesIO``) instead
+    of streaming ``source_path(entry)`` from disk — the entry is always a
+    small XML text file, never a multi-GB mesh, so holding it in memory once
+    is free; every OTHER manifest member still streams from disk exactly as
+    before.
+    """
+
+    def _reset(info: tarfile.TarInfo) -> tarfile.TarInfo:
+        info.mtime = 0
+        info.uid = info.gid = 0
+        info.uname = info.gname = ""
+        info.mode = 0o644
+        return info
+
+    tar_path.parent.mkdir(parents=True, exist_ok=True)
+    with tarfile.open(tar_path, "w") as tar:
+        for entry in package.manifest:
+            if package.entry_override_bytes is not None and entry.path == package.entry:
+                info = tarfile.TarInfo(name=entry.path)
+                info.size = len(package.entry_override_bytes)
+                tar.addfile(_reset(info), io.BytesIO(package.entry_override_bytes))
+                continue
+            source = package.source_path(entry.path)
+            if source.is_symlink() or not source.is_file():
+                raise AssetPackageError(
+                    f"Refusing to package {entry.path!r}: {source} is not a regular file "
+                    "(symlink, FIFO, device, or similar) — this should never happen; "
+                    "please report this as a bug."
+                )
+            # Streams from disk — a multi-GB mesh never lands in memory.
+            tar.add(source, arcname=entry.path, filter=_reset)
+    digest, size = _hash_file(tar_path)
+    return digest, size