feat(crates): deterministic crate resolver

Add app/crates/layout.py (separate crate/result key prefixes) and resolver.py. `resolve_crate()` locates a crate by direct stat checks on "canonical keys" instead of prefix-listing.
- Distinguishes zip vs directory,
- confirms ro-crate-metadata.json for directories, and
- reports "AmbiguousCrate" / "CrateNotFound"
- Fixes sibling false-match, .zip-in-id, and some missing-metadata gaps.
Closes #175

Author: alexhambley

app/crates/layout.py

@@ -0,0 +1,40 @@
+"""Canonical object-key layout for crates and their validation results.
+
+A single place defines where crates and results live in the bucket. Crates and
+results use *separate* prefixes so a result object can never collide with, or be
+mistaken for, a crate object.
+
+Layout (given a ``crate_prefix`` and ``results_prefix``):
+
+- Crate (zip):       ``{crate_prefix}/{id}.zip``
+- Crate (directory): ``{crate_prefix}/{id}/`` containing ``ro-crate-metadata.json``
+- Validation result: ``{results_prefix}/{id}.json``
+"""
+
+METADATA_FILENAME = "ro-crate-metadata.json"
+
+
+def _join(prefix: str, suffix: str) -> str:
+    """Join an optional prefix and a suffix with a single separator."""
+    prefix = prefix.strip("/")
+    return f"{prefix}/{suffix}" if prefix else suffix
+
+
+def crate_zip_key(crate_prefix: str, crate_id: str) -> str:
+    """Object key for a crate stored as a zip archive."""
+    return _join(crate_prefix, f"{crate_id}.zip")
+
+
+def crate_dir_prefix(crate_prefix: str, crate_id: str) -> str:
+    """Key prefix (with trailing slash) for a crate stored as a directory."""
+    return _join(crate_prefix, f"{crate_id}/")
+
+
+def crate_metadata_key(crate_prefix: str, crate_id: str) -> str:
+    """Object key for the metadata file inside a directory-style crate."""
+    return _join(crate_prefix, f"{crate_id}/{METADATA_FILENAME}")
+
+
+def result_key(results_prefix: str, crate_id: str) -> str:
+    """Object key for a crate's stored validation result."""
+    return _join(results_prefix, f"{crate_id}.json")

app/crates/resolver.py

@@ -0,0 +1,76 @@
+"""Deterministic crate resolution over a StorageBackend.
+
+Resolution is by direct existence checks on canonical keys, never by listing a
+prefix and substring-matching. This removes the previous fragilities: it cannot
+false-match a sibling prefix, it confirms a directory crate actually contains
+``ro-crate-metadata.json``, and it treats the ID as opaque (so a ``.zip`` in the
+ID is harmless). Ambiguity and absence are reported explicitly.
+"""
+
+from dataclasses import dataclass
+
+from app.crates.ids import validate_crate_id
+from app.crates.layout import crate_zip_key, crate_dir_prefix, crate_metadata_key
+from app.storage.base import StorageBackend
+from app.storage.errors import ObjectNotFound
+
+
+@dataclass(frozen=True)
+class ResolvedCrate:
+    """A crate located in storage.
+
+    ``key`` is the zip object key for a zip crate, or the directory prefix
+    (with trailing slash) for a directory crate.
+    """
+
+    crate_id: str
+    key: str
+    is_zip: bool
+
+
+class CrateNotFound(Exception):
+    """Raised when no crate exists for the given ID."""
+
+
+class AmbiguousCrate(Exception):
+    """Raised when both a zip and a directory crate exist for the same ID."""
+
+
+def _object_exists(storage: StorageBackend, key: str) -> bool:
+    try:
+        storage.stat(key)
+        return True
+    except ObjectNotFound:
+        return False
+
+
+def resolve_crate(
+    storage: StorageBackend, crate_id: str, crate_prefix: str
+) -> ResolvedCrate:
+    """Resolve ``crate_id`` to a concrete crate object.
+
+    :raises InvalidCrateId: If the ID is malformed.
+    :raises AmbiguousCrate: If both zip and directory forms exist.
+    :raises CrateNotFound: If neither form exists.
+    """
+    validate_crate_id(crate_id)
+
+    zip_key = crate_zip_key(crate_prefix, crate_id)
+    metadata_key = crate_metadata_key(crate_prefix, crate_id)
+
+    zip_exists = _object_exists(storage, zip_key)
+    directory_exists = _object_exists(storage, metadata_key)
+
+    if zip_exists and directory_exists:
+        raise AmbiguousCrate(
+            f"Crate {crate_id!r} exists as both a zip and a directory; refusing to guess."
+        )
+    if zip_exists:
+        return ResolvedCrate(crate_id=crate_id, key=zip_key, is_zip=True)
+    if directory_exists:
+        return ResolvedCrate(
+            crate_id=crate_id,
+            key=crate_dir_prefix(crate_prefix, crate_id),
+            is_zip=False,
+        )
+    raise CrateNotFound(f"No crate found for ID {crate_id!r}")

