fix: resolve exact artifact versions

Author: nclsmitchell

README.md

@@ -29,7 +29,9 @@ Run `uvx foretop-lading scan --help` for every option.
 - Optional artifacts from the local Hugging Face cache or an existing CycloneDX 1.6 JSON SBOM.
 - Attribution, redistribution, acceptable-use, field-of-use, and share-alike obligations.
 
-Unresolved licences remain `unknown`; they are never treated as permissive.
+When discovery supplies a package version or Hugging Face revision, Lading resolves metadata
+for that exact release rather than the registry's latest state. Unresolved licences remain
+`unknown`; they are never treated as permissive.
 
 ## Output and CI gating
 
@@ -41,7 +43,7 @@ failed, while `2` means the scan itself failed. Warnings alone never fail the co
 ## GitHub Action
 
 ```yaml
-- uses: foretop-dev/lading@v0.1.0
+- uses: foretop-dev/lading@v0.1.1
   with:
     policy: permissive-only
 ```

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "foretop-lading"
-version = "0.1.0"
+version = "0.1.1"
 description = "Traces licence obligations across code dependencies and model weights as one dependency graph — resolves each artifact's licence via Hugging Face / PyPI and prints a flat, honest table (unknown rather than guessed)."
 readme = "README.md"
 requires-python = ">=3.12"

src/lading/__init__.py

@@ -1 +1 @@
-__version__ = "0.1.0"
+__version__ = "0.1.1"

src/lading/cli.py

@@ -94,24 +94,40 @@ def _curate_all(
     package_overrides: dict[str, PackageOverride],
 ) -> tuple[tuple[DiscoveredArtifact, CuratedResolution], ...]:
     """Curates each discovered artifact, deduplicated in-memory within this one run — the
-    same model id or package name referenced from two call sites is only resolved once. No
-    persistent cache yet (specs/lading.md §6's 7-day cache-expiry rule is real but not this
-    slice's job — a documented gap, not a silent one)."""
-    cache: dict[tuple[ArtifactKind, str], CuratedResolution] = {}
+    same model id or package name at the same version/revision, referenced from two call sites,
+    is resolved once. Two versions of one canonical id remain separate because registry
+    metadata and its licence can differ. No persistent cache yet (specs/lading.md §6's 7-day
+    cache-expiry rule is real but not this slice's job — a documented gap, not a silent one)."""
+    cache: dict[tuple[ArtifactKind, str, str | None], CuratedResolution] = {}
     rows: list[tuple[DiscoveredArtifact, CuratedResolution]] = []
     for artifact in artifacts:
-        key = (artifact.kind, artifact.identifier)
+        key = (artifact.kind, artifact.identifier, artifact.version)
         if key not in cache:
             # ADAPTER shares MODEL's own resolution path: a vendored adapter's identifier is
             # a local directory path, not a real HF id, so curate_model's own id-shape check
             # already resolves it honestly to unresolved — no separate adapter resolver needed.
             if artifact.kind is ArtifactKind.MODEL or artifact.kind is ArtifactKind.ADAPTER:
-                cache[key] = curate_model(client, artifact.identifier, overrides, licence_index)
+                cache[key] = curate_model(
+                    client,
+                    artifact.identifier,
+                    overrides,
+                    licence_index,
+                    revision=artifact.version,
+                )
             elif artifact.kind is ArtifactKind.DATASET:
-                cache[key] = curate_dataset(client, artifact.identifier, licence_index)
+                cache[key] = curate_dataset(
+                    client,
+                    artifact.identifier,
+                    licence_index,
+                    revision=artifact.version,
+                )
             else:
                 cache[key] = curate_package(
-                    client, artifact.identifier, licence_index, package_overrides
+                    client,
+                    artifact.identifier,
+                    licence_index,
+                    package_overrides,
+                    version=artifact.version,
                 )
         rows.append((artifact, cache[key]))
     return tuple(rows)

src/lading/curate.py

@@ -59,6 +59,8 @@ def curate_model(
     model_id: str,
     overrides: dict[str, ModelOverride],
     licence_index: dict[str, LicenceEntry],
+    *,
+    revision: str | None = None,
 ) -> CuratedResolution:
     """DEC-02's hybrid: a curated override (real research done once, ahead of time) always
     wins and never touches the network — resolve_model is only called when no override
@@ -68,7 +70,7 @@ def curate_model(
     if override is not None:
         return _decorate(override.licence_id, override.source_url, licence_index)
 
-    resolution = resolve_model(client, model_id)
+    resolution = resolve_model(client, model_id, revision=revision)
     if not resolution.resolved or resolution.licence is None:
         return _UNRESOLVED
     return _decorate(resolution.licence, resolution.source_url, licence_index)
@@ -79,6 +81,8 @@ def curate_package(
     name: str,
     licence_index: dict[str, LicenceEntry],
     package_overrides: dict[str, PackageOverride] | None = None,
+    *,
+    version: str | None = None,
 ) -> CuratedResolution:
     """Same DEC-02 hybrid `curate_model` uses: a curated override always wins and never
     touches the network. Package overrides matter more here than model overrides do for
@@ -93,19 +97,23 @@ def curate_package(
     if override is not None:
         return _decorate(override.licence_id, override.source_url, licence_index)
 
-    resolution = resolve_package(client, name)
+    resolution = resolve_package(client, name, version=version)
     if not resolution.resolved or resolution.licence is None:
         return _UNRESOLVED
     return _decorate(resolution.licence, resolution.source_url, licence_index)
 
 
 def curate_dataset(
-    client: httpx.Client, dataset_id: str, licence_index: dict[str, LicenceEntry]
+    client: httpx.Client,
+    dataset_id: str,
+    licence_index: dict[str, LicenceEntry],
+    *,
+    revision: str | None = None,
 ) -> CuratedResolution:
     """No override layer for datasets this slice — data/model_overrides.yaml stays
     model-only; a real dataset override KB is future work, not named in Slice 3a's own
     scope."""
-    resolution = resolve_dataset(client, dataset_id)
+    resolution = resolve_dataset(client, dataset_id, revision=revision)
     if not resolution.resolved or resolution.licence is None:
         return _UNRESOLVED
     return _decorate(resolution.licence, resolution.source_url, licence_index)

src/lading/resolve.py

@@ -1,5 +1,6 @@
 import re
 from typing import Any
+from urllib.parse import quote
 
 import httpx
 
@@ -12,10 +13,17 @@
 # could reach an unintended API path.
 _MODEL_ID_RE = re.compile(r"^[\w][\w.-]*/[\w][\w.-]*$")
 _PACKAGE_NAME_RE = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9._-]*[A-Za-z0-9])?$")
