code-sandboxes 1.9.18__tar.gz → 1.9.20__tar.gz

{code_sandboxes-1.9.18 → code_sandboxes-1.9.20}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: code_sandboxes
-Version: 1.9.18
+Version: 1.9.20
 Project-URL: Home, https://github.com/datalayer/code-sandboxes
 Author-email: Datalayer <info@datalayer.io>
 License: BSD 3-Clause License

{code_sandboxes-1.9.18 → code_sandboxes-1.9.20}/code_sandboxes/__version__.py

@@ -3,4 +3,4 @@
 
 """Code Sandboxes."""
 
-__version__ = "1.9.18"
+__version__ = "1.9.20"

{code_sandboxes-1.9.18 → code_sandboxes-1.9.20}/code_sandboxes/environments/adapters/daytona.py

@@ -179,7 +179,12 @@ class Builder(ManagedBuilder):
     title = "Daytona"
     #: A `packages` list and, for conda (E3-02), an `environment.yml`
     #: dependency file installed with `micromamba`.
-    build_sources = ("packages", "dependencyFile")
+    build_sources = ("packages", "dependencyFile", "dockerfile")
+    #: None beyond the contract's own (E3-03): `Image.from_dockerfile` keeps
+    #: the Dockerfile text as it is and Daytona builds it on a real Docker
+    #: builder, so the grammar it accepts is Docker's. Checked in the SDK on
+    #: 2026-09-17.
+    forbidden_instructions = ()
     dependency_formats = ("conda",)
     #: Daytona runs GPUs, on its own hardware and the owner's account (E2-17).
     #: This builder does not build one yet: see `_own_findings`.
@@ -419,6 +424,11 @@ class Builder(ManagedBuilder):
                     self._log(line)
 
                 resources = self._resources(sdk, request.size_class)
+                # A snapshot is region-scoped, and the region that scopes it is
+                # Daytona's, not this platform's. `validate` already refuses
+                # more than one, so the first is the only one.
+                declared = list(request.environment.spec.compatibility.regions)
+                region = declared[0] if declared else None
                 try:
                     snapshot = client.snapshot.create(
                         sdk.CreateSnapshotParams(
@@ -426,7 +436,15 @@ class Builder(ManagedBuilder):
                             image=image,
                             resources=resources,
                             entrypoint=_CONTRACT_ENTRYPOINT,
-                            region_id=request.region,
+                            # Only a region Daytona knows. `request.region` is
+                            # *Datalayer's* — `r1` — and sending it answered
+                            # "Region not found" on the first real Daytona
+                            # build (2026-09-17). The owner names a Daytona
+                            # region in `compatibility.regions`; with none,
+                            # the field is left out and the account's own
+                            # default decides, which is what every snapshot
+                            # in the owner's account already has.
+                            **({"region_id": region} if region else {}),
                         ),
                         on_logs=on_logs,
                         timeout=self.max_build_seconds,

{code_sandboxes-1.9.18 → code_sandboxes-1.9.20}/code_sandboxes/environments/adapters/e2b.py

@@ -199,7 +199,24 @@ class Builder(ManagedBuilder):
     title = "E2B"
     #: A `packages` list and, for conda (E3-02), an `environment.yml`
     #: dependency file installed with `micromamba`.
-    build_sources = ("packages", "dependencyFile")
+    build_sources = ("packages", "dependencyFile", "dockerfile")
+    #: What E2B's own Dockerfile parser does not handle (E3-03). Read from the
+    #: SDK on 2026-09-17: `e2b.template.dockerfile_parser` branches on FROM,
+    #: RUN, COPY, ADD, WORKDIR, USER, ENV, ARG, CMD and ENTRYPOINT, and for
+    #: anything else **prints `Unsupported instruction` and carries on**. So a
+    #: template built from a Dockerfile naming one of these comes back without
+    #: it and reports success — which is exactly what a capability report
+    #: exists to prevent.
+    forbidden_instructions = (
+        "VOLUME",
+        "EXPOSE",
+        "HEALTHCHECK",
+        "SHELL",
+        "ONBUILD",
+        "STOPSIGNAL",
+        "LABEL",
+        "MAINTAINER",
+    )
     dependency_formats = ("conda",)
     #: Firecracker microVMs: no GPU passthrough.
     gpu = False

{code_sandboxes-1.9.18 → code_sandboxes-1.9.20}/code_sandboxes/environments/adapters/managed.py

@@ -73,7 +73,11 @@ class ManagedBuilder:
     #: built for a managed variant yet (E3-01), so it is not listed here.
     dependency_formats: tuple[str, ...] = ()
     package_managers: tuple[str, ...] = ("uv", "pip")
-    #: Dockerfile instructions its own builder does not implement (§6).
+    #: Dockerfile instructions its own builder does not implement (§6, E3-03).
+    #: Checked against a `dockerfile`-sourced spec at `validate`, before
+    #: anything is queued — the point being to refuse an instruction a variant
+    #: would otherwise drop, rather than hand back an image quietly missing
+    #: whatever it asked for.
     forbidden_instructions: tuple[str, ...] = ()
     #: Where its artifacts live; empty when the variant is regionless.
     regions: tuple[str, ...] = ()
@@ -128,6 +132,8 @@ class ManagedBuilder:
             )
         elif spec.build.source == "dependencyFile":
             findings.extend(self._dependency_file_findings(spec))