tests/test_crate_layout.py

@@ -0,0 +1,33 @@
+"""Tests for canonical crate/result key construction."""
+
+import pytest
+
+from app.crates.layout import (
+    crate_zip_key,
+    crate_dir_prefix,
+    crate_metadata_key,
+    result_key,
+)
+
+
+def test_crate_zip_key_under_prefix():
+    assert crate_zip_key("crates", "foo") == "crates/foo.zip"
+
+
+def test_crate_dir_prefix_under_prefix():
+    assert crate_dir_prefix("crates", "foo") == "crates/foo/"
+
+
+def test_crate_metadata_key_under_prefix():
+    assert crate_metadata_key("crates", "foo") == "crates/foo/ro-crate-metadata.json"
+
+
+def test_result_key_uses_separate_results_prefix():
+    assert result_key("validation-results", "foo") == "validation-results/foo.json"
+
+
+@pytest.mark.parametrize("prefix", ["", "crates/"])
+def test_prefix_edge_cases_are_normalised(prefix):
+    """An empty prefix maps to the bucket root; a trailing slash is not doubled."""
+    expected = "foo.zip" if prefix == "" else "crates/foo.zip"
+    assert crate_zip_key(prefix, "foo") == expected

tests/test_crate_resolver.py

@@ -0,0 +1,92 @@
+"""Tests for deterministic crate resolution over a StorageBackend."""
+
+import pytest
+
+from app.crates.ids import InvalidCrateId
+from app.crates.resolver import (
+    resolve_crate,
+    ResolvedCrate,
+    CrateNotFound,
+    AmbiguousCrate,
+)
+from app.storage.memory import InMemoryStorage
+
+PREFIX = "crates"
+
+
+@pytest.fixture
+def storage() -> InMemoryStorage:
+    return InMemoryStorage()
+
+
+def test_resolves_zip_crate(storage):
+    storage.put_bytes("crates/foo.zip", b"PK...")
+
+    resolved = resolve_crate(storage, "foo", PREFIX)
+
+    assert isinstance(resolved, ResolvedCrate)
+    assert resolved.crate_id == "foo"
+    assert resolved.is_zip is True
+    assert resolved.key == "crates/foo.zip"
+
+
+def test_resolves_directory_crate_with_metadata(storage):
+    storage.put_bytes("crates/foo/ro-crate-metadata.json", b"{}")
+    storage.put_bytes("crates/foo/data.csv", b"x")
+
+    resolved = resolve_crate(storage, "foo", PREFIX)
+
+    assert resolved.is_zip is False
+    assert resolved.key == "crates/foo/"
+
+
+def test_directory_without_metadata_is_not_a_crate(storage):
+    """A directory lacking ro-crate-metadata.json must not resolve (old TODO)."""
+    storage.put_bytes("crates/foo/data.csv", b"x")
+
+    with pytest.raises(CrateNotFound):
+        resolve_crate(storage, "foo", PREFIX)
+
+
+def test_ambiguous_when_both_zip_and_directory_exist(storage):
+    storage.put_bytes("crates/foo.zip", b"PK...")
+    storage.put_bytes("crates/foo/ro-crate-metadata.json", b"{}")
+
+    with pytest.raises(AmbiguousCrate):
+        resolve_crate(storage, "foo", PREFIX)
+
+
+def test_missing_crate_raises_not_found(storage):
+    with pytest.raises(CrateNotFound):
+        resolve_crate(storage, "absent", PREFIX)
+
+
+def test_sibling_prefix_does_not_false_match(storage):
+    """Resolving 'foo' must not match 'foobar' (old prefix-substring bug)."""
+    storage.put_bytes("crates/foobar.zip", b"PK...")
+
+    with pytest.raises(CrateNotFound):
+        resolve_crate(storage, "foo", PREFIX)
+
+
+def test_zip_suffix_in_id_resolves_as_directory(storage):
+    """An ID containing '.zip' is opaque: a directory crate named 'data.zip' resolves."""
+    storage.put_bytes("crates/data.zip/ro-crate-metadata.json", b"{}")
+
+    resolved = resolve_crate(storage, "data.zip", PREFIX)
+
+    assert resolved.is_zip is False
+    assert resolved.key == "crates/data.zip/"
+
+
+def test_invalid_id_propagates(storage):
+    with pytest.raises(InvalidCrateId):
+        resolve_crate(storage, "../etc", PREFIX)
+
+
+def test_result_object_does_not_satisfy_crate_resolution(storage):
+    """A stored result under a separate prefix never counts as the crate itself."""
+    storage.put_bytes("validation-results/foo.json", b"{}")
+
+    with pytest.raises(CrateNotFound):
+        resolve_crate(storage, "foo", PREFIX)