+_PACKAGE_VERSION_RE = re.compile(r"^[A-Za-z0-9](?:[A-Za-z0-9.!+_-]*[A-Za-z0-9])?$")
 
 _UNRESOLVED = Resolution(licence=None, resolved=False, source_url=None)
 
 
+def _valid_hf_revision(revision: str) -> bool:
+    if any(ord(character) < 32 or ord(character) == 127 for character in revision):
+        return False
+    return all(segment not in {"", ".", ".."} for segment in revision.split("/"))
+
+
 def _extract_hf_licence(data: dict[str, Any]) -> str | None:
     """Verified live this session against real HF API responses: `cardData.license` can be a
     plain string (e.g. a gated Llama model's own non-SPDX slug, "llama3.2") or a list of
@@ -35,7 +43,13 @@ def _extract_hf_licence(data: dict[str, Any]) -> str | None:
     return None
 
 
-def _resolve_hf_repo(client: httpx.Client, repo_id: str, *, api_segment: str) -> Resolution:
+def _resolve_hf_repo(
+    client: httpx.Client,
+    repo_id: str,
+    *,
+    api_segment: str,
+    revision: str | None = None,
+) -> Resolution:
     """Shared by resolve_model/resolve_dataset — both endpoints share the exact same
     `cardData.license` shape (confirmed live this session against real datasets too:
     openai/gsm8k, Salesforce/wikitext), so this is genuinely identical logic, not merely
@@ -44,6 +58,13 @@ def _resolve_hf_repo(client: httpx.Client, repo_id: str, *, api_segment: str) ->
         return _UNRESOLVED
 
     url = f"https://huggingface.co/api/{api_segment}/{repo_id}"
+    if revision is not None:
+        if not _valid_hf_revision(revision):
+            return _UNRESOLVED
+        # This is the exact revision route and quoting rule used by the current official
+        # huggingface_hub HfApi model_info/dataset_info clients. A slash in a branch such as
+        # refs/pr/7 is one revision value, never additional URL structure.
+        url = f"{url}/revision/{quote(revision, safe='')}"
     try:
         response = client.get(url)
     except httpx.HTTPError:
@@ -62,19 +83,29 @@ def _resolve_hf_repo(client: httpx.Client, repo_id: str, *, api_segment: str) ->
     return Resolution(licence=licence, resolved=True, source_url=url)
 
 
