code-sandboxes 1.9.3__tar.gz → 1.9.5__tar.gz

{code_sandboxes-1.9.3 → code_sandboxes-1.9.5}/CHANGELOG.md

@@ -8,6 +8,62 @@
 
 ## Unreleased
 
+## 1.9.5
+
+- **Attest waits for a just-pushed image's scan to exist**
+  (`environments.attest`; PLAN_ENV.md E1-08). Enhanced scanning starts after
+  the push, so the first answers for a new image are
+  `ScanNotFoundException`. Attest read that as an image with no scan and
+  failed the build at once (found live on r1, 2026-09-14). It is now waited
+  for like a running scan, within the same bound.
+- **apt is pinned at, and installed from, the base channel's Ubuntu snapshot**
+  (`environments.bases`, `environments.resolve`,
+  `environments.adapters.datalayer`; PLAN_ENV.md E1-04). A channel records
+  the `snapshot.ubuntu.com` id its image was upgraded at. The solve runs
+  `apt-get` with `--snapshot` at that id, the lock records it
+  (`# datalayer-apt-snapshot:`), and the Datalayer builder installs its pins
+  from the same snapshot. This replaces a `deb` line that named only `main`
+  (`gdal-bin` is in `universe`) and left the live mirror enabled beside it.
+  `DATALAYER_APT_SNAPSHOT` must now be a snapshot id.
+- **A private registry's credential is resolved and used** (`environments
+  .image_import`, `environments.resolve`; PLAN_ENV.md E3-04's second half).
+  `image.credentialSecretId` used to only clear the allowlist check; nothing
+  fetched or used the credential it named. It is now fetched through the
+  same IAM route a build secret is (E3-05), and sent as HTTP Basic on the
+  registry's own token exchange — the way `docker login` authenticates a
+  private pull — never to the registry named in the reference, and never
+  logged. `resolve_environment` and `resolve_image_base` take `owner_uid`
+  and `resolve_secret` to reach it; unused by a public registry or any other
+  source.
+- **The Datalayer base channel's own five ESM-locked advisories are allowed**
+  (`environments.policy`; PLAN_ENV.md E1-08). Amazon Inspector marks all five
+  fixable, but the fix is an Ubuntu ESM package version a plain
+  `apt-get upgrade` cannot reach. Reviewed and added to `DEFAULT_POLICY
+  .allowed`, 2026-09-14, so they are recorded as allowed rather than missed,
+  and any other critical still blocks.
+
+## 1.9.4
+
+- **A pushed Environment image is decided by its linux/amd64 image's scan**
+  (`environments.attest`; PLAN_ENV.md E1-08). The Datalayer builder pushes
+  with SBOM and provenance attestations, so the digest it records is an OCI
+  image index. Amazon Inspector scans the image inside it and answers
+  `UNSUPPORTED_IMAGE` for the index itself, so every real build failed at
+  `attest` with `DL_ENV_PROVIDER_ERROR` (found live on r1, 2026-09-14, the
+  first build to get past the scan-read permission). The attestor now reads
+  the manifest and, for an index, reads the scan of its `linux/amd64` image,
+  skipping the attestation manifest. The signature stays on the index, which
+  is what a pod pulls.
+- **Modal attaches a build secret to the `postInstall` steps that name it**
+  (`environments.adapters.modal`; PLAN_ENV.md E3-05). Modal used to refuse
+  every `buildSecrets` spec. Each declared secret is now resolved from IAM
+  before Modal is touched, made into a Modal Secret of the build's own,
+  passed as `secrets=` to exactly the `run_commands` steps whose command
+  names it, and deleted after the build like the base-reader secret. Its
+  value is redacted from the log and from a failed build's error. A
+  `mountAs: file` secret is refused, because Modal passes secrets as
+  environment variables and a file would land in a layer.
+
 ## 1.9.3
 
 - **A build secret is mounted only on the `postInstall` commands that name it**

{code_sandboxes-1.9.3 → code_sandboxes-1.9.5}/PKG-INFO

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

{code_sandboxes-1.9.3 → code_sandboxes-1.9.5}/code_sandboxes/__version__.py

@@ -3,4 +3,4 @@
 
 """Code Sandboxes."""
 
-__version__ = "1.9.3"
+__version__ = "1.9.5"

{code_sandboxes-1.9.3 → code_sandboxes-1.9.5}/code_sandboxes/environments/adapters/datalayer.py

@@ -68,7 +68,13 @@ from ..errors import (
     EnvironmentsError,
 )
 from ..files import files_step
-from ..resolve import WHEELHOUSE_IMAGE_PATH, WHEELHOUSE_PATH, apt_pins_in, locked_versions
+from ..resolve import (
+    WHEELHOUSE_IMAGE_PATH,
+    WHEELHOUSE_PATH,
+    apt_pins_in,
+    apt_snapshot_in,
+    locked_versions,
+)
 from ..spec import BuildSecret, Environment, command_names_secret
 
 __all__ = [
@@ -310,14 +316,18 @@ class Builder:
             lines.append(f"ENV {name}={shlex.quote(spec.env[name])}")
         if apt:
             # Pinned, and from the lock: `apt-get install <name>` a month later
-            # is a different artifact.
+            # is a different artifact. From the snapshot the pins were taken
+            # from, when the lock names one: a pinned version can leave the
+            # live mirror (D-9).
             pinned = " ".join(f"{name}={apt[name]}" for name in sorted(apt))
+            snapshot = apt_snapshot_in(request.lock_text)
+            option = f" --snapshot {snapshot}" if snapshot else ""
             lines.extend(
                 [
                     "USER root",
                     "RUN --mount=type=cache,target=/var/cache/apt,sharing=locked "
-                    "apt-get update -qq \\\n"
-                    f"    && apt-get install -y --no-install-recommends {pinned} \\\n"
+                    f"apt-get update -qq{option} \\\n"
+                    f"    && apt-get install -y --no-install-recommends{option} {pinned} \\\n"
                     "    && rm -rf /var/lib/apt/lists/*",
                 ]
             )

{code_sandboxes-1.9.3 → code_sandboxes-1.9.5}/code_sandboxes/environments/adapters/modal.py

@@ -104,16 +104,16 @@ builder does not know the launch-time `gpu=` argument to hand a size class
 either (D-20 leaves that to a later item; a GPU is Modal's own launch
 option, not an image property, per section 11.4 item 10).
 
-**`spec.buildSecrets` is refused, unlike what Modal's own SDK could do.**
-`run_commands`/`apt_install`/`dockerfile_commands` each take a per-step
-`secrets=` collection — Modal has a real per-step secret mechanism, unlike
-E2B or Daytona. What is missing is not Modal's capability but this
-builder's own: `resolve_build_secret` (E3-05) has landed (`code_sandboxes
-.environments.build_secrets`), but nothing here calls it yet — wiring it
-into a Modal `secrets=` collection, and its own creation/cleanup lifecycle
-(mirroring `_ecr_secret`/`_delete_secret` above), is real, separate,
-follow-up work, not attempted in this pass. Refused for now, with that
-reason, rather than silently built without it.
+**A build secret is attached to the `postInstall` steps that name it (E3-05).**
+`run_commands` takes a per-step `secrets=` collection, a mechanism E2B and
+Daytona lack. Each declared secret is resolved from IAM
+(`resolve_build_secret`) before Modal is touched, made into a Modal Secret of
+this build's own, attached to exactly the `run_commands` steps whose command
+names it (`command_names_secret`), and deleted after the build the way the
+base-reader secret is. Its value is redacted from the build's log and from a
+failed build's error. Modal hands a secret to a step only as environment
+variables, so a `mountAs: file` secret is refused: making it a file would
+write it into a layer.
 
 @module code_sandboxes.environments.adapters.modal
 """
@@ -129,6 +129,7 @@ from pathlib import Path
 from typing import Any
 
 from ..accounts import provider_account
+from ..build_secrets import resolve_build_secret
 from ..builders import (
     ArtifactMetadata,
     ArtifactReference,
@@ -144,8 +145,9 @@ from ..errors import (
     EnvironmentsError,
 )
 from ..files import files_step
+from ..redact import redact
 from ..resolve import WHEELHOUSE_IMAGE_PATH, apt_pins_in
-from ..spec import GPU_SIZE_CLASSES, Environment
+from ..spec import GPU_SIZE_CLASSES, BuildSecret, Environment, command_names_secret
 from .managed import ManagedBuilder
 
 __all__ = ["UNIMPLEMENTED_INSTRUCTIONS", "Builder"]
@@ -204,6 +206,21 @@ def _modal_internals() -> tuple[Any, Any]:
     return synchronizer, api_pb2
 
 
+def _scrubbed(text: str, values: dict[str, str]) -> str:
+    """The text with this build's secret values redacted, or as it was with none (E3-05)."""
+    return redact(text, values.values()) if values else text
+
+
+def _post_install(
+    image: Any, commands: list[str], declared: list[BuildSecret], step_secrets: dict[str, Any]
+) -> Any:
+    """Each `postInstall` command as its own step, with the secrets it names (E3-05)."""
+    for command in commands:
+        named = [step_secrets[s.id] for s in declared if command_names_secret(command, s)]
+        image = image.run_commands(command, secrets=named) if named else image.run_commands(command)
+    return image
+
+
 class Builder(ManagedBuilder):
     """Modal: the capability half (E2-06) and the build (E2-05)."""
 
@@ -228,8 +245,12 @@ class Builder(ManagedBuilder):
         modal_internals: Callable[[], tuple[Any, Any]] | None = None,
         image_builder_version: str | None = None,
         region: str | None = None,
+        resolve_secret: Callable[..., str] = resolve_build_secret,
     ) -> None:
         super().__init__(log=log, credential=credential)
+        #: How one `BuildSecret`'s value is fetched (E3-05): IAM by default,
+        #: the same seam the Datalayer builder takes.
+        self._resolve_secret = resolve_secret
         self._modal_sdk = modal_sdk or _modal_sdk
         self._modal_internals = modal_internals or _modal_internals
         self._image_builder_version = image_builder_version or _IMAGE_BUILDER_VERSION
@@ -297,24 +318,19 @@ class Builder(ManagedBuilder):
                         field=f"spec.commands.postInstall[{index}]",
                     )
                 )
-        if environment.spec.build_secrets:
-            # Modal's own per-step `secrets=` mechanism could carry one —
-            # unlike E2B or Daytona — and `resolve_build_secret` (E3-05) has
-            # landed, but nothing here calls it yet: wiring it into a Modal
-            # `secrets=` collection is real, separate work (found in this
-            # item's own implementation, not a provider limit).
-            ids = ", ".join(secret.id for secret in environment.spec.build_secrets)
-            findings.append(
-                CapabilityFinding(
-                    code="DL_ENV_CAPABILITY_UNSUPPORTED",
-                    message=(
-                        f"`buildSecrets` ({ids}) is not wired into this builder yet — Modal's own "
-                        "per-step secrets could carry one, and resolve_build_secret (E3-05) can "
-                        "resolve one, but nothing here connects them"
-                    ),
-                    field="spec.buildSecrets",
+        for index, secret in enumerate(environment.spec.build_secrets):
+            if secret.mount_as == "file":
+                findings.append(
+                    CapabilityFinding(
+                        code="DL_ENV_CAPABILITY_UNSUPPORTED",
+                        message=(
+                            f"Modal gives `{secret.name}` to a step as an environment variable "
+                            "only; a file would be written into a layer. Use `mountAs: env`, or "
+                            "drop `modal` from the variants"
+                        ),
+                        field=f"spec.buildSecrets[{index}].mountAs",
+                    )
                 )
-            )
         return findings
 
     # -- Building -------------------------------------------------------------
@@ -340,20 +356,9 @@ class Builder(ManagedBuilder):
                 "needs is E2-17's, not built yet",
                 detail={"variant": self.variant, "missing": "E2-17"},
             )
-        if request.build_secret_ids or spec.build_secrets:
-            # `_own_findings` already refuses this at `validate()` — this
-            # guard is `build()`'s own, the same way the GPU one above is,
-            # because nothing enforces that `build` is only ever called
-            # after a passing `validate` (found in review): a caller
-            # handing `build()` an already-resolved request could otherwise
-            # get a successful image with a required credential silently
-            # missing from it.
-            raise EnvironmentsError(
-                CAPABILITY_UNSUPPORTED,
-                "Modal's build secrets are not wired into this builder yet (E3-05 has landed, "
-                "but nothing here calls it)",
-                detail={"variant": self.variant, "missing": "E3-05"},
-            )
+        # Resolved before Modal is touched: a secret IAM will not give stops
+        # the build with nothing to clean up in the owner's workspace.
+        declared, values = self._resolved_secrets(request)
         sdk = self._modal_sdk()
         # Read from the process environment, not a per-call argument (see
         # the module docstring) — set before anything else touches the SDK.
@@ -362,7 +367,12 @@ class Builder(ManagedBuilder):
         name = f"dl-{request.environment.metadata.name}-v{request.version}-{request.build_uid}"
 
         ecr_secret = self._ecr_secret(sdk, client)
+        step_secrets: dict[str, Any] = {}
         try:
+            for secret in declared:
+                step_secrets[secret.id] = self._hydrated_secret(
+                    sdk, client, {secret.name: values[secret.id]}, keep=step_secrets
+                )
             app = sdk.App.lookup(
                 f"dl-{request.environment.metadata.name}", client=client, create_if_missing=True
             )
@@ -404,8 +414,7 @@ class Builder(ManagedBuilder):
                 )
                 for command in files_step(request.environment, variant=self.variant):
                     image = image.run_commands(command)
-                for command in spec.commands.post_install:
-                    image = image.run_commands(command)
+                image = _post_install(image, spec.commands.post_install, declared, step_secrets)
                 image = image.workdir(_CONTENT_DIR).entrypoint([_ENTRYPOINT_PATH])
 
                 logged: list[str] = []
@@ -423,13 +432,13 @@ class Builder(ManagedBuilder):
                     # that raised inside the `with` block above never
                     # reached the line that read it, so a failed build's
                     # own log was silently dropped from the error detail.
-                    logged.extend(buffer.getvalue().splitlines())
+                    logged.extend(_scrubbed(buffer.getvalue(), values).splitlines())
                     raise EnvironmentsError(
                         BUILD_FAILED,
-                        f"The Modal build failed: {error}",
+                        f"The Modal build failed: {_scrubbed(str(error), values)}",
                         detail={"variant": self.variant, "name": name, "log": logged[-20:]},
-                    ) from error
-                logged.extend(buffer.getvalue().splitlines())
+                    ) from (None if values else error)
+                logged.extend(_scrubbed(buffer.getvalue(), values).splitlines())
                 for line in logged:
                     self._log(line)
             # A name for people and dashboards only (§11.4 item 3): moves
@@ -439,6 +448,8 @@ class Builder(ManagedBuilder):
             # No standing credential is left in an account Datalayer does
             # not control, whether the build above succeeded or not (D-18).
             self._delete_secret(sdk, client, ecr_secret)
+            for secret in step_secrets.values():
+                self._delete_secret(sdk, client, secret)
 
         return ArtifactReference(
             variant=self.variant,
@@ -450,6 +461,25 @@ class Builder(ManagedBuilder):
             contract_version=spec.contract or SANDBOX_CONTRACT_V1.version,
         )
 
+    def _resolved_secrets(self, request: BuildRequest) -> tuple[list[BuildSecret], dict[str, str]]:
+        """The build secrets this build attaches, and each one's value from IAM (E3-05).
+
+        `_own_findings` refuses a `mountAs: file` secret at `validate()`. This
+        guards it too, the same way `build` guards a GPU class, because
+        nothing makes a caller validate first.
+        """
+        wanted = set(request.build_secret_ids)
+        declared = [s for s in request.environment.spec.build_secrets if s.id in wanted]
+        if any(secret.mount_as == "file" for secret in declared):
+            raise EnvironmentsError(
+                CAPABILITY_UNSUPPORTED,
+                "Modal gives a build secret to a step as an environment variable only; a "
+                "`mountAs: file` secret would be written into a layer",
+                detail={"variant": self.variant, "field": "spec.buildSecrets"},
+            )
+        values = {s.id: self._resolve_secret(s, owner_uid=request.owner_uid) for s in declared}
+        return declared, values
+
     def _ecr_secret(self, sdk: Any, client: Any) -> Any | None:
         """A Modal Secret carrying this build's own base-reader credential (D-17, D-18).
 
@@ -489,6 +519,30 @@ class Builder(ManagedBuilder):
             ) from error
         return secret
 
+    def _hydrated_secret(
+        self, sdk: Any, client: Any, env: dict[str, str], *, keep: dict[str, Any]
+    ) -> Any:
+        """A Modal Secret of this build's own for one build secret (E3-05).
+
+        Created in the owner's workspace like `_ecr_secret`'s, and deleted by
+        `build`'s own `finally`. A `hydrate` that fails is cleaned up here,
+        since `build` never got it back. The error names no value.
+        """
+        secret = sdk.Secret.from_dict(env)
+        try:
+            secret.hydrate(client=client)
+        except Exception as error:
+            self._delete_secret(sdk, client, secret)
+            # `from None`: Modal's own error is not kept, in case it echoes
+            # what it was given. Its type is enough to tell failures apart.
+            raise EnvironmentsError(
+                PROVIDER_ERROR,
+                f"Modal could not be given the build secret `{next(iter(env))}` "
+                f"({type(error).__name__})",
+                detail={"variant": self.variant, "made": len(keep)},
+            ) from None
+        return secret
+
     def _delete_secret(self, sdk: Any, client: Any, secret: Any | None) -> None:
         """Delete the app-owned copy Modal stores of this build's own secret.
 

{code_sandboxes-1.9.3 → code_sandboxes-1.9.5}/code_sandboxes/environments/attest.py

@@ -32,6 +32,7 @@ clock — so the whole chain is tested without AWS and without a daemon.
 
 from __future__ import annotations
 
+import json
 import logging
 import os
 import re
@@ -68,6 +69,20 @@ SCAN_STATUSES = {
     "refused": ("FAILED", "UNSUPPORTED_IMAGE", "FINDINGS_UNAVAILABLE"),
 }
 
+#: The platform an Environment image is built for: the image of an index
+#: whose scan is read.
+_SCANNED_PLATFORM = ("linux", "amd64")
+
+#: What a registry answers for an image index, and for a single image.
+_INDEX_MEDIA_TYPES = (
+    "application/vnd.oci.image.index.v1+json",
+    "application/vnd.docker.distribution.manifest.list.v2+json",
+)
+_MANIFEST_MEDIA_TYPES = (
+    "application/vnd.oci.image.manifest.v1+json",
+    "application/vnd.docker.distribution.manifest.v2+json",
+)
+
 #: How long a scan is waited for, and how often it is asked about.
 DEFAULT_SCAN_TIMEOUT_SECONDS = 15 * 60
 DEFAULT_SCAN_INTERVAL_SECONDS = 10.0
@@ -173,29 +188,34 @@ class Attestor:
         — retryable, because nothing about the version is wrong — and so is a
         scanner that refuses the image. A scan that finished is decided, and a
         blocking decision raises `DL_ENV_SCAN_BLOCKED`.
+
+        An artifact that is an image index is decided by the scan of its
+        linux/amd64 image: see `_scanned_digest`.
         """
         deadline = self._now() + self._timeout
+        scanned = self._scanned_digest(repository=repository, digest=digest)
+        where = {"repository": repository, "digest": digest, "scannedDigest": scanned}
         waited = 0
         while True:
-            status, described = self._describe(repository=repository, digest=digest)
+            status, described = self._describe(repository=repository, digest=scanned)
             if status in SCAN_STATUSES["done"]:
                 break
             if status in SCAN_STATUSES["refused"]:
                 raise EnvironmentsError(
                     PROVIDER_ERROR,
                     f"The registry did not scan this artifact: {status}",
-                    detail={"repository": repository, "digest": digest, "scanStatus": status},
+                    detail={**where, "scanStatus": status},
                 )
             if self._now() >= deadline:
                 raise EnvironmentsError(
                     PROVIDER_ERROR,
                     f"The scan of this artifact did not finish within {self._timeout:.0f}s "
                     f"(last status {status or 'unknown'})",
-                    detail={"repository": repository, "digest": digest, "scanStatus": status},
+                    detail={**where, "scanStatus": status},
                 )
             waited += 1
             if waited == 1:
-                self._log(f"Waiting for the scan of {digest}")
+                self._log(f"Waiting for the scan of {scanned}")
             self._sleep(self._interval)
         findings = findings_of(self._findings(described))
         decision = decide(
@@ -211,6 +231,64 @@ class Attestor:
         )
         return decision
 
+    def _scanned_digest(self, *, repository: str, digest: str) -> str:
+        """The digest whose scan decides this artifact: its own, or its linux/amd64 image's.
+
+        The Datalayer builder pushes with SBOM and provenance attestations, so
+        what it records is an OCI image index: the image, and an attestation
+        manifest beside it. Enhanced scanning scans the image and answers
+        `UNSUPPORTED_IMAGE` for the index (found live on r1, 2026-09-14), so the
+        scan read is that of the image the index names for linux/amd64. The
+        signature stays on the index, which is what a pod pulls.
+        """
+        try:
+            answer = self._client().batch_get_image(
+                repositoryName=repository,
+                imageIds=[{"imageDigest": digest}],
+                acceptedMediaTypes=[*_INDEX_MEDIA_TYPES, *_MANIFEST_MEDIA_TYPES],
+            )
+        except Exception as error:
+            raise EnvironmentsError(
+                PROVIDER_ERROR,
+                f"The manifest of {digest} could not be read: {error}",
+                detail={"repository": repository, "digest": digest},
+            ) from error
+        images = answer.get("images") or []
+        if not images:
+            raise EnvironmentsError(
+                PROVIDER_ERROR,
+                f"The registry has no image {digest}",
+                detail={"repository": repository, "digest": digest},
+            )
+        try:
+            manifest = json.loads(images[0].get("imageManifest") or "{}")
+        except ValueError:
+            manifest = {}
+        media_type = str(images[0].get("imageManifestMediaType") or manifest.get("mediaType") or "")
+        if media_type not in _INDEX_MEDIA_TYPES and "manifests" not in manifest:
+            return digest
+        os_name, architecture = _SCANNED_PLATFORM
+        for entry in manifest.get("manifests") or []:
+            annotations = entry.get("annotations") or {}
+            if annotations.get("vnd.docker.reference.type") == "attestation-manifest":
+                continue
+            platform = entry.get("platform") or {}
+            child = str(entry.get("digest") or "")
+            if (
+                platform.get("os") == os_name
+                and platform.get("architecture") == architecture
+                and _DIGEST.match(child)
+            ):
+                self._log(
+                    f"Reading the scan of {child}, the {os_name}/{architecture} image of {digest}"
+                )
+                return child
+        raise EnvironmentsError(
+            PROVIDER_ERROR,
+            f"The image index {digest} holds no {os_name}/{architecture} image to scan",
+            detail={"repository": repository, "digest": digest},
+        )
+
     def _describe(self, *, repository: str, digest: str) -> tuple[str, dict[str, Any]]:
         """One `DescribeImageScanFindings`, as a status and what it answered."""
         try:
@@ -452,10 +530,20 @@ def _is_missing(error: BaseException) -> bool:
     return _error_code(error) in {
         "ImageNotFoundException",
         "RepositoryNotFoundException",
-        "ScanNotFoundException",
     }
 
 
 def _is_in_progress(error: BaseException) -> bool:
-    """ECR answers a scan that has not finished as an error, not a status."""
-    return _error_code(error) in {"ScanInProgressException", "LimitExceededException"}
+    """ECR answers a scan that has not finished as an error, not a status.
+
+    `ScanNotFoundException` is one of those answers: enhanced scanning starts
+    after the push, so an image pushed a moment ago has no scan yet (found
+    live on r1, 2026-09-14, the first build to read its image's scan rather
+    than its index's). It is waited for like a running scan, within the same
+    bound.
+    """
+    return _error_code(error) in {
+        "ScanInProgressException",
+        "ScanNotFoundException",
+        "LimitExceededException",
+    }

{code_sandboxes-1.9.3 → code_sandboxes-1.9.5}/code_sandboxes/environments/bases.py

@@ -36,6 +36,7 @@ __all__ = [
     "BaseChannelUnpublishedError",
     "approved_base",
     "approved_repositories",
+    "channel_snapshot",
     "is_approved_repository",
     "resolve_base",
 ]
@@ -44,6 +45,8 @@ __all__ = [
 ECR_BASE_PREFIX = "environments/base/"
 
 _DIGEST = re.compile(r"sha256:[0-9a-f]{64}")
+#: A snapshot.ubuntu.com id: the moment, to the second, in UTC.
+_SNAPSHOT = re.compile(r"\d{8}T\d{6}Z")
 
 
 class ApprovedBase(BaseModel):
@@ -59,6 +62,11 @@ class ApprovedBase(BaseModel):
     #: Channel, then variant, to the digest resolution pins. A channel with no
     #: variant is approved and not yet published.
     channels: dict[str, dict[str, str]] = Field(default_factory=dict)
+    #: Channel to the Ubuntu snapshot its apt versions are pinned against
+    #: (D-9): a ``snapshot.ubuntu.com`` id, taken just after the channel's
+    #: image upgraded its packages, so no pin is older than what the image
+    #: already carries. A channel with none pins against the base's mirror.
+    snapshots: dict[str, str] = Field(default_factory=dict)
 
     @field_validator("channels")
     @classmethod
@@ -75,6 +83,17 @@ class ApprovedBase(BaseModel):
             for channel, digests in channels.items()
         }
 
+    @field_validator("snapshots")
+    @classmethod
+    def _snapshot_ids_only(cls, snapshots: dict[str, str]) -> dict[str, str]:
+        for channel, snapshot in snapshots.items():
+            if not _SNAPSHOT.fullmatch(snapshot):
+                raise ValueError(
+                    f"channel {channel!r} pins apt to {snapshot!r}, "
+                    "which is not a snapshot id like 20260914T150000Z"
+                )
+        return snapshots
+
     @property
     def name(self) -> str:
         """The base's name without its namespace: ``python-cpu``."""
@@ -103,6 +122,7 @@ APPROVED_BASES: dict[str, ApprovedBase] = {
                     "sha256:cd09308a0c5e5adeec7fb5d8d29cf7455e78ba86f5c6c095a79068a280e1254f",
                 )
             },
+            snapshots={"2026.09": "20260914T150000Z"},
         ),
         # E2-17: jupyter-python-cuda plus the same layer.
         ApprovedBase(
@@ -180,6 +200,14 @@ def resolve_base(
     return digest
 
 
+def channel_snapshot(
+    ref: str, channel: str, bases: dict[str, ApprovedBase] = APPROVED_BASES
+) -> str:
+    """The Ubuntu snapshot ``ref`` at ``channel`` pins apt against, or ``""`` for none (D-9)."""
+    base = bases.get(ref)
+    return "" if base is None else base.snapshots.get(channel, "")
+
+
 def approved_repositories(bases: dict[str, ApprovedBase] = APPROVED_BASES) -> tuple[str, ...]:
     """Every repository name an approved base is published under."""
     names: list[str] = []