docker-devkit 0.1.17__tar.gz → 0.1.18__tar.gz

{docker_devkit-0.1.17 → docker_devkit-0.1.18}/AGENTS.md

@@ -2,7 +2,7 @@
 
 ## What this is
 
-`docker-devkit` owns the Docker-stack lifecycle commands — `up`, `down`, `build` — plus the helpers they share (`detect_gpu`, `modes`, `context_sha`). It is a small, generic package that any repo shipping a compose graph can depend on to get the same bring-up/tear-down / cross-build flow, with the compose assembly declared per consumer in `[tool.docker-devkit.lifecycle]` so a repo that authors its own images and a repo that only OCI-includes an upstream artifact both work through the same commands.
+`docker-devkit` owns the Docker-stack lifecycle commands — `up`, `down`, `build`, `mirror` — plus the helpers they share (`detect_gpu`, `modes`, `context_sha`). It is a small, generic package that any repo shipping a compose graph can depend on to get the same bring-up/tear-down / cross-build flow, with the compose assembly declared per consumer in `[tool.docker-devkit.lifecycle]` so a repo that authors its own images and a repo that only OCI-includes an upstream artifact both work through the same commands.
 
 The package is `docker_devkit` (src-layout under `src/docker_devkit/`); all dependencies resolve from PyPI (`bashrun>=0.1.0`; git-source pins only in scratch branches testing unreleased changes). The repo and package renamed twice on the way here — `stack-lifecycle` → `stack-toolkit` (2026-09-20, before any publish) and `stack-toolkit` → `docker-devkit` (2026-09-21, member of the `-devkit` family). The PyPI identity is fresh: `docker-devkit` starts its own tag ledger at `0.1.0`; the terminal `stack-toolkit` distributions (≤0.1.1) are deprecation signposts pointing here, not this package's history.
 
@@ -12,13 +12,13 @@ Publishing rides `release.yml`, triggered by a successful CI run on a `main` pus
 
 ## Shape
 
-Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:app`, `build` → `build_docker.py:app`, `generate-score` → `score_generate.py:app`. All accept `--help`.
+Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:app`, `build` → `build_docker.py:app`, `mirror` → `mirror.py:app`, `generate-score` → `score_generate.py:app`. All accept `--help`.
 
 | Module | Role |
 |---|---|
-| `up.py` | `docker compose up`. Flags: `--attached`/`-a`, `--quiet-pull`/`-q`, `--build`, `--gpu auto\|cuda\|rocm\|none`, `--dev`. |
+| `up.py` | `docker compose up`. Flags: `--attached`/`-a`, `--quiet-pull`/`-q`, `--build`, `--gpu auto\|cuda\|rocm\|none`, `--dev`, `--allow-upstream-fallback`. |
 | `down.py` | `docker compose down`. Flags: `--volumes`/`-v` (also removes named volumes), `--gpu`. |
-| `build_docker.py` | `run_build()` + the `build` command — cross-builds all images per the resolved image manifest, writing the paired lock (one `NAME=path:tag@sha256:…` entry per `x-base-images` declaration; `@digest`-pinned declarations pass through unresolved). `--mode ci` hard-requires `x-registry-cache` in the manifest. |
+| `build_docker.py` | `run_build()` + the `build` command — cross-builds all images per the resolved image manifest, writing the paired lock (one `NAME=path:tag@sha256:…` entry per `x-base-images` declaration; `@digest`-pinned declarations pass through unresolved; mirror-prefixed declarations resolve their digest against the upstream reference). `--mode ci` hard-requires `x-registry-cache` in the manifest. |
 | `score_generate.py` | `generate-score` — deterministic Score-manifest generation from a consumer's `stack/score/` sources: `${ALL_CAPS}` placeholder expansion into tempdir-rendered workload copies, idempotent `score-compose`/`score-k8s` init (state preserved across runs), and a determinism suite (document sort, state-path normalisation, 0644 modes, LF newlines). Consumer policy — workloads, provisioners, patch templates, output paths, storage classes, publishes, tool versions — is declared in the consumer's root `pyproject.toml` under `[tool.docker-devkit.generate-score]` (`ScoreConfig`); `load_score_config()` reads it, `ensure_score_tools()` fetches the pinned score-compose/score-k8s release binaries (for CI staleness gates). Output and state paths resolve against the repo root: the compose half runs in `score_dir` (its `.score-compose` state stays there, gitignored), the k8s half runs in the configured `k8s_state` parent so the committed `.score-k8s` state lands in the generated tier. `--local` writes the k8s artifact to the configured gitignored local path with the local storage class. |
 | `lifecycle.py` | `LifecycleConfig` — the `[tool.docker-devkit.lifecycle]` declaration (`files`: compose files in layering order with `{gpu}` templating; `dev_file`: optional dev overlay); `load_lifecycle_config()` (walks `tool → docker-devkit → lifecycle`, `None` when absent), `resolve_manifest()` / `require_manifest()` (the raising form) / `resolve_lock()` (the image manifest and its lock are a named pair — `workloads/images.yml` + `workloads/images.lock`, with the legacy root `compose.bake.yml` + `.env.lock` pair still resolved so repos can upgrade before moving files), `enforce_bake_declaration()` (a manifest under either name requires a declaration), `expand_compose_files()` (assembles the `-f` list; a `{gpu}` entry is dropped when the GPU resolves to `none`; `dev_file` appended when a dev overlay applies). |
 | `detect_gpu.py` | `detect_gpu()` → `cuda`/`rocm`/`none` from host devices; the `Gpu` literal. |