+        elif spec.build.source == "dockerfile":
+            findings.extend(self._dockerfile_findings(spec))
         if spec.packages.python.manager not in self.package_managers:
             findings.append(
                 CapabilityFinding(
@@ -269,6 +275,36 @@ class ManagedBuilder:
 
     # -- helpers for the subclasses -------------------------------------------
 
+    def _dockerfile_findings(self, spec: Any) -> list[CapabilityFinding]:
+        """Every instruction in the spec's Dockerfile this variant would not honour.
+
+        The contract's own refusals are `spec.py`'s to make and apply to every
+        variant alike; this is the narrower question of what *this* builder
+        does with a Dockerfile it accepts. Each is named with its line, since
+        a Dockerfile is somebody's file.
+        """
+        if not self.forbidden_instructions:
+            return []
+        dockerfile = getattr(spec.build, "dockerfile", None)
+        content = getattr(dockerfile, "content", "") or ""
+        if not content.strip():
+            return []
+        from ..contract import parse_dockerfile
+
+        refused = set(self.forbidden_instructions)
+        return [
+            CapabilityFinding(
+                code=CAPABILITY_UNSUPPORTED.code,
+                message=(
+                    f"line {instruction.line}: {self.title} does not implement "
+                    f"`{instruction.keyword}`"
+                ),
+                field="spec.build.dockerfile.content",
+            )
+            for instruction in parse_dockerfile(content)
+            if instruction.keyword in refused
+        ]
+
     @staticmethod
     def _spec_finding(message: str, field: str) -> CapabilityFinding:
         return CapabilityFinding(code=SPEC_INVALID.code, message=message, field=field)

{code_sandboxes-1.9.18 → code_sandboxes-1.9.20}/code_sandboxes/environments/adapters/modal.py

@@ -230,8 +230,7 @@ def _install_packages(image: Any, lock_text: str) -> Any:
         # Packages install as root: every Modal build step already runs as
         # root regardless of any `USER` line (see the module docstring), so
         # this is stating what is already true rather than asking for it.
-        "uv pip sync --system --require-hashes "
-        f"--find-links {WHEELHOUSE_IMAGE_PATH} {_LOCK_PATH}",
+        f"uv pip sync --system --require-hashes --find-links {WHEELHOUSE_IMAGE_PATH} {_LOCK_PATH}",
     )
 
 
@@ -245,6 +244,40 @@ def _post_install(
     return image
 
 
+def _intermediates_of(built: Any) -> tuple[str, ...]:
+    """Every layer under a built image, by id, deepest first (E2-05, E2-09).
+
+    Each chained builder call leaves an image of its own, and deleting the
+    artifact does not delete them. Modal offers no call that lists an
+    account's images, so an intermediate nobody wrote down at build time can
+    never be found again — which is why this is recorded rather than
+    discovered. Confirmed live on 2026-09-17: a three-call chain built through
+    `Image.build` hydrates an `object_id` on every image in `deps()`, not only
+    on the last.
+
+    The built image itself is not an intermediate: it is the artifact.
+    """
+    found: list[str] = []
+    seen: set[int] = set()
+
+    def walk(image: Any) -> None:
+        if id(image) in seen:
+            return
+        seen.add(id(image))
+        for dependency in getattr(image, "deps", lambda: ())():
+            if hasattr(dependency, "deps"):
+                walk(dependency)
+        object_id = getattr(image, "object_id", None)
+        if object_id and image is not built:
+            found.append(str(object_id))
+
+    try:
+        walk(built)
+    except Exception:
+        return ()
+    return tuple(dict.fromkeys(found))
+
+
 class Builder(ManagedBuilder):
     """Modal: the capability half (E2-06) and the build (E2-05)."""
 
@@ -253,7 +286,7 @@ class Builder(ManagedBuilder):
     title = "Modal"
     #: A `packages` list and, for conda (E3-02), an `environment.yml`
     #: dependency file installed with `micromamba_install`.
-    build_sources = ("packages", "dependencyFile")
+    build_sources = ("packages", "dependencyFile", "dockerfile")
     dependency_formats = ("conda",)
     #: Modal runs GPUs, in the owner's workspace (E2-17). This builder does
     #: not build one yet: see `build`'s own guard.
@@ -479,6 +512,7 @@ class Builder(ManagedBuilder):
             mutable_alias=name,
             provider_account=provider_account(self.variant, self._provider_secrets()) or None,
             contract_version=spec.contract or SANDBOX_CONTRACT_V1.version,
+            intermediates=_intermediates_of(built),
         )
 
     def _resolved_secrets(self, request: BuildRequest) -> tuple[list[BuildSecret], dict[str, str]]:
@@ -631,6 +665,56 @@ class Builder(ManagedBuilder):
             raise self._provider_error("ask whether the image exists", error) from error
         return True
 
+    def delete(self, artifact: ArtifactReference) -> None:
+        """Delete the image, and every intermediate layer this build recorded (E2-05, E2-09).
+
+        Deleting the artifact does not delete the layers under it, and Modal
+        offers no call that lists an account's images, so what is removed is
+        what `build` wrote down — an intermediate nobody recorded can never be
+        found again.
+
+        Two answers are outcomes rather than failures, both found live on
+        2026-09-17:
+
+        * **Already gone** is success. A replay of a collection must delete the
+          same set again with no harm, the same way the Datalayer collector
+          treats an artifact that is not there.
+        * **Not ours to delete.** The bottom of a chain can be an image the
+          workspace does not own — Modal's own `debian_slim` answers
+          `PermissionDenied` — and an image somebody else owns was never this
+          artifact's to collect. It is logged and stepped over, not raised.
+        """
+        sdk = self._modal_sdk()
+        client = self._client(sdk)
+        synchronizer, api_pb2 = self._modal_internals()
+
+        async def _delete(image_id: str) -> None:
+            await client.stub.ImageDelete(api_pb2.ImageDeleteRequest(image_id=image_id))
+
+        # The artifact last: an intermediate is only reachable while the
+        # record naming it survives, so a half-done collection that has
+        # dropped the image would strand them.
+        for image_id in (*artifact.intermediates, artifact.provider_artifact_id):
+            if not image_id:
+                continue
+            try:
+                # A bare coroutine on Modal's stub silently does nothing, so
+                # this runs on the SDK's own loop — see `_delete_secret`.
+                synchronizer.wrap(_delete)(image_id)
+            except sdk.exception.NotFoundError:
+                continue
+            except Exception as error:
+                if "permission" in str(error).lower():
+                    self._log(
+                        f"The Modal image {image_id} is not this account's to delete: {error}"
+                    )
+                    continue
+                if image_id == artifact.provider_artifact_id:
+                    raise self._provider_error("delete the image", error) from error
+                # One layer's refusal does not strand the rest, nor the
+                # artifact this was called to collect.
+                self._log(f"The Modal intermediate {image_id} could not be deleted: {error}")
+
     def _provider_error(self, what: str, error: BaseException) -> EnvironmentsError:
         return EnvironmentsError(
             PROVIDER_ERROR,

{code_sandboxes-1.9.18 → code_sandboxes-1.9.20}/code_sandboxes/environments/attest.py

@@ -106,6 +106,76 @@ def signature_tag(digest: str) -> str:
     return text.replace(":", "-", 1) + ".sig"
 
 
+#: Where a CycloneDX component keeps its licence, in the order they are read.
+_CYCLONEDX_LICENSE_KEYS = ("id", "name")
+#: Where an SPDX package keeps its licence. `licenseConcluded` is what the
+#: tool decided; `licenseDeclared` is what the package claimed. BuildKit
+#: writes SPDX, so this is the one that matters in practice.
+_SPDX_LICENSE_KEYS = ("licenseConcluded", "licenseDeclared")
+#: What SPDX writes when it could not tell, which is not a licence.
+_SPDX_UNKNOWN = frozenset({"NOASSERTION", "NONE", ""})
+
+
+def _spdx_licenses(document: Mapping[str, Any]) -> set[str]:
+    """What an SPDX document names, which is what BuildKit's `attest:sbom=` writes.
+
+    `licenseConcluded` is what the tool decided and `licenseDeclared` what the
+    package claimed, so the concluded one is read first and the declared one
+    only when it said nothing.
+    """
+    found: set[str] = set()
+    for package in document.get("packages") or ():
+        if not isinstance(package, Mapping):
+            continue
+        for key in _SPDX_LICENSE_KEYS:
+            value = str(package.get(key) or "").strip()
+            if value and value.upper() not in _SPDX_UNKNOWN:
+                found.add(value)
+                break
+    return found
+
+
+def _cyclonedx_licenses(document: Mapping[str, Any]) -> set[str]:
+    """What a CycloneDX document names, by id, by name, or as an expression."""
+    found: set[str] = set()
+    for component in document.get("components") or ():
+        if not isinstance(component, Mapping):
+            continue
+        for entry in component.get("licenses") or ():
+            if not isinstance(entry, Mapping):
+                continue
+            licence = entry.get("license")
+            if isinstance(licence, Mapping):
+                for key in _CYCLONEDX_LICENSE_KEYS:
+                    value = str(licence.get(key) or "").strip()
+                    if value:
+                        found.add(value)
+                        break
+            expression = str(entry.get("expression") or "").strip()
+            if expression:
+                found.add(expression)
+    return found
+
+
+def licenses_of(document: Any) -> list[str]:
+    """Every licence an SBOM names, deduplicated and sorted.
+
+    Reads both shapes the ecosystem writes: SPDX, which is what BuildKit's
+    `attest:sbom=` produces, and CycloneDX. A document in neither shape, or one
+    that names nothing, answers an empty list rather than raising: a
+    publication's licence list is worth having and never worth failing a build
+    over.
+
+    This is what a published version's snapshot carries (D-12, E2-16). Until
+    it did, `licenses` came from the scan summary — and the registry's scanner
+    reports vulnerabilities, not licences, so every publication froze an empty
+    list beside an SBOM reference.
+    """
+    if not isinstance(document, Mapping):
+        return []
+    return sorted(_spdx_licenses(document) | _cyclonedx_licenses(document))
+
+
 @dataclass(frozen=True)
 class AttestationResult:
     """What the workflow stores about an artifact once both gates have passed."""
@@ -117,6 +187,8 @@ class AttestationResult:
     size_bytes: int | None = None
     signed_now: bool = True
     """False when a replay found the signature that was already there."""
+    licenses: tuple[str, ...] = ()
+    """What the SBOM named, frozen onto the artifact for a publication to carry."""
 
     def body(self) -> dict[str, Any]:
         """The mapping `activities_environments.attest` answers."""
@@ -127,6 +199,7 @@ class AttestationResult:
             "signature_ref": self.signature_ref,
             "size_bytes": self.size_bytes,
             "signed_now": self.signed_now,
+            "licenses": list(self.licenses),
         }
 
 
@@ -515,8 +588,14 @@ class Attestor:
         size_bytes: int | None = None,
         sbom_ref: str = "",
         provenance_ref: str = "",
+        sbom: Any = None,
     ) -> AttestationResult:
