fix(cargo-anvil): let a repository with no root toolchain file build the container image (#161)

* fix(cargo-anvil): supply the declared MSRV to the container image build

`anvil-msrv-test-setup` resolves the MSRV by scanning the root `Cargo.toml`,
and `just anvil-setup` reaches it through the PR tier. The container image is
built with no repository source in its context by design, so that scan threw
and the install layer failed. No image was produced, which left every
`anvil-container` recipe unusable after a cold build.

The MSRV is the one version anvil installs that is declared in the source
rather than pinned in `versions.just`, and the image already carries the
repository's other toolchain declaration, `rust-toolchain.toml`. Close that
asymmetry by making the MSRV an image input: `anvil-container-tag` resolves the
declared value through a new `_anvil-resolve-stable root-msrv` action and hashes
it, the build passes it as `ARG ANVIL_ROOT_MSRV`, and the resolver reads it only
when no root manifest is present, so it can never shadow a real declaration.

The value is carried rather than the manifest holding it. Copying `Cargo.toml`
into the context would rename the image on every dependency edit, obliging a
publisher to rebuild and republish for changes that cannot alter a byte the
image contains, while `rust-version` moves perhaps once. A repository that
declares no MSRV sends `none`, which is an answer; an unset variable is not, so
a build that drops the argument stops rather than producing an image silently
missing a toolchain it claims to install.

Validated with a cold image build on Docker 29.7.1: the build completes and
`rustup toolchain list` in the resulting image reports the declared MSRV
alongside the pinned stable and nightlies. Contract tests cover manifest
precedence over the override, the `none` declaration, the refusal when nothing
is declared, and that the tag follows the MSRV while ignoring unrelated
manifest edits.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 80f12d44-5a83-4650-9806-d3e247175858

* refactor(cargo-anvil): let the image read the MSRV instead of being told it

The setup region installs the toolchain named by the repository's declared
MSRV, which lives in the root `Cargo.toml` rather than in `versions.just`.
That value reached the build as `ARG ANVIL_ROOT_MSRV`, resolved on the host
and passed as a build argument, with the resolver reading the variable
whenever it found no manifest.

That channel is fragile in a way the composed Dockerfile makes likely. The
setup region is a documented replacement point, and the `ARG` sat inside it,
so a repository substituting its own region kept receiving the build argument
while silently losing the declaration that receives it. The resulting failure
is `failed to install MSRV toolchain '1.92'`, which sends the reader hunting a
toolchain that is not the problem.

Admit the root manifest to the build context and copy it to `/opt/anvil`
instead. That directory is already the root the recipes resolve against: it is
`justfile_directory()`, and it holds `justfiles/` and the toolchain pin.
Copying the manifest alongside them completes it for the one question the
setup asks, and the resolver reads it there exactly as it does on a
developer's machine.

`tools.just` therefore returns to what it was, minus the new `root-msrv`
action the tag still needs. The variable, its `none` sentinel, its error
message and the `--build-arg` all go away, and with them a general resolver's
knowledge of containers. Dropping the `COPY` now fails with `Cargo.toml not
found at repository root`, which names the missing thing.

The workspace members the manifest lists stay out of the context: they are a
checkout, and the image is not one. The one path that would need them,
workspace MSRV validation, returns early whenever a root toolchain file
selects the compiler, which this image requires and copies.

The tag continues to hash the resolved value rather than the file. The
manifest is the busiest file in a workspace while `rust-version` moves perhaps
once in a repository's life, so hashing it would rename the image, and oblige
a publisher to rebuild and republish, for a stream of edits that cannot alter
a byte the image contains.

Contracts follow the mechanism: the context admits the manifest, the setup
region copies it, and no build argument survives anywhere.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 2963084a-ef08-4cf7-adc6-e78e61556a84

* docs(cargo-anvil): trim the MSRV commentary to what is not inferable

The prose ran about four lines per line of code, well past what the change needs. Keep the reasons a reader cannot recover from the code -- why the value is hashed rather than the manifest, why the members stay out of the context, why the declared value rather than the mapped one -- and drop the restatement around them.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 2963084a-ef08-4cf7-adc6-e78e61556a84

* test(cargo-anvil): pin the toolchain-file precondition the MSRV design rests on

Workspace MSRV validation reads every member manifest, and the build context carries none. It stays out of reach only because a root toolchain file selects the compiler and makes the resolver return early -- which holds today by accident, since the unconditional COPY means a repository without one cannot build an image at all.

Making that COPY conditional is a reasonable fix for those repositories, and it would silently put the branch back in reach of a partial workspace. State the dependency so that change has to confront this one.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 2963084a-ef08-4cf7-adc6-e78e61556a84

* fix(cargo-anvil): let a repository with no root toolchain file build the image

The setup region named `rust-toolchain.toml` in a COPY and the tag recipe listed it as a required input, so a repository that pins its compiler by other means could not build an image at all: the build failed at the first COPY, and `anvil-container-tag` refused before that. `microsoft/oxidizer` is such a repository.

No engine anvil supports offers a portable COPY of a path that may not exist, so the region names no input at all and copies the context whole. The ignore file already scopes that context to precisely the image's inputs, so what it admits and what the image contains become the same set. It now admits both toolchain-file spellings: naming only the TOML would leave a repository that pins with the extensionless file building an image whose compiler silently disagreed with its own checkout.

The tag discovers the file rather than requiring it, in both spellings. Absence is one fewer record in the digest, so the two states cannot share a reference, and the file's mode still comes from the index. The ignore file stays a named, required input for the reason it always was.

The design note this replaces claimed the toolchain file kept workspace MSRV validation out of reach of a memberless context. It does not: that validation hangs off the `-validate-prereqs` recipes, and `anvil-setup` -- the only thing the image runs -- depends on none of them. `just --dry-run anvil-setup binstall` reaches `_anvil-resolve-stable install-msrv` and nothing else, so no resolver change is needed and the doc and contract test now state the real reason.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(cargo-anvil): delete the copied manifest once the setup has read it

The tag hashes the declared MSRV rather than the manifest, so an edit that leaves rust-version alone computes the same tag. With the manifest left in place that tag named two different filesystems, and a reused or published image carried a Cargo.toml matching no checkout.

Deleting it in the same RUN that reads it makes the identity exact again, and restores the design note's claim that those edits cannot alter a byte the image contains. Three statements in containers.md that still described the old three-path context are corrected alongside it, including the replacement rule a downstream catalog reads verbatim.

Also drops an env_remove for ANVIL_ROOT_MSRV: nothing on this branch reads that variable, so the call could not affect what a fixture resolves and its comment described a mechanism that no longer exists.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 2963084a-ef08-4cf7-adc6-e78e61556a84

* docs(cargo-anvil): trim the container commentary to what is not inferable

The comments added with the previous commit ran well past the change. Several restated the assertion message directly below them; others explained what the code already says.

Keep the reasons a reader cannot recover: why the context is copied whole, why both toolchain-file spellings are admitted and neither required, and why the tag discovers the file rather than requiring it. Drop the rest. No behaviour changes.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 80f12d44-5a83-4650-9806-d3e247175858
Copilot-Session: 2963084a-ef08-4cf7-adc6-e78e61556a84

Author: wukchung

.anvil.lock

@@ -1,11 +1,11 @@
 version = 1
 tool = "anvil"
 tool_version = "0.9.0"
-catalog_checksum = "sha256:baa2a5e479fe8f466e8f54e71ef0c498e07ac225b59a61a76ee99d46d5498650"
+catalog_checksum = "sha256:540ae76e257e9f1e7c16b3bf015bdc084a98be8ca98858c797c075eedde7edb0"
 
 [[file]]
 path = ".anvil/container/Dockerfile.dockerignore"
-checksum = "sha256:3907b9d8d15211ef5adff9ac2bcd23023797ed7b9961a59e28324bb7666ec340"
+checksum = "sha256:641cb14e197a1fd9c8e179b7e992aede15d80291841b82830d7283e1b751d3cb"
 
 [[file]]
 path = ".github/actions/anvil-impact/action.yml"
@@ -181,7 +181,7 @@ checksum = "sha256:6efd7378a2cd0f5d86519bd32fd86f2055a60191187dd77a8842b374b8eb7
 
 [[file]]
 path = "justfiles/anvil/container.just"
-checksum = "sha256:6e2a24a20fb7c0a7a0bffa35f98b8b9e66f96bb6ec9cce8154199930546b375c"
+checksum = "sha256:b6e42555c5bb59f3040f665ec0ae9c9289a0d67490d72d758bfc1ec0dc6bd62a"
 
 [[file]]
 path = "justfiles/anvil/dev/build.just"
@@ -269,7 +269,7 @@ checksum = "sha256:7b409a9b560c214e10b50f74330fb6f8c0c12c3d83494e0dcf016f2411b50
 [[region]]
 host = ".anvil/container/Dockerfile"
 id = "anvil-container-setup"
-checksum = "sha256:6a516c50a5a717a2b7635e043f2cc33fd872bdf5950a456718518b1af0bf75f9"
+checksum = "sha256:0e777d1a0b54ada564aa48b8b23c9f035d07d0f6d49a83a4ebca76773a7fd29a"
 
 [[region]]
 host = ".anvil/container/Dockerfile"

.anvil/container/Dockerfile

@@ -78,6 +78,12 @@ RUN curl -fsSLo /tmp/cargo-binstall.tgz \
 # <<< anvil-managed: anvil-container-tools
 
 # >>> anvil-managed: anvil-container-setup
+# The context is copied whole rather than input by input, because one of the
+# inputs is optional: a repository that pins its compiler by other means owns no
+# root toolchain file, and a `COPY` of a path that may not exist is not portable
+# across the engines anvil supports. `.anvil/container/` rides along as a
+# consequence; the image never reads it.
+#
 # The whole recipe tree is copied because `just` parses it to reach the install
 # recipes.
 #
@@ -94,24 +100,37 @@ RUN curl -fsSLo /tmp/cargo-binstall.tgz \
 # volume over each, and an engine seeds a new volume from the image path it
 # covers; a path that does not exist seeds as root-owned 0755, which the
 # `--user` mapping cannot write, so the first cargo fetch fails with EACCES.
-# The root manifest is copied for the MSRV, the one version `anvil-setup`
+# The root manifest is admitted for the MSRV, the one version `anvil-setup`
 # installs that is declared in repository source rather than pinned in
 # `versions.just`. `/opt/anvil` is the root the recipes already resolve against,
 # so the resolver reads it there with no container-specific path. The workspace
-# members it names are not copied and are not needed: the toolchain file selects
-# the compiler, which is the branch that skips workspace MSRV validation.
+# members it names are not admitted and are not needed: the one path that reads
+# them is workspace MSRV validation, which only
+# `anvil-tool-rustc-validate-prereqs` invokes, and nothing `anvil-setup`
+# reaches depends on it.
 #
 # It is deleted once the setup has read it, so it does not survive into the
 # finished image. The tag hashes the declared MSRV rather than the file, so an
 # unrelated dependency edit computes the same tag; a manifest left in place
 # would make that tag name two different filesystems, and a reused or published
 # image would carry a manifest that does not match any checkout.
+#
+# `rustup` was initialized with `--default-toolchain none`, so the image has no
+# default until something names one. Rustup sets it as a side effect of the
+# first `rustup toolchain install` that finds none set, which today is the
+# MSRV; that is an accident of the order `anvil-setup` reaches the install
+# recipes in, not something either side states. A checkout with a root
+# toolchain file never notices, because that file overrides the default. One
+# without has nothing else to select a compiler, so plain `cargo` in the
+# container would follow whichever toolchain the setup graph happened to
+# install first. The default is named here instead, from the same declared MSRV
+# the setup installs, while the manifest it is read from is still present.
 WORKDIR /opt/anvil
-COPY justfiles ./justfiles
-COPY rust-toolchain.toml ./
-COPY Cargo.toml ./
+COPY . ./
 RUN printf "import 'justfiles/anvil/mod.just'\n" > Justfile \
     && just anvil-setup binstall \
+    && msrv="$(just _anvil-resolve-stable root-msrv)" \
+    && if [ "${msrv}" != "none" ]; then rustup default "${msrv}"; fi \
     && rm -f Cargo.toml \
     && rm -rf "${CARGO_HOME}/registry/cache" "${CARGO_HOME}/registry/src" \
     && rm -f "${CARGO_HOME}/credentials" "${CARGO_HOME}/credentials.toml" "${HOME:-/root}/.netrc" /root/.netrc \

.anvil/container/Dockerfile.dockerignore

@@ -7,9 +7,11 @@
 # `.dockerignore`, so this scopes the exec-image build context without the
 # repository having to own a root ignore file or having one silently overridden.
 #
-# The build context is the repository root but the image only needs two things.
-# Excluding everything else keeps a cold build from streaming the whole
-# worktree (and every stale `target/`) to the daemon.
+# The build context is the repository root but the image needs a small, named
+# set out of it. Excluding everything else keeps a cold build from streaming the
+# whole worktree (and every stale `target/`) to the daemon -- and, because the
+# setup region copies the context whole, this file decides what the image
+# contains.
 #
 # The context is narrowed to `justfiles/anvil/` rather than all of `justfiles/`
 # so that a cold build does not stream unrelated trees to the daemon. The
@@ -29,6 +31,11 @@
 # The root `Cargo.toml` is admitted for the declared MSRV, the only build input
 # that lives in repository source rather than in the recipe tree. The workspace
 # members it names stay out: they are a checkout, and the image is not one.
+#
+# Both spellings are admitted and neither is required: a repository that pins
+# by other means gets an image whose compiler is the declared MSRV, and
+# admitting only the TOML would give one that pins with the extensionless file
+# an image that disagreed with its own checkout.
 *
 !justfiles
 justfiles/*
@@ -39,4 +46,5 @@ justfiles/anvil/**/*.anvil-proposed
 !.anvil/container
 .anvil/container/**/*.anvil-proposed
 !rust-toolchain.toml
+!rust-toolchain
 !Cargo.toml

crates/cargo-anvil/README.md

@@ -348,8 +348,10 @@ just anvil-container cargo build
 ```
 
 The image contains the same tool versions used by the generated checks.
-Its tag is derived from the Dockerfile, toolchain, and generated recipe
-tree, so changes to those inputs select a different image. Docker is
+Its tag is derived from the Dockerfile and its ignore file, the generated
+recipe tree, the declared root MSRV, and a root `rust-toolchain` file where
+the repository owns one, so changes to those inputs select a different
+image. Docker is
 supported; Podman is available on a best-effort basis. Repositories that
 need private feeds can add a host-side credential hook without embedding
 credentials in the image or command line. See
@@ -398,7 +400,7 @@ More detailed design and operational guidance is available in the
 This crate was developed as part of <a href="../..">The Oxidizer Project</a>. Browse this crate's <a href="https://github.com/microsoft/ox-tools/tree/main/crates/cargo-anvil">source code</a>.
 </sub>
 
- [__cargo_doc2readme_dependencies_info]: ggGmYW0CYXZlMC43LjNhdIQblRYhli3L8qob_NSi_WYo69wbWnMVqZw3jJwb3u56HnT6RDphYvRhcoQb_Wi2RvJKqLgb6U0-tQFqaYMbiv-kD9siQ44bVYhqNqZVUZBhZIGDa2NhcmdvLWFudmlsZTAuOS4wa2NhcmdvX2Fudmls
+ [__cargo_doc2readme_dependencies_info]: ggGmYW0CYXZlMC43LjNhdIQblRYhli3L8qob_NSi_WYo69wbWnMVqZw3jJwb3u56HnT6RDphYvRhcoQbBALu36V1VAYbFUDdfp-8dCobobFjKbRep8AbYNMPgi_aMhFhZIGDa2NhcmdvLWFudmlsZTAuOS4wa2NhcmdvX2Fudmls
  [__link0]: https://github.com/casey/just
  [__link1]: https://rust-lang.github.io/rustfmt/
  [__link10]: https://embarkstudios.github.io/cargo-deny/

crates/cargo-anvil/docs/design/containers.md

@@ -53,9 +53,10 @@ Both are addressed by executing the recipe unchanged inside an image built from
 bodies are identical in either mode, and cloud workflows are unaffected: they run the same recipes natively on their
 own agents. The image is pinned to resemble that environment, not to reproduce it.
 
-Image construction has a deliberately stricter compiler contract than native execution: the repository must own
-`rust-toolchain.toml`. The build context admits that file but not `rust-toolchain`, and the build does not inherit the
-host's `RUSTUP_TOOLCHAIN`; rustup therefore selects the image compiler from the repository-owned TOML file.
+Image construction does not require the repository to own a `rust-toolchain.toml`. Where one exists — either
+spelling — the context admits it and rustup selects the image compiler from it, exactly as it would on a host. Where a
+repository pins its compiler by other means and owns neither, the image compiler is the declared root MSRV, which is
+again what a host resolves there. The build does not inherit the host's `RUSTUP_TOOLCHAIN` in either case.
 
 ## 2. Command surface
 
@@ -133,7 +134,7 @@ never read, rewritten or reordered.
 | `anvil-container-base-image` | `ARG BASE_IMAGE`, pinned to a digest. | A second `ARG BASE_IMAGE=…` to build on a different base. |
 | `anvil-container-base` | `FROM`, the version pins for `pwsh`, `just`, `rustup` and `cargo-binstall`, and the `ENV` block. | Anything the first network access needs: a root CA, `http_proxy`, an internal package mirror. |
 | `anvil-container-tools` | System packages and those four tools. | Libraries a catalog tool needs to compile, for tools `binstall` has no prebuilt binary for. |
-| `anvil-container-setup` | `COPY` of the recipe tree and the root manifest, then `just anvil-setup`. | Anything the repository's own checks need at run time. |
+| `anvil-container-setup` | `COPY` of the scoped build context, then `just anvil-setup`. | Anything the repository's own checks need at run time. |
 | `anvil-container-entry` | `ANVIL_IN_CONTAINER`, `WORKDIR`, `CMD`. | — |
 
 Each gap sits at the only point in the build where its kind of addition works: a certificate has to land before the
@@ -191,23 +192,36 @@ and copied to `/opt/anvil`, the root the recipes already resolve against, so the
 container-specific path in it.
 
 The workspace members it names are not admitted: they are a checkout, and the image is not one. The one path that
-would need them, workspace MSRV validation, returns early whenever a root toolchain file selects the compiler.
+would need them is workspace MSRV validation, which the image never reaches: `anvil-tool-rustc-validate-prereqs` is its
+only caller, and nothing `anvil-setup` reaches depends on that recipe. Inside a running
+container that validation does execute, against `/workspace` — a real checkout, with its members.
 
 The manifest is deleted once the setup has read it, so it is in the build context but not in the finished image. That
 keeps the tag honest: it hashes the declared MSRV rather than the file, so a dependency edit computes the same tag,
 and nothing is left behind for that tag to misdescribe.
 
-That makes the toolchain file a precondition of this design rather than a convenience: the image requires one, copies
-it, and relies on it to keep workspace validation out of reach of a context that has no members. A repository without
-one cannot build the image today, because the `COPY` above is unconditional. Should that become conditional, this
-design needs revisiting alongside it.
-
-`Dockerfile.dockerignore` scopes the build context to `justfiles/anvil/`, `.anvil/container/`, `rust-toolchain.toml`
-and the root `Cargo.toml`, denying everything else. The recipe tree is copied whole because `just` has to parse it to run
-`anvil-setup`, and it is hashed whole (§4). `.anvil/container/` is admitted so a gap can `COPY` a file placed beside
-the Dockerfile; anvil's own `.anvil-proposed` review artifacts are excluded from both the context and the digest.
-BuildKit reads `<dockerfile>.dockerignore` in preference to a root `.dockerignore`, so the repository neither needs to
-own a root ignore file nor can have one silently override this.
+**The image names its default toolchain.** `rustup` is initialized with `--default-toolchain none`, and rustup then
+sets the default as a side effect of the first `rustup toolchain install` that finds none set. That is the MSRV today,
+but only because of the order `anvil-setup` reaches the install recipes in. A checkout with a root toolchain file never
+notices, because the file overrides the default; a checkout without one has nothing else to select a compiler, so plain
+`cargo` inside the container would follow whichever toolchain the setup graph installed first. The setup region
+therefore runs `rustup default` on the declared MSRV, read from the manifest before it is deleted, so an arbitrary
+Rust command in the container uses the compiler the repository declared. A repository declaring no MSRV is left alone;
+the setup installs no stable toolchain for it either.
+
+The setup region copies the context whole rather than naming each input, because one input is optional. A repository
+that pins its compiler by other means owns no root toolchain file, and a `COPY` of a path that may not exist is not
+portable across the engines anvil supports, so naming the file would leave exactly those repositories unable to build
+an image at all. The ignore file already scopes the context to precisely the image's inputs, so deferring to it makes
+what the context admits and what the image contains the same set. `.anvil/container/` rides along with it; that is the
+committed input a gap `COPY`s from, and the image never runs it.
+
+`Dockerfile.dockerignore` scopes the build context to `justfiles/anvil/`, `.anvil/container/`, a root toolchain file in
+either spelling, and the root `Cargo.toml`, denying everything else. The recipe tree is copied whole because `just` has
+to parse it to run `anvil-setup`, and it is hashed whole (§4). `.anvil/container/` is admitted so a gap can `COPY` a
+file placed beside the Dockerfile; anvil's own `.anvil-proposed` review artifacts are excluded from both the context
+and the digest. BuildKit reads `<dockerfile>.dockerignore` in preference to a root `.dockerignore`, so the repository
+neither needs to own a root ignore file nor can have one silently override this.
 
 ## 4. Image identity
 
@@ -219,7 +233,7 @@ define the image. The name derives from the repository directory (§5.1).
 | Input | Hashed |
 | --- | --- |
 | every file under `.anvil/container/` | always |
-| `rust-toolchain.toml` | always |
+| `rust-toolchain.toml` or `rust-toolchain` | when the repository owns one |
 | every file under `justfiles/anvil/` | always |
 | the declared root MSRV | always |
 
@@ -230,6 +244,10 @@ change the image under a reference that already resolves, which is the hole the
 Dockerfile is still a hard error, checked by name: the walk alone would let it contribute nothing and yield a confident
 tag for an image that cannot be built.
 
+The root toolchain file is the one input whose absence is not an error. It is discovered rather than required, in both
+spellings, and a repository that owns none contributes one fewer record to the digest — a state distinct from owning
+one, so the two cannot share a tag.
+
 The recipe tree is hashed in full. `just anvil-setup` reaches the install recipes through the tier, group and check
 recipes, so the routing decides *whether* a tool is installed just as surely as `tools.just` decides *how*: dropping an
 `anvil-<check>-setup` dependency from a group changes the installed set while `tools.just` and `versions.just` stay
@@ -421,7 +439,8 @@ image, executes the requested command directly instead of launching another cont
 ## 6. Engines and host setup
 
 anvil installs nothing and manages no virtual machine. Beyond the engine, the host needs `just` and PowerShell Core
-(`pwsh`), which every generated recipe requires, and the repository must own a `rust-toolchain.toml`.
+(`pwsh`), which every generated recipe requires. The repository needs a declared root MSRV; a `rust-toolchain.toml` is
+honoured where it exists but is not required (§1).
 
 | | Docker | Podman |
 | --- | --- | --- |
@@ -637,10 +656,12 @@ Replacing a *region* rather than the whole file is what makes a downstream catal
 private-environment catalog rewrites the base and tool layers and nothing else. Replacing `dockerfile_setup()` reintroduces the
 second tool list the design exists to avoid, and is almost never right.
 
-**A replacement must keep the ignore file in step.** A region that `COPY`s anything outside `justfiles/anvil/`,
-`.anvil/container/`, `rust-toolchain.toml` and the root `Cargo.toml` must also replace
-`artifacts::container::dockerignore()` (§3), or the added paths never reach the build context and the build fails on a
-missing file.
+**A replacement must keep the ignore file in step.** The setup region `COPY`s the context whole, so the ignore file is
+what decides the image's contents. A region that needs anything outside `justfiles/anvil/`, `.anvil/container/`, a root
+toolchain file and the root `Cargo.toml` must also replace `artifacts::container::dockerignore()` (§3), or the added
+paths never reach the build context. Widening it also moves content into the image that the digest does not hash: the
+walk covers `.anvil/container/` and `justfiles/anvil/` and nothing else, so a newly admitted tree has to be brought
+under one of them, or the tag stops covering what the image contains.
 
 **Anything extra it copies is digested, provided it lives under `.anvil/container/`.** The hashed set is that whole
 directory (§4.1), so an installer script, a config file or a certificate placed beside the Dockerfile is an input:
@@ -651,10 +672,11 @@ manual `ANVIL_CONTAINER_NO_CACHE=1`.
 `justfiles/anvil/` must contain `.just` recipes and nothing else, which `CatalogBuilder::build` enforces for
 catalog-owned files. The reason is legibility rather than identity: the directory is the recipe tree, `just` parses
 every file the image copies, and a catalog that hides an installer script there makes the tool set harder to reason
-about than one that keeps it in `.anvil/`. Identity is safe either way, because the digest covers every file the build
-context admits and the image keeps (§4.1), not only the recipes — a repository that adds a non-recipe file by hand
+about than one that keeps it in `.anvil/`. Identity is safe either way, because the digest walks that whole directory
+rather than only its recipes (§4.1) — a repository that adds a non-recipe file by hand
 still renames the tag when it edits it. The root `Cargo.toml` is the one admitted file the digest does not cover as
-bytes, and it is also the one the setup deletes once read, so it is in no image for the tag to misdescribe.
+bytes, and it is also the one the setup deletes once read, so it is in no image for the tag to misdescribe. Both
+statements describe the ignore file anvil ships; a replacement that admits another tree carries the obligation above.
 
 A fork inherits everything else: the recipes, the identity scheme, the cache volumes, the mounts, and the re-entry
 guard. A different base OS with a different toolchain source is two region replacements plus one hook.

crates/cargo-anvil/src/anvil/artifacts/container.rs

@@ -346,8 +346,11 @@ mod tests {
         // the same recipe the checks use, from the same generated pins.
         let composed = composed_dockerfile();
         assert!(composed.contains("just anvil-setup binstall"));
-        assert!(composed.contains("COPY justfiles"));
-        assert!(composed.contains("COPY rust-toolchain.toml"));
+        assert!(composed.contains("COPY . ./"));
+        assert!(
+            !composed.contains("COPY rust-toolchain"),
+            "naming the toolchain file would leave a repository without one unable to build"
+        );
         // The re-entry guard the recipe relies on to avoid nesting.
         assert!(composed.contains("ENV ANVIL_IN_CONTAINER=1"));
     }
@@ -422,7 +425,9 @@ mod tests {
     #[test]
     fn build_context_admits_only_what_the_image_copies() {
         assert!(DOCKERIGNORE.contains("!justfiles"));
+        assert!(DOCKERIGNORE.contains("!Cargo.toml"));
         assert!(DOCKERIGNORE.contains("!rust-toolchain.toml"));
+        assert!(DOCKERIGNORE.contains("!rust-toolchain\n"));
     }
 
     #[test]