@@ -26,6 +26,7 @@ Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:ap
 | `context_sha.py` | `compute_service_shas(repo_root, bake: BakeDocument)` — per-service `tree-<hash>` image tags over the `.dockerignore`-allowlisted git tree. The workload-tree root is derived as the single top-level directory containing every tagged service's Dockerfile (a bake graph spanning several top-level directories is a loud error); files under it that belong to no tagged service are excluded from every SHA rather than shared into all of them. |
 | `documents.py` | `BakeDocument` + `parse_bake(path)` — the typed bake-file model every consumer of bake data goes through (build, up, down, generate-score, the reference collectors). A field validator enforces at parse time that every `x-base-images` value is `path:tag` or `path@digest` (a `${…}` hole or a bare path is a validation error, killing the silent-unpinned `FROM` → `:latest` failure mode). `digest_pinned(reference)` is the shared tail test. |
 | `image_refs.py` | Image-reference collection, split by source. `declared_references(root)` enumerates bake `x-base-images` declarations from `workloads/images.yml` and the legacy `compose*.bake.yml` names (parsed and validated via `BakeDocument`) — the single source consumer mirroring consumes. `stray_references(root, …globs)` scans Dockerfile `FROM`, Dockerfile `COPY --from=` (slash-bearing captures only, so build-stage names are skipped), and yaml `image:` lines — hand-written literal refs that bypass the declaration system — across the `workloads/` and `docker/` Dockerfile trees and the `stack/score/` + `score/` source trees; `unpinned_references(root)` polices exactly those strays (every slash-bearing reference must carry a tag, a digest, or a trailing `${build-arg}` suffix — consumer CIs fail on its result). `bake_base_image_refs(bake: BakeDocument)` adapts declarations to `ImageReference` pairs; `version_coupling_violations(root, couplings)` (each `VersionCoupling` names a pyproject-declared version and the `VersionSite` regexes that must restate it — bake `x-base-images` values or raw file text — so non-derivable couplings like uv `required-version` ↔ uv-base-image tag can't drift silently; the mechanism lives here, the registry in consumer repos' preflight) is unchanged. Remote digest resolution goes through `imagetools inspect`. Compose files are parsed by nothing in this package. |
+| `mirror.py` | The mirror namespace's config, inversion, and verbs. `MirrorConfig` (`[tool.docker-devkit.mirror]`, key `prefix`), `load_mirror_config()` (walks `tool → docker-devkit → mirror`, `None` when absent), `is_mirrored`/`upstream_ref` (prefix inversion preserving the `:tag@sha256:…` tail), `reference_exists` (imagetools existence probe honoring docker config creds), `mirror_targets` (declared refs filtered by prefix, sorted), the `mirror` verb (crane install + per-target `crane copy`), and `up`'s fallback helpers (`upstream_fallback`, `write_fallback_overlay`). Constraints in "Mirror namespace and upstream fallback". |
 
 ## Constraints
 