-def resolve_model(client: httpx.Client, model_id: str) -> Resolution:
-    return _resolve_hf_repo(client, model_id, api_segment="models")
+def resolve_model(
+    client: httpx.Client, model_id: str, *, revision: str | None = None
+) -> Resolution:
+    return _resolve_hf_repo(client, model_id, api_segment="models", revision=revision)
 
 
-def resolve_dataset(client: httpx.Client, dataset_id: str) -> Resolution:
-    return _resolve_hf_repo(client, dataset_id, api_segment="datasets")
+def resolve_dataset(
+    client: httpx.Client, dataset_id: str, *, revision: str | None = None
+) -> Resolution:
+    return _resolve_hf_repo(client, dataset_id, api_segment="datasets", revision=revision)
 
 
-def resolve_package(client: httpx.Client, name: str) -> Resolution:
+def resolve_package(client: httpx.Client, name: str, *, version: str | None = None) -> Resolution:
     if not _PACKAGE_NAME_RE.match(name):
         return _UNRESOLVED
 
     url = f"https://pypi.org/pypi/{name}/json"
+    if version is not None:
+        if not _PACKAGE_VERSION_RE.match(version):
+            return _UNRESOLVED
+        # PyPI documents this release-specific route separately from the project route,
+        # whose info block describes only the latest release.
+        url = f"https://pypi.org/pypi/{name}/{quote(version, safe='')}/json"
     try:
         response = client.get(url)
     except httpx.HTTPError:

tests/test_acceptance.py

@@ -0,0 +1,63 @@
+import httpx
+
+from lading.cli import _curate_all
+from lading.models import ArtifactKind, DiscoveredArtifact
+
+
+def test_versions_and_revisions_reach_their_own_registry_metadata() -> None:
+    artifacts = (
+        DiscoveredArtifact(
+            kind=ArtifactKind.PYTHON_PACKAGE,
+            identifier="demo-package",
+            version="1.0.0",
+            evidence="pkg:pypi/demo-package@1.0.0",
+        ),
+        DiscoveredArtifact(
+            kind=ArtifactKind.PYTHON_PACKAGE,
+            identifier="demo-package",
+            version="2.0.0",
+            evidence="pkg:pypi/demo-package@2.0.0",
+        ),
+        DiscoveredArtifact(
+            kind=ArtifactKind.MODEL,
+            identifier="org/model",
+            version="refs/pr/7",
+            evidence="pkg:huggingface/org/model@refs%2Fpr%2F7",
+        ),
+        DiscoveredArtifact(
+            kind=ArtifactKind.MODEL,
+            identifier="org/model",
+            version="abcdef123456",
+            evidence="pkg:huggingface/org/model@abcdef123456",
+        ),
+        DiscoveredArtifact(
+            kind=ArtifactKind.DATASET,
+            identifier="org/dataset",
+            version="dataset-revision",
+            evidence="dataset fixture",
+        ),
+    )
+    licences_by_path = {
+        "/pypi/demo-package/1.0.0/json": "licence-package-v1",
+        "/pypi/demo-package/2.0.0/json": "licence-package-v2",
+        "/api/models/org/model/revision/refs%2Fpr%2F7": "licence-model-pr",
+        "/api/models/org/model/revision/abcdef123456": "licence-model-sha",
+        "/api/datasets/org/dataset/revision/dataset-revision": "licence-dataset-revision",
+    }
+    requested_paths: list[str] = []
+
+    def handler(request: httpx.Request) -> httpx.Response:
+        path = request.url.raw_path.decode("ascii")
+        requested_paths.append(path)
+        licence = licences_by_path.get(path, "wrong-latest-metadata")
+        if request.url.host == "pypi.org":
+            return httpx.Response(200, json={"info": {"license": licence}})
+        return httpx.Response(200, json={"cardData": {"license": licence}})
+
+    with httpx.Client(transport=httpx.MockTransport(handler)) as client:
+        curated = _curate_all(client, artifacts, {}, {}, {})
+
+    assert [resolution.licence for _artifact, resolution in curated] == list(
+        licences_by_path.values()
+    )
+    assert requested_paths == list(licences_by_path)

tests/unit/test_resolve.py

@@ -80,6 +80,17 @@ def handler(request: httpx.Request) -> httpx.Response:
     assert resolution.source_url is None
 
 
+def test_resolve_model_rejects_a_path_traversal_revision_before_building_a_url() -> None:
+    def handler(request: httpx.Request) -> httpx.Response:
+        raise AssertionError("must never reach the transport for a malformed revision")
+
+    with make_client(handler) as client:
+        resolution = resolve_model(client, "org/model", revision="../../main")
+
+    assert resolution.resolved is False
+    assert resolution.source_url is None
+
+
 def test_resolve_package_reads_pypi_license(monkeypatch: pytest.MonkeyPatch) -> None:
     def handler(request: httpx.Request) -> httpx.Response:
         assert request.url.path == "/pypi/requests/json"