-        """Scan, then sign: the order the Operator's check depends on (D-11)."""
+        """Scan, then sign: the order the Operator's check depends on (D-11).
+
+        `sbom`, when the caller has the document, is read for the licences a
+        publication carries; the registry's scanner reports vulnerabilities
+        and never licences, so there is nowhere else they come from.
+        """
         self.can_sign()
         decision = self.scan(repository=repository, digest=digest)
         if not decision.passed:
@@ -540,6 +619,7 @@ class Attestor:
             if size_bytes is not None
             else self.size_of(repository=repository, digest=digest),
             signed_now=signed_now,
+            licenses=tuple(licenses_of(sbom)),
         )
 
     def size_of(self, *, repository: str, digest: str) -> int | None:

{code_sandboxes-1.9.18 → code_sandboxes-1.9.20}/code_sandboxes/environments/build_secrets.py

@@ -28,7 +28,12 @@ from __future__ import annotations
 import os
 from typing import Any
 
-from .errors import BUILD_SECRET_UNAVAILABLE, EnvironmentsError
+from .errors import (
+    BUILD_SECRET_UNAVAILABLE,
+    CAPABILITY_UNSUPPORTED,
+    PROVIDER_ERROR,
+    EnvironmentsError,
+)
 from .spec import BuildSecret
 
 __all__ = [
@@ -150,3 +155,141 @@ def resolve_build_secret(
             retryable=False,
         )
     return value
+
+
+#: The managed variants an owner keeps a credential for (D-8). `datalayer` is
+#: not one: the platform's own builder uses the platform's own registry.
+PROVIDER_VARIANTS = frozenset({"daytona", "e2b", "modal"})
+
+
+def resolve_provider_credential(
+    variant: str,
+    *,
+    owner_uid: str,
+    iam_url: str | None = None,
+    api_key: str | None = None,
+    timeout: float = 10.0,
+    transport: Any = None,
+) -> dict[str, str]:
+    """The owner's own credential for a managed variant (PLAN_ENVS.md E2-01, D-8).
+
+    A managed artifact exists only in the account the credential opens, so the
+    build runs with the owner's keys and records a non-secret fingerprint of
+    that account. The value IAM holds is a JSON object of the environment
+    names the provider's own SDK reads — ``DAYTONA_API_KEY``,
+    ``E2B_API_KEY``, ``MODAL_TOKEN_ID`` and ``MODAL_TOKEN_SECRET``, and
+    optionally the account names ``environments/accounts.py`` reads to
+    fingerprint it — because that is the shape ``BuildCredential`` carries and
+    every adapter already reads.
+
+    Raises ``DL_ENV_CAPABILITY_UNSUPPORTED`` — not retryable — when the owner
+    has no credential for this variant. A build must be told it cannot run in
+    an account nobody configured, rather than falling back to whatever keys
+    the worker happens to hold: that would put one owner's artifact in
+    another's account, which is the one thing D-8 exists to prevent.
+    """
+    variant = (variant or "").strip().lower()
+    if variant not in PROVIDER_VARIANTS:
+        raise EnvironmentsError(
+            CAPABILITY_UNSUPPORTED,
+            f"`{variant}` is not a managed variant a credential is kept for",
+            detail={"variant": variant},
+            retryable=False,
+        )
+    key = api_key if api_key is not None else os.environ.get(IAM_API_KEY_VARIABLE, "")
+    if not key:
+        raise EnvironmentsError(
+            CAPABILITY_UNSUPPORTED,
+            f"No {IAM_API_KEY_VARIABLE} to ask IAM for the {variant} credential with",
+            detail={"variant": variant, "missing": IAM_API_KEY_VARIABLE},
+            retryable=False,
+        )
+    base = (iam_url if iam_url is not None else os.environ.get(IAM_URL_VARIABLE, "")).rstrip("/")
+    if not base:
+        raise EnvironmentsError(
+            CAPABILITY_UNSUPPORTED,
+            f"No {IAM_URL_VARIABLE} to ask for the {variant} credential",
+            detail={"variant": variant, "missing": IAM_URL_VARIABLE},
+            retryable=False,
+        )
+    try:
+        import httpx
+    except ImportError as error:
+        raise EnvironmentsError(
+            CAPABILITY_UNSUPPORTED,
+            "No HTTP client to resolve a provider credential with: install "
+            "`code-sandboxes[environments-builder]`",
+            detail={"variant": variant, "missing": "httpx"},
+            retryable=False,
+        ) from error
+    url = f"{base}/api/iam/v1/secrets/provider/{variant}/value"
+    try:
+        with httpx.Client(transport=transport, timeout=timeout) as client:
+            response = client.get(
+                url,
+                params={"owner_uid": owner_uid},
+                headers={"X-API-Key": key},
+            )
+    except httpx.HTTPError as error:
+        raise EnvironmentsError(
+            PROVIDER_ERROR,
+            f"IAM could not be reached for the {variant} credential: {error}",
+            detail={"variant": variant},
+            retryable=True,
+        ) from error
+    if response.status_code == 404:
+        raise EnvironmentsError(
+            CAPABILITY_UNSUPPORTED,
+            f"This owner has no {variant} credential: a managed build runs in "
+            f"their own account, so one must be kept before {variant} can build",
+            detail={"variant": variant, "status": 404},
+            retryable=False,
+        )
+    if response.status_code != 200:
+        raise EnvironmentsError(
+            PROVIDER_ERROR,
+            f"IAM refused the {variant} credential: {response.status_code}",
+            detail={"variant": variant, "status": response.status_code},
+            retryable=True,
+        )
+    try:
+        body = response.json()
+    except ValueError as error:
+        raise EnvironmentsError(
+            PROVIDER_ERROR,
+            f"IAM answered the {variant} credential with a body that is not valid JSON",
+            detail={"variant": variant},
+            retryable=True,
+        ) from error
+    return _provider_secrets_of(body.get("value") if isinstance(body, dict) else None, variant)
+
+
+def _provider_secrets_of(value: Any, variant: str) -> dict[str, str]:
+    """The environment names a provider credential carries, as IAM answered.
+
+    A mapping of names to values: IAM gathers them from the secrets the owner
+    already keeps, one per environment variable, and decodes them, so the
+    worker is not asked to know how a secret is stored.
+    """
+    if not isinstance(value, dict) or not value:
+        raise EnvironmentsError(
+            CAPABILITY_UNSUPPORTED,
+            f"IAM answered the {variant} credential with no usable value; a "
+            "provider credential is the environment names that provider's own "
+            "SDK reads",
+            detail={"variant": variant},
+            retryable=False,
+        )
+    secrets = {
+        str(name): str(item)
+        for name, item in value.items()
+        if str(name).strip() and str(item).strip()
+    }
+    if not secrets:
+        raise EnvironmentsError(
+            CAPABILITY_UNSUPPORTED,
+            f"The {variant} credential names nothing",
+            detail={"variant": variant},
+            retryable=False,
+        )
+    return secrets

{code_sandboxes-1.9.18 → code_sandboxes-1.9.20}/code_sandboxes/environments/builders.py

@@ -141,6 +141,14 @@ class ArtifactReference(_Model):
     provider_account: str | None = None
     contract_version: str
     architecture: str = "linux/amd64"
+    #: The layers this build left behind that deleting the artifact does not
+    #: delete (E2-05, E2-09). Modal is the variant that has them: each chained
+    #: builder call leaves an image of its own with an id, and Modal offers no
+    #: call that lists an account's images — `ImageGetOrCreate`, `ImageFromId`,
+    #: `ImageGetByTag`, `ImageListTags`, `ImageTagRevisions`, `ImagePublish`
+    #: and `ImageDelete`, and nothing that enumerates — so an intermediate
+    #: nobody wrote down is an intermediate nobody can ever find again.
+    intermediates: tuple[str, ...] = ()
 
     @model_validator(mode="after")
     def _immutable(self) -> ArtifactReference:

{code_sandboxes-1.9.18 → code_sandboxes-1.9.20}/code_sandboxes/environments/spec.py

@@ -55,10 +55,10 @@ __all__ = [
     "BUILD_SOURCES",
     "GPU_SIZE_CLASSES",
     "KIND",
+    "PUBLIC_PACKAGE_INDEX_HOSTS",
     "SIZE_CLASSES",
     "SUPPORTED_BUILD_SOURCES",
     "VARIANTS",
-    "PUBLIC_PACKAGE_INDEX_HOSTS",
     "Accelerator",
     "ArtifactStatus",
     "Base",
@@ -174,14 +174,12 @@ class Platform(_Model):
 #: reached with a credential the public does not hold. Matched on host, so the
 #: trailing `/simple` or its absence never decides it. `pypi.org` is the index;
 #: `files.pythonhosted.org` is where its wheels are served from.
-PUBLIC_PACKAGE_INDEX_HOSTS = frozenset(
-    {"pypi.org", "files.pythonhosted.org"}
-)
+PUBLIC_PACKAGE_INDEX_HOSTS = frozenset({"pypi.org", "files.pythonhosted.org"})
 
 
 def _package_index_host(url: str) -> str:
     """The host an index URL names, lower-cased and without its port, or `""`."""
-    from urllib.parse import urlsplit  # noqa: PLC0415
+    from urllib.parse import urlsplit
 
     try:
         return (urlsplit(url).hostname or "").lower()
@@ -214,9 +212,7 @@ PUBLIC_CONDA_CHANNELS = frozenset(
         "msys2",
     }
 )
-PUBLIC_CONDA_CHANNEL_HOSTS = frozenset(
-    {"conda.anaconda.org", "repo.anaconda.com", "anaconda.org"}
-)
+PUBLIC_CONDA_CHANNEL_HOSTS = frozenset({"conda.anaconda.org", "repo.anaconda.com", "anaconda.org"})
 
 
 def channel_is_public(channel: str) -> bool:
@@ -344,6 +340,25 @@ class DependencyFileSpec(_Model):
     lock_content: str = ""
 
 
+class DockerfileSpec(_Model):
+    """The Dockerfile a `dockerfile`-sourced version builds from (E3-03).
+
+    Inline, the way ``DependencyFileSpec`` carries a ``requirements.txt``: a
+    file the author brings lives in the spec, so ``check_dockerfile`` and
+    every variant's capability report can read it **before** anything is
+    queued — which is the whole point of refusing an instruction a variant
+    does not implement at ``validate`` rather than halfway through a build.
+
+    The build *context* — the extra files a ``COPY`` needs — is the separate
+    upload E3-03 describes, bounded and checked by ``validate_build_context``.
+    A Dockerfile with no context is the common case and needs no upload at
+    all.
+    """
+
+    #: The Dockerfile text.
+    content: str = ""
+
+
 class ImageSourceSpec(_Model):
     """An existing OCI image, imported as the build's base (E3-04).
 
@@ -370,6 +385,7 @@ class ImageSourceSpec(_Model):
 class BuildSpec(_Model):
     source: Literal["packages", "dependencyFile", "dockerfile", "image"] = "packages"
     dependency_file: DependencyFileSpec | None = None
+    dockerfile: DockerfileSpec | None = None
     image: ImageSourceSpec | None = None
 
 
@@ -486,6 +502,28 @@ def parse_requirements_txt(text: str) -> list[str]:
     return lines
 
 
+def _dockerfile_findings(dockerfile: DockerfileSpec | None) -> list[SpecFinding]:
+    """What a `dockerfile`-sourced version must carry, and what the contract refuses.
+
+    The contract's own refusals are reported here, at `validate`, rather than
+    at build time: a `FROM` that is not an approved base, a privileged build,
+    the host network, a Docker socket mount, a host bind mount, and every
+    instruction §6 does not allow. Each is named with its line, because a
+    Dockerfile is somebody's file and "it was refused" is not a reason.
+    """
+    field = "spec.build.dockerfile"
+    if dockerfile is None:
+        return [SpecFinding(field, "is required when `spec.build.source` is `dockerfile`")]
+    if not dockerfile.content.strip():
+        return [SpecFinding(f"{field}.content", "is empty; it is the Dockerfile text")]
+    from .contract import validate_dockerfile
+
+    return [
+        SpecFinding(f"{field}.content", f"line {finding.line}: {finding.message}")
+        for finding in validate_dockerfile(dockerfile.content)
+    ]
+
+
 def _dependency_file_findings(dependency_file: DependencyFileSpec | None) -> list[SpecFinding]:
     field = "spec.build.dependencyFile"
     if dependency_file is None:
@@ -644,6 +682,8 @@ def spec_findings(
         )
     if spec.build.source == "dependencyFile":
         findings.extend(_dependency_file_findings(spec.build.dependency_file))
+    elif spec.build.source == "dockerfile":
+        findings.extend(_dockerfile_findings(spec.build.dockerfile))
     elif spec.build.source == "image":
         findings.extend(_image_findings(spec.build.image))
 
@@ -951,11 +991,7 @@ def publication_findings(environment: Environment) -> list[SpecFinding]:
                 PUBLICATION_BLOCKED,
             )
         )
-    private = [
-        url
-        for url in environment.spec.packages.python.indexes
-        if not index_is_public(url)
-    ]
+    private = [url for url in environment.spec.packages.python.indexes if not index_is_public(url)]
     if private:
         findings.append(
             SpecFinding(