@@ -47,6 +48,18 @@ Entry points (`[project.scripts]`): `up` → `up.py:app`, `down` → `down.py:ap
 
 `build` injects the `tree-<hash>` tags of locally-built images into the environment rather than writing them anywhere; `up`/`down` do the same via `compute_service_shas`. The lock stays a pure third-party pin file — a CI invariant forbids built-image digests in the committed, reviewed lock.
 
+### Mirror namespace and upstream fallback
+
+**Context.** Third-party images are consumed through an org-owned mirror namespace (`ghcr.io/outernet-foundation/mirror/<upstream-host>/<path>…`) instead of pulling upstream registries directly: manifests at upstream get GC'd, and an upstream yank once broke external cloners — digest pins alone don't save you when the manifest is gone. Durability for strangers beats upstream egress: strangers, CI, and prod always pull the mirror. Populating it is CI's job, single writer — engineers never push to the org namespace, and error text must never teach them to (no "run this populate command" hints).
+
+**Constraint.** The mirror is declared, not inferred: `[tool.docker-devkit.mirror]` with `prefix` in the consumer's root pyproject. Absent table → all mirror behavior off; `up`/`build` behave exactly as they did before it existed. Under the table:
+
+- `build` resolves lock digests for mirror-prefixed declarations against the upstream reference (prefix stripped, tag/digest tail preserved) and records them under the mirror name. Valid because `crane copy` produces byte-identical manifests — upstream and mirror digests are the same digest; a manifest re-wrap (`docker buildx imagetools`-shaped tooling) would change the top-level digest and break lock equality. This makes declare → re-lock walkable before CI has mirrored anything; lock lines are never hand-authored.
+- `up` fails closed: after lock resolution it probes each mirror-prefixed lock entry; a missing mirror image is a hard `RuntimeError`, not a warning — people ignore warnings, and warnings are errors someone was too lazy to fix. The only escape is the per-run `--allow-upstream-fallback` flag. Under the flag, missing entries become digest-preserving address substitutions (same bytes from the upstream host), printed as plain statements — the operator asked for fallback, the run reports what it did. The rewrite is authoritative on both consumption paths: an appended `--env-file` overlay (compose's later env files win) plus `os.environ` before `build`'s bake (shell env wins over env files; `run_build` re-applies the overlay after its own lock update so bake is never clobbered). CI never passes the flag — the mirror job runs before anything needs the images.
+- The `mirror` verb (crane install from a pinned release, per-target `crane copy`, count footer) uses bashrun + plain prints, deliberately not ci-devkit's `ci_step`: docker-devkit and ci-devkit are siblings in the dependency DAG and the mirror verb is the only thing that would ever draw that edge. Zero new dependencies is a hard rule.
+
+**Consequences.** Non-mirror lock entries (e.g. `placeframe/*` publishes) are not probed and keep failing naturally at pull. There is no config-level ban on the flag: an air-gap fails closed anyway (no route to upstream — the pull dies with or without it).
+
 ### Package split rationale
 
 Lifecycle (`up`/`down`/`build`) and codegen (client generation, datamodel generation, workspace locking) have disjoint dependency surfaces. Bundling them would force a consumer that only brings a stack up to install `sqlacodegen`, `psycopg`, `datamodel-code-generator`. Keeping the lifecycle in its own small package lets consumers git-reference just this without dragging the codegen surface behind it.

{docker_devkit-0.1.17 → docker_devkit-0.1.18}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: docker-devkit
-Version: 0.1.17
+Version: 0.1.18
 Summary: Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly
 License-File: LICENSE
 License-File: NOTICE

{docker_devkit-0.1.17 → docker_devkit-0.1.18}/README.md

@@ -21,14 +21,18 @@ uv run up                      # docker compose up (auto-detects GPU; assembles
 uv run up --dev                # layer the declared dev overlay (bind-mount/debug bring-up)
 uv run up --build              # build images locally first (requires workloads/images.yml)
 uv run up --gpu none           # override GPU auto-detection
+uv run up --allow-upstream-fallback  # per-run escape: pull unmirrored lock entries from upstream at the same digest
 uv run down                    # docker compose down
 uv run down -v                 # also remove named volumes
 uv run build                   # cross-build all images per workloads/images.yml
 uv run build --lock-only       # refresh the image lock without building
+uv run mirror                  # populate the org mirror namespace from mirror-prefixed declarations (CI)
 uv run generate-score          # regenerate Score compose/k8s manifests per [tool.docker-devkit.generate-score]
 uv run generate-score --local  # local-cluster variant (local storage class, gitignored output)
 ```
 
+Repos that consume third-party images through the org mirror namespace declare `[tool.docker-devkit.mirror]` (`prefix = "ghcr.io/outernet-foundation/mirror"`); `up` then fails closed on any lock entry not mirrored yet, and `build` resolves lock digests against upstream. See the "Mirror namespace and upstream fallback" section in [`AGENTS.md`](./AGENTS.md).
+
 ## Consuming from another repo
 
 Install from PyPI and use its entry points:

{docker_devkit-0.1.17 → docker_devkit-0.1.18}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "docker-devkit"
-version = "0.1.17"
+version = "0.1.18"
 description = "Docker-stack lifecycle commands (up/down/build) driven by a pyproject-declared compose assembly"
 requires-python = ">=3.13"
 dependencies = [
@@ -28,6 +28,7 @@ build-backend = "hatchling.build"
 up = "docker_devkit.up:app"
 down = "docker_devkit.down:app"
 build = "docker_devkit.build_docker:app"
+mirror = "docker_devkit.mirror:app"
 generate-score = "docker_devkit.score_generate:app"
 
 [tool.hatch.build.targets.wheel]

{docker_devkit-0.1.17 → docker_devkit-0.1.18}/src/docker_devkit/build_docker.py

@@ -17,6 +17,7 @@ from .context_sha import compute_service_shas
 
 from .image_refs import bake_base_image_refs, resolve_remote_digest
 from .lifecycle import require_manifest, resolve_lock
+from .mirror import is_mirrored, load_mirror_config, upstream_ref
 from .modes import parse_env_file
 
 
@@ -71,10 +72,12 @@ def run_build(
     gpu_only: bool = False,
     no_cache: bool = False,
     targets_opt: list[str] | None = None,
+    env_overlay: dict[str, str] | None = None,
 ) -> None:
     root = Path.cwd()
     manifest = require_manifest(root)
     lock_file = resolve_lock(root, manifest)
+    mirror_config = load_mirror_config(root)
 
     bake = parse_bake(manifest)
 
@@ -103,6 +106,9 @@ def run_build(
         gpu = detect_gpu()
 
     # One lock entry per declared third-party image: NAME=path:tag@sha256:…
+    # Mirror-prefixed declarations resolve their digest against upstream (crane copies
+    # are byte-identical, so the digest is valid under both names) and record it under
+    # the mirror name — declaring and re-locking works before CI has mirrored anything.
     for occurrence in bake_base_image_refs(bake):
         if digest_pinned(occurrence.reference):
             lock_data[occurrence.name] = occurrence.reference
@@ -113,7 +119,10 @@ def run_build(
             and lock_data[occurrence.name].startswith(occurrence.reference + "@")
         ):
             continue
-        lock_data[occurrence.name] = f"{occurrence.reference}@{resolve_remote_digest(occurrence.reference)}"
+        inspect_target = occurrence.reference
+        if mirror_config is not None and is_mirrored(occurrence.reference, mirror_config.prefix):
+            inspect_target = upstream_ref(occurrence.reference, mirror_config.prefix)
+        lock_data[occurrence.name] = f"{occurrence.reference}@{resolve_remote_digest(inspect_target)}"
 
     # Update main lock file
     lock_file.write_text(
@@ -126,6 +135,8 @@ def run_build(
 
     # Update environment with external dependency image digests
     os.environ.update(lock_data)
+    if env_overlay:
+        os.environ.update(env_overlay)
 
     # Build command arguments
     command_arguments: list[str] = []

docker_devkit-0.1.18/src/docker_devkit/mirror.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import os
+import shlex
+import tempfile
+import tomllib
+from pathlib import Path
+
+import typer
+from bashrun.bash import bash, bash_check
+from pydantic import BaseModel, ConfigDict, field_validator
+
+from .image_refs import ImageReference, declared_references
+
+app = typer.Typer(add_completion=False, pretty_exceptions_show_locals=False)
+
+CRANE_VERSION = "v0.22.1"
+
+
+class MirrorConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    prefix: str
+
+    @field_validator("prefix")
+    @classmethod
+    def _require_bare_prefix(cls, prefix: str) -> str:
+        if not prefix or prefix.endswith("/"):
+            raise ValueError("mirror prefix must be non-empty and carry no trailing slash")
+        return prefix
+
+
+@app.command()
+def mirror() -> None:
+    root = Path.cwd()
+    config = load_mirror_config(root)
+    if config is None:
+        raise RuntimeError("[tool.docker-devkit.mirror] with 'prefix' is required to mirror")
+
+    targets = mirror_targets(root, config.prefix)
+    print(f"Install crane {CRANE_VERSION}")
+    sudo = "sudo " if os.geteuid() != 0 else ""
+    archive = "go-containerregistry_Linux_x86_64.tar.gz"
+    bash(f"curl -fsSLO https://github.com/google/go-containerregistry/releases/download/{CRANE_VERSION}/{archive}")
+    bash(f"{sudo}tar -xzf {archive} -C /usr/local/bin crane")
+    Path(archive).unlink()
+    for target in targets:
+        upstream = upstream_ref(target.reference, config.prefix)
+        print(f"Mirror {upstream} -> {target.reference}")
+        bash(f"crane copy {upstream} {target.reference}")
+    print(f"Mirrored images: {len(targets)}")
+
+
+def load_mirror_config(root: Path) -> MirrorConfig | None:
+    pyproject_path = root / "pyproject.toml"
+    if not pyproject_path.exists():
+        return None
+    data = tomllib.loads(pyproject_path.read_text(encoding="utf-8"))
+    section = data.get("tool", {}).get("docker-devkit", {}).get("mirror")
+    if section is None:
+        return None
+    return MirrorConfig.model_validate(section)
+
+
+def is_mirrored(reference: str, prefix: str) -> bool:
+    return reference.startswith(f"{prefix}/")
+
+
+def upstream_ref(reference: str, prefix: str) -> str:
+    return reference[len(prefix) + 1 :]
+
+
+def reference_exists(reference: str) -> bool:
+    return bash_check(f"docker buildx imagetools inspect {shlex.quote(reference)}")
+
+
+def mirror_targets(root: Path, prefix: str) -> list[ImageReference]:
+    return sorted(
+        (occurrence for occurrence in declared_references(root) if is_mirrored(occurrence.reference, prefix)),
+        key=lambda occurrence: occurrence.reference,
+    )
+
+
+def upstream_fallback(lock_data: dict[str, str], prefix: str, *, allow_upstream_fallback: bool) -> dict[str, str]:
+    missing = {
+        name: value for name, value in lock_data.items() if is_mirrored(value, prefix) and not reference_exists(value)
+    }
+    if not missing:
+        return {}
+    if not allow_upstream_fallback:
+        value = next(iter(missing.values()))
+        reference, _, digest = value.rpartition("@")
+        raise RuntimeError(
+            f"Image {reference or value} (digest {digest or 'unknown'}) is not mirrored yet. "
+            "If this is a new upstream dependency that has not been through CI, pass --allow-upstream-fallback "
+            "to pull the same digest from upstream for this run."
+        )
+    return {name: upstream_ref(value, prefix) for name, value in missing.items()}
+
+
+def write_fallback_overlay(substitutions: dict[str, str]) -> Path:
+    overlay = Path(tempfile.gettempdir()) / f"docker-devkit-upstream-fallback-{os.getpid()}.env"
+    overlay.write_text(
+        "\n".join(f"{name}={value}" for name, value in sorted(substitutions.items())) + "\n",
+        encoding="utf-8",
+    )
+    return overlay
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

{docker_devkit-0.1.17 → docker_devkit-0.1.18}/src/docker_devkit/up.py

@@ -16,7 +16,8 @@ from .lifecycle import (
     resolve_lock,
     resolve_manifest,
 )
-from .modes import resolve_auth_mode
+from .mirror import load_mirror_config, upstream_fallback, write_fallback_overlay
+from .modes import parse_env_file, resolve_auth_mode
 
 ENV_FILE = Path(".env")
 
@@ -41,6 +42,13 @@ def up(
         "--dev",
         help="Layer the declared dev overlay (compose.dev.yml shape) over the production stack for bind-mount/debug bring-up.",
     ),
+    allow_upstream_fallback: Annotated[
+        bool,
+        typer.Option(
+            "--allow-upstream-fallback",
+            help="Pull unmirrored lock entries from upstream at the same digest instead of failing closed.",
+        ),
+    ] = False,
 ) -> None:
     root = Path.cwd()
     config = load_lifecycle_config(root)
@@ -67,8 +75,21 @@ def up(
 
     auth_mode = resolve_auth_mode(ENV_FILE)
 
+    substitutions: dict[str, str] = {}
+    fallback_overlay: Path | None = None
+    mirror_config = load_mirror_config(root)
+    if mirror_config is not None:
+        substitutions = upstream_fallback(
+            parse_env_file(lock_file), mirror_config.prefix, allow_upstream_fallback=allow_upstream_fallback
+        )
+        if substitutions:
+            for name, upstream in sorted(substitutions.items()):
+                print(f"Falling back to upstream for {name}: {upstream}", flush=True)
+            os.environ.update(substitutions)
+            fallback_overlay = write_fallback_overlay(substitutions)
+
     if build:
-        run_build(gpu=gpu)
+        run_build(gpu=gpu, env_overlay=substitutions)
 
     if manifest is not None:
         os.environ.update(compute_service_shas(root, parse_bake(manifest)))
@@ -80,6 +101,8 @@ def up(
     files_args = " ".join(f"-f {compose_file}" for compose_file in compose_files)
     profile_flag = "--profile keycloak " if auth_mode == "keycloak" else ""
     compose_args = f"{files_args} {profile_flag}--project-directory {root} --env-file .env --env-file {lock_file}"
+    if fallback_overlay is not None:
+        compose_args += f" --env-file {fallback_overlay}"
 
     up_command = f"docker compose {compose_args} up"
     if not build:

docker_devkit-0.1.18/tests/test_mirror.py

@@ -0,0 +1,356 @@
+import os
+import tempfile
+from pathlib import Path
+
+import pytest
+from pydantic import ValidationError
+from typer.testing import CliRunner
+
+from docker_devkit import build_docker, mirror
+from docker_devkit.documents import BakeDocument
+from docker_devkit.image_refs import ImageReference
+from docker_devkit.mirror import MirrorConfig
+
+MIRROR_PREFIX = "ghcr.io/outernet-foundation/mirror"
+FAKE_DIGEST = "sha256:" + "a" * 64
+
+MIRROR_REFERENCES = [
+    f"{MIRROR_PREFIX}/docker.io/library/python:3.13-slim@{FAKE_DIGEST}",
+    f"{MIRROR_PREFIX}/ghcr.io/astral-sh/uv:0.12.15-python3.13-trixie-slim",
+    f"{MIRROR_PREFIX}/quay.io/keycloak/keycloak:26.3.5@{FAKE_DIGEST}",
+    f"{MIRROR_PREFIX}/docker.io/livekit/livekit-server:v1.12.0@{FAKE_DIGEST}",
+]
+
+MANIFEST = (
+    "x-base-images:\n"
+    f"  UV_IMAGE: {MIRROR_PREFIX}/ghcr.io/astral-sh/uv:0.12.15\n"
+    "  API_IMAGE: ghcr.io/outernet-foundation/placeframe/api:1.2.3\n"
+    "services:\n"
+    "  api:\n"
+    "    build:\n"
+    "      dockerfile: workloads/api/Dockerfile\n"
+    "      tags:\n"
+    "        - localhost:5000/api:${API_SHA}\n"
+)
+
+LOCKED_ERROR = (
+    f"Image {MIRROR_PREFIX}/docker.io/library/alpine:3.20 (digest {FAKE_DIGEST}) is not mirrored yet. "
+    "If this is a new upstream dependency that has not been through CI, pass --allow-upstream-fallback "
+    "to pull the same digest from upstream for this run."
+)
+
+runner = CliRunner()
+
+
+class SelectiveExistence:
+    def __init__(self, present: str) -> None:
+        self.present = present
+        self.probed: list[str] = []
+
+    def exists(self, reference: str) -> bool:
+        self.probed.append(reference)
+        return reference == self.present
+
+
+class BashCheckRecorder:
+    def __init__(self, *, exists: bool) -> None:
+        self.exists = exists
+        self.commands: list[str] = []
+
+    def check(self, command: str) -> bool:
+        self.commands.append(command)
+        return self.exists
+
+
+class CommandRecorder:
+    def __init__(self) -> None:
+        self.commands: list[str] = []
+
+    def run(self, command: str) -> None:
+        self.commands.append(command)
+        if command.startswith("curl"):
+            Path("go-containerregistry_Linux_x86_64.tar.gz").write_text("", encoding="utf-8")
+
+
+class DigestRecorder:
+    def __init__(self) -> None:
+        self.inspected: list[str] = []
+
+    def resolve(self, reference: str) -> str:
+        self.inspected.append(reference)
+        return FAKE_DIGEST
+
+
+class BakeEnvProbe:
+    def __init__(self) -> None:
+        self.uv_image: str | None = None
+
+    def run(self, command: str) -> None:
+        self.uv_image = os.environ.get("UV_IMAGE")
+        Path("metadata.json").write_text('{"api": {}}', encoding="utf-8")
+
+
+def _always_true(reference: str) -> bool:
+    return True
+
+
+def _bash_check_false(command: str) -> bool:
+    return False
+
+
+def _must_not_be_probed(reference: str) -> bool:
+    raise AssertionError(f"unexpected existence probe: {reference}")
+
+
+def _no_service_shas(root: Path, bake: BakeDocument) -> dict[str, str]:
+    return {}
+
+
+def _no_gc_limits(min_gb: int = 60) -> None:
+    return None
+
+
+def _fixed_digest(reference: str) -> str:
+    return FAKE_DIGEST
+
+
+class TestInversion:
+    @pytest.mark.parametrize("reference", MIRROR_REFERENCES)
+    def test_round_trips_through_the_prefix(self, reference: str):
+        assert mirror.is_mirrored(reference, MIRROR_PREFIX)
+        assert f"{MIRROR_PREFIX}/{mirror.upstream_ref(reference, MIRROR_PREFIX)}" == reference
+
+    @pytest.mark.parametrize("reference", MIRROR_REFERENCES)
+    def test_preserves_tag_and_digest_tail(self, reference: str):
+        assert mirror.upstream_ref(reference, MIRROR_PREFIX).rpartition("/")[2] == reference.rpartition("/")[2]
+
+    def test_dockerio_path_maps_to_fully_qualified_upstream(self):
+        reference = f"{MIRROR_PREFIX}/docker.io/livekit/livekit-server:v1.12.0@{FAKE_DIGEST}"
+        assert (
+            mirror.upstream_ref(reference, MIRROR_PREFIX) == f"docker.io/livekit/livekit-server:v1.12.0@{FAKE_DIGEST}"
+        )
+
+    def test_prefix_boundary_requires_slash(self):
+        assert not mirror.is_mirrored(f"{MIRROR_PREFIX}-evil/docker.io/library/alpine:3.20", MIRROR_PREFIX)
+
+    def test_publish_entries_are_not_mirrored(self):
+        assert not mirror.is_mirrored("ghcr.io/outernet-foundation/placeframe/api:1.2.3", MIRROR_PREFIX)
+
+
+class TestLoadMirrorConfig:
+    def test_loads_declared_prefix(self, tmp_path: Path):
+        (tmp_path / "pyproject.toml").write_text(
+            f"[tool.docker-devkit.mirror]\nprefix = '{MIRROR_PREFIX}'\n", encoding="utf-8"
+        )
+
+        assert mirror.load_mirror_config(tmp_path) == MirrorConfig(prefix=MIRROR_PREFIX)
+
+    def test_absent_table_returns_none(self, tmp_path: Path):
+        (tmp_path / "pyproject.toml").write_text("[tool.docker-devkit.lifecycle]\nfiles = []\n", encoding="utf-8")
+
+        assert mirror.load_mirror_config(tmp_path) is None
+
+    def test_missing_pyproject_returns_none(self, tmp_path: Path):
+        assert mirror.load_mirror_config(tmp_path) is None
+
+    def test_rejects_unknown_keys(self, tmp_path: Path):
+        (tmp_path / "pyproject.toml").write_text(
+            "[tool.docker-devkit.mirror]\nprefix = 'ghcr.io/x/mirror'\nbogus = true\n", encoding="utf-8"
+        )
+
+        with pytest.raises(ValidationError):
+            mirror.load_mirror_config(tmp_path)
+
+    def test_rejects_trailing_slash_prefix(self, tmp_path: Path):
+        (tmp_path / "pyproject.toml").write_text(
+            "[tool.docker-devkit.mirror]\nprefix = 'ghcr.io/x/mirror/'\n", encoding="utf-8"
+        )
+
+        with pytest.raises(ValidationError):
+            mirror.load_mirror_config(tmp_path)
+
+
+class TestMirrorTargets:
+    def test_filters_declared_references_by_prefix_and_sorts(self, tmp_path: Path):
+        (tmp_path / "workloads").mkdir()
+        (tmp_path / "workloads" / "images.yml").write_text(MANIFEST, encoding="utf-8")
+
+        assert mirror.mirror_targets(tmp_path, MIRROR_PREFIX) == [
+            ImageReference("UV_IMAGE", f"{MIRROR_PREFIX}/ghcr.io/astral-sh/uv:0.12.15")
+        ]
+
+
+class TestReferenceExists:
+    def test_probes_with_imagetools_inspect(self, monkeypatch: pytest.MonkeyPatch):
+        recorder = BashCheckRecorder(exists=True)
+        monkeypatch.setattr(mirror, "bash_check", recorder.check)
+
+        assert mirror.reference_exists("docker.io/library/alpine:3.20")
+        assert recorder.commands == ["docker buildx imagetools inspect docker.io/library/alpine:3.20"]
+
+    def test_returns_false_for_failed_probe(self, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.setattr(mirror, "bash_check", _bash_check_false)
+
+        assert not mirror.reference_exists("docker.io/library/alpine:3.20")
+
+
+class TestUpstreamFallback:
+    def test_fails_closed_with_the_locked_message(self, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.setattr(mirror, "reference_exists", _bash_check_false)
+        lock_data = {"ALPINE_IMAGE": f"{MIRROR_PREFIX}/docker.io/library/alpine:3.20@{FAKE_DIGEST}"}
+
+        with pytest.raises(RuntimeError) as excinfo:
+            mirror.upstream_fallback(lock_data, MIRROR_PREFIX, allow_upstream_fallback=False)
+
+        assert str(excinfo.value) == LOCKED_ERROR
+
+    def test_flag_substitutes_exactly_the_missing_entries(self, monkeypatch: pytest.MonkeyPatch):
+        present = f"{MIRROR_PREFIX}/ghcr.io/astral-sh/uv:0.12.15"
+        absent = f"{MIRROR_PREFIX}/docker.io/library/alpine:3.20@{FAKE_DIGEST}"
+        existence = SelectiveExistence(present)
+        monkeypatch.setattr(mirror, "reference_exists", existence.exists)
+        lock_data = {
+            "UV_IMAGE": present,
+            "ALPINE_IMAGE": absent,
+            "API_IMAGE": "ghcr.io/outernet-foundation/placeframe/api:1.2.3",
+        }
+
+        substitutions = mirror.upstream_fallback(lock_data, MIRROR_PREFIX, allow_upstream_fallback=True)
+
+        assert substitutions == {"ALPINE_IMAGE": f"docker.io/library/alpine:3.20@{FAKE_DIGEST}"}
+        assert existence.probed == [present, absent]
+
+    def test_returns_empty_when_everything_is_mirrored(self, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.setattr(mirror, "reference_exists", _always_true)
+        lock_data = {"ALPINE_IMAGE": f"{MIRROR_PREFIX}/docker.io/library/alpine:3.20@{FAKE_DIGEST}"}
+
+        assert mirror.upstream_fallback(lock_data, MIRROR_PREFIX, allow_upstream_fallback=False) == {}
+
+    def test_non_mirror_entries_are_never_probed(self, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.setattr(mirror, "reference_exists", _must_not_be_probed)
+        lock_data = {"API_IMAGE": "ghcr.io/outernet-foundation/placeframe/api:1.2.3"}
+
+        assert mirror.upstream_fallback(lock_data, MIRROR_PREFIX, allow_upstream_fallback=True) == {}
+
+
+class TestWriteFallbackOverlay:
+    def test_writes_sorted_entries_under_a_pid_named_tempfile(self):
+        substitutions = {
+            "UV_IMAGE": "ghcr.io/astral-sh/uv:0.12.15",
+            "ALPINE_IMAGE": f"docker.io/library/alpine:3.20@{FAKE_DIGEST}",
+        }
+
+        overlay = mirror.write_fallback_overlay(substitutions)
+
+        assert overlay.parent == Path(tempfile.gettempdir())
+        assert overlay.name == f"docker-devkit-upstream-fallback-{os.getpid()}.env"
+        assert overlay.read_text(encoding="utf-8") == (
+            f"ALPINE_IMAGE=docker.io/library/alpine:3.20@{FAKE_DIGEST}\nUV_IMAGE=ghcr.io/astral-sh/uv:0.12.15\n"
+        )
+
+
+class TestMirrorVerb:
+    def _write_tree(self, tmp_path: Path) -> None:
+        (tmp_path / "pyproject.toml").write_text(
+            f"[tool.docker-devkit.mirror]\nprefix = '{MIRROR_PREFIX}'\n", encoding="utf-8"
+        )
+        (tmp_path / "workloads").mkdir()
+        (tmp_path / "workloads" / "images.yml").write_text(MANIFEST, encoding="utf-8")
+
+    def test_copies_each_mirror_target_from_upstream(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        recorder = CommandRecorder()
+        monkeypatch.setattr(mirror, "bash", recorder.run)
+        monkeypatch.chdir(tmp_path)
+        self._write_tree(tmp_path)
+
+        result = runner.invoke(mirror.app, [])
+
+        assert result.exit_code == 0
+        assert [command for command in recorder.commands if command.startswith("crane copy")] == [
+            f"crane copy ghcr.io/astral-sh/uv:0.12.15 {MIRROR_PREFIX}/ghcr.io/astral-sh/uv:0.12.15"
+        ]
+        assert "Mirrored images: 1" in result.stdout
+
+    def test_errors_without_mirror_table(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        monkeypatch.chdir(tmp_path)
+
+        result = runner.invoke(mirror.app, [])
+
+        assert result.exit_code != 0
+        assert isinstance(result.exception, RuntimeError)
+
+
+class TestUpstreamAwareLockResolution:
+    def _write_tree(self, tmp_path: Path, *, mirror_table: bool) -> None:
+        table = f"[tool.docker-devkit.mirror]\nprefix = '{MIRROR_PREFIX}'\n" if mirror_table else ""
+        (tmp_path / "pyproject.toml").write_text(f"[project]\nname = 'stack'\n\n{table}", encoding="utf-8")
+        (tmp_path / "workloads").mkdir()
+        (tmp_path / "workloads" / "images.yml").write_text(MANIFEST, encoding="utf-8")
+
+    def test_resolves_mirror_declarations_against_upstream(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        self._write_tree(tmp_path, mirror_table=True)
+        monkeypatch.chdir(tmp_path)
+        recorder = DigestRecorder()
+        monkeypatch.setattr(build_docker, "resolve_remote_digest", recorder.resolve)
+        monkeypatch.setattr(build_docker, "compute_service_shas", _no_service_shas)
+
+        build_docker.run_build(lock_only=True)
+
+        assert recorder.inspected == [
+            "ghcr.io/astral-sh/uv:0.12.15",
+            "ghcr.io/outernet-foundation/placeframe/api:1.2.3",
+        ]
+        lock = (tmp_path / "workloads" / "images.lock").read_text(encoding="utf-8")
+        assert f"API_IMAGE=ghcr.io/outernet-foundation/placeframe/api:1.2.3@{FAKE_DIGEST}" in lock
+        assert f"UV_IMAGE={MIRROR_PREFIX}/ghcr.io/astral-sh/uv:0.12.15@{FAKE_DIGEST}" in lock
+
+    def test_without_table_inspects_the_declared_reference(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        self._write_tree(tmp_path, mirror_table=False)
+        monkeypatch.chdir(tmp_path)
+        recorder = DigestRecorder()
+        monkeypatch.setattr(build_docker, "resolve_remote_digest", recorder.resolve)
+        monkeypatch.setattr(build_docker, "compute_service_shas", _no_service_shas)
+
+        build_docker.run_build(lock_only=True)
+
+        assert recorder.inspected == [
+            f"{MIRROR_PREFIX}/ghcr.io/astral-sh/uv:0.12.15",
+            "ghcr.io/outernet-foundation/placeframe/api:1.2.3",
+        ]
+
+
+class TestBakeConsumesEnvOverlay:
+    def _write_tree(self, tmp_path: Path) -> None:
+        (tmp_path / "pyproject.toml").write_text(
+            f"[project]\nname = 'stack'\n\n[tool.docker-devkit.mirror]\nprefix = '{MIRROR_PREFIX}'\n",
+            encoding="utf-8",
+        )
+        (tmp_path / "workloads").mkdir()
+        (tmp_path / "workloads" / "images.yml").write_text(MANIFEST, encoding="utf-8")
+
+    def _fake_bake(self, monkeypatch: pytest.MonkeyPatch) -> BakeEnvProbe:
+        probe = BakeEnvProbe()
+        monkeypatch.setattr(build_docker, "bash", probe.run)
+        monkeypatch.setattr(build_docker, "_check_gc_limits", _no_gc_limits)
+        monkeypatch.setattr(build_docker, "resolve_remote_digest", _fixed_digest)
+        monkeypatch.setattr(build_docker, "compute_service_shas", _no_service_shas)
+        return probe
+
+    def test_overlay_wins_over_lock_values(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        self._write_tree(tmp_path)
+        monkeypatch.chdir(tmp_path)
+        probe = self._fake_bake(monkeypatch)
+        upstream = f"ghcr.io/astral-sh/uv:0.12.15@{FAKE_DIGEST}"
+
+        build_docker.run_build(gpu="none", env_overlay={"UV_IMAGE": upstream})
+
+        assert probe.uv_image == upstream
+
+    def test_without_overlay_bake_sees_mirror_values(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch):
+        self._write_tree(tmp_path)
+        monkeypatch.chdir(tmp_path)
+        probe = self._fake_bake(monkeypatch)
+
+        build_docker.run_build(gpu="none")
+
+        assert probe.uv_image == f"{MIRROR_PREFIX}/ghcr.io/astral-sh/uv:0.12.15@{FAKE_DIGEST}"