ci(examples): the criterion for a rebuilt compiler had to be built to isolate it

The device-language step still asserted the previous example: it grepped for
`toy_answer() = 42` and edited `rules-toy/tools/toyc.sh`, a shell script that no
longer exists. The job failed with "the .toy did not reach the link".

Rewriting it turned up a claim I had written from reading the rule rather than
from measuring it, and the measurement contradicts it.

WHAT THE FIRST REWRITE ASSERTED. Bump the tool package's version, and the
artifact follows. That is true, and it does not test what its message said.
Falsified by removing `a.input(compiler)` from the rule: the version bump still
reached the artifact and the step still passed. The tool's path is on the
action's command line, so a new path re-runs the edge whether or not the
compiler is also a declared input.

WHAT ISOLATES IT. Different bytes at the same path: build a compiler that
behaves differently and overwrite the cached binary in place, leaving the
command line byte-identical. And both directions, because neither alone is the
property -- with the input removed, the artifact followed the overwrite and then
stopped following the restore. With the input present the step exits 0; with it
removed, 1.

The step now covers four things: the `.toy` reaches the link; the emitted loop
runs (`gcd(1071, 462) = 21`, a value no constant in the tree holds); the
compiler's bytes are tracked by the action; and the tool store holds no source
content, with a version bump as the way out. Probe runs exit non-zero on
purpose -- the program returns 1 when the answer is not 42 -- so they are judged
by their output rather than their status.

The README and chapter 30 said the action re-runs when the compiler binary
changes. That is now measured rather than reasoned, and both state which case
does not isolate it.

Author: speak-agent

.github/workflows/ci-linux.yml

@@ -313,20 +313,95 @@ jobs:
           echo "ok: the optional package is absent without its feature"
           cd - >/dev/null
 
-          # 12-a-new-device-language. The `.toy` compiles on an engine that does
-          # not know the extension, AND editing the compiler reaches the
-          # artifact -- the half that fails silently when the tool is not a
-          # declared input of the action.
+          # 12-a-new-device-language. Three criteria, and a probe run exits
+          # non-zero on purpose -- the program returns 1 when the answer is not
+          # 42 -- so those runs are guarded with `|| true` and judged by their
+          # output rather than their status.
           cd examples/12-a-new-device-language/app
           "$MCPP" run | tee /tmp/toy.log
-          grep -q 'toy_answer() = 42' /tmp/toy.log || {
+          grep -q 'answer()       = 42' /tmp/toy.log || {
             echo "FAIL: the .toy did not reach the link"; exit 1; }
-          sed -i 's/print s + 0 }/print s + 100 }/' ../rules-toy/tools/toyc.sh
-          "$MCPP" run | tee /tmp/toy2.log
-          sed -i 's/print s + 100 }/print s + 0 }/' ../rules-toy/tools/toyc.sh
-          grep -q 'toy_answer() = 142' /tmp/toy2.log || {
-            echo "FAIL: editing the compiler did not reach the artifact"; exit 1; }
-          echo "ok: the compiler is a declared input"
+          # THE LANGUAGE IS EXECUTED, NOT PATTERN-MATCHED: 21 is what the
+          # emitted `while` loop computes, and no constant in the tree holds it.
+          grep -q 'gcd(1071, 462) = 21' /tmp/toy.log || {
+            echo "FAIL: the emitted loop did not run"; exit 1; }
+
+          # Editing the .toy reaches the artifact.
+          sed -i 's/scale(gcd(1071, 462), 2)/scale(gcd(1071, 462), 3)/' src/kernels/answer.toy
+          "$MCPP" run > /tmp/toy2.log 2>&1 || true
+          sed -i 's/scale(gcd(1071, 462), 3)/scale(gcd(1071, 462), 2)/' src/kernels/answer.toy
+          grep -q 'answer()       = 63' /tmp/toy2.log || {
+            cat /tmp/toy2.log; echo "FAIL: editing the .toy did not reach the artifact"; exit 1; }
+
+          # THE COMPILER IS A DECLARED INPUT OF THE ACTION -- the half that
+          # fails silently, and the one criterion here that has to be built to
+          # isolate it. Bumping the tool's version is NOT that criterion: the
+          # tool's path is on the action's command line, so a new path re-runs
+          # the edge whether or not it is also declared as an input. Measured:
+          # with `a.input(compiler)` removed, a version bump still reached the
+          # artifact, and this step passed.
+          #
+          # The isolating change is different BYTES AT THE SAME PATH. Build a
+          # compiler that behaves differently, overwrite the cached binary in
+          # place, and the command line is byte-identical.
+          #
+          # BOTH DIRECTIONS ARE THE CRITERION, not either one. Falsified by
+          # removing `a.input(compiler)`: the artifact followed the first
+          # overwrite anyway and stopped following the restore, so a check that
+          # asserted only the first direction would have passed on a rule that
+          # tracks nothing.
+          #
+          # `n.value * 2` keeps `0` at `0`: a probe that changed every literal
+          # would turn `while (b != 0)` into a loop that divides by zero, and
+          # this step would report a crash rather than an answer.
+          probe_on() { sed -i 's/return std::format("{}", n.value);/return std::format("{}", n.value * 2);/' ../toyc/src/compile.cppm; }
+          probe_off() { sed -i 's/return std::format("{}", n.value \* 2);/return std::format("{}", n.value);/' ../toyc/src/compile.cppm; }
+          install_toyc() {
+            ( cd ../toyc && "$MCPP" build >/dev/null )
+            cp "$(find ../toyc/target -name toyc -type f -perm -u+x | head -1)" "$1"
+          }
+
+          # `mcpp cache dir` prints a legacy-directory note on a second line.
+          store="$("$MCPP" cache dir | head -1)/tool"
+          cached="$(find "$store" -path '*toyc@0.1.0*/bin/toyc' | head -1)"
+          [ -n "$cached" ] || {
+            echo "FAIL: no toyc in the tool store under $store"; exit 1; }
+
+          probe_on; install_toyc "$cached"; probe_off
+          "$MCPP" run > /tmp/toy3.log 2>&1 || true
+          grep -q 'answer()       = 168' /tmp/toy3.log || {
+            cat /tmp/toy3.log
+            echo "FAIL: a changed compiler binary did not reach the artifact."
+            echo "      rules-toy must declare the compiler among the action's inputs."
+            exit 1; }
+          install_toyc "$cached"
+          "$MCPP" run > /tmp/toy4.log 2>&1 || true
+          grep -q 'answer()       = 42' /tmp/toy4.log || {
+            cat /tmp/toy4.log
+            echo "FAIL: restoring the compiler binary did not reach the artifact --"
+            echo "      the action is not tracking the compiler's bytes."
+            echo "      rules-toy must declare the compiler among the action's inputs."
+            exit 1; }
+
+          # THE STORE HOLDS NO SOURCE CONTENT, which the example's README and
+          # docs/30 both state. Editing the compiler's sources at the same
+          # version changes nothing, because nothing rebuilds the tool.
+          probe_on
+          "$MCPP" run > /tmp/toy5.log 2>&1 || true
+          grep -q 'answer()       = 42' /tmp/toy5.log || {
+            cat /tmp/toy5.log
+            echo "FAIL: the tool store now sees source content."
+            echo "      The example's README and docs/30 state that it does not; update them."
+            exit 1; }
+
+          # ... and bumping the version is the way out both of them offer.
+          sed -i 's/^version     = "0.1.0"/version     = "0.1.1"/' ../toyc/mcpp.toml
+          "$MCPP" run > /tmp/toy6.log 2>&1 || true
+          sed -i 's/^version     = "0.1.1"/version     = "0.1.0"/' ../toyc/mcpp.toml
+          probe_off
+          grep -q 'answer()       = 168' /tmp/toy6.log || {
+            cat /tmp/toy6.log; echo "FAIL: bumping the tool version did not rebuild it"; exit 1; }
+          echo "ok: the compiler is a declared input, and the store is keyed on the version"
 
       - name: "Graphics example: render offscreen on lavapipe and assert the pixels"
         run: |

docs/30-build-mcpp.md

@@ -936,10 +936,15 @@ A published version is immutable, so for a tool that arrives from an index the
 key is exact. A tool being edited next door has the same version from one build
 to the next, and the cached binary stays: measured on
 [`examples/12-a-new-device-language`](../examples/12-a-new-device-language/),
-a change to the tool's emitter left `mcpp run` reporting `Finished dev in 0.00s`
-and printing the previous answer. Bump the tool package's version, or empty the
-build cache with `mcpp cache clean` — the tool store lives inside it, at
-`<mcpp cache dir>/tool/<index>/<name>@<version>/`.
+a change to the tool's emitter left `mcpp run` printing the previous answer,
+while bumping the tool package's version rebuilt it and changed the artifact.
+Bump the version, or empty the build cache with `mcpp cache clean` — the tool
+store lives inside it, at `<mcpp cache dir>/tool/<index>/<name>@<version>/`.
+
+This is a gap in the rebuild, not in the tracking. An action that declares the
+tool among its inputs does re-run when that file's bytes change, measured by
+overwriting the binary in the store: the artifact followed. What does not happen
+is the rebuild that would change those bytes.
 
 ### `[tools.overrides]` — use an existing binary
 

docs/zh/30-build-mcpp.md

@@ -789,9 +789,13 @@ grpc     = { version = "1.83.0", tools = ["grpc_cpp_plugin"] }
 所以对来自索引的工具,这个键是精确的。而正在旁边被编辑的工具,两次构建之间版本相同,
 缓存里的二进制就留在原地:在
 [`examples/12-a-new-device-language`](../../examples/12-a-new-device-language/)
-上实测,改动工具的 emitter 之后,`mcpp run` 报告 `Finished dev in 0.00s` 并打印上一次
-的答案。抬工具包的版本,或用 `mcpp cache clean` 清空构建缓存 —— tool store 就住在
-里面,路径是 `<mcpp cache dir>/tool/<index>/<name>@<version>/`。
+上实测,改动工具的 emitter 之后 `mcpp run` 打印的是上一次的答案,而抬高工具包的版本
+之后它被重建、产物随之改变。抬版本,或用 `mcpp cache clean` 清空构建缓存 ——
+tool store 就住在里面,路径是 `<mcpp cache dir>/tool/<index>/<name>@<version>/`。
+
+**缺口在重建,不在跟踪。** 把工具列进 action 输入的规则,确实会在那个文件的字节变化
+时重跑 —— 实测直接覆盖 store 里的二进制,产物随之改变。不发生的是「让这些字节变化」
+的那次重建。
 
 ### `[tools.overrides]` —— 使用已有的二进制
 

examples/12-a-new-device-language/README.md

@@ -184,28 +184,47 @@ a real compiler rather than a script.
 
 ## The boundary this example measured: a host tool is cached by version
 
-Editing `toyc`'s **source** does not reach the artifact. Measured: a change to
-the emitter left `mcpp run` reporting `Finished dev in 0.00s` and printing the
-previous answer.
+Four changes were made one at a time, each from the same starting state:
 
-The tool store's key is the tool package's identity, version, host triple,
-compiler identity, profile, features and the versions of its transitive
-dependencies — not the content of its sources. For a package that arrives from
-an index that key is exact, because a published version is immutable. For a
-`path` dependency being edited it is not:
-
-| situation | effect |
-|---|---|
-| the tool's version changes | the tool is rebuilt, and the action re-runs because its declared input changed |
-| the tool's sources change, its version does not | the cached binary stays, and the build is green over the previous compiler's output |
-
-Two ways out, and they are the same one at different sizes: bump the tool
-package's version, or empty the build cache with `mcpp cache clean` — the tool
-store lives inside it, at `<mcpp cache dir>/tool/<index>/<name>@<version>/`.
-
-The action itself is not the gap. `rules-toy` declares the compiler as an input
-beside the source, so an action whose compiler binary changes does re-run. What
-does not happen is the rebuild that would change those bytes.
+| what changed | the artifact | how it was changed |
+|---|---|---|
+| the `.toy` source | follows: `42` → `63` | `scale(…, 2)` → `scale(…, 3)` |
+| the compiler's **bytes**, at the path the action names | follows: `42` → `168` | overwriting the binary in the tool store |
+| the compiler's **sources**, its version unchanged | does not follow: the previous answer stands | editing the emitter |
+| the compiler's **version** | follows: `42` → `168`, and the tool is rebuilt | `0.1.0` → `0.1.1` |
+
+Rows two and three are the whole finding, and they separate two things that are
+easy to merge. **The action's input tracking works**: `rules-toy` declares the
+compiler beside the source, and changing that file's bytes re-runs the edge.
+**What does not happen is the rebuild that would change those bytes.** The tool
+store's key is the tool package's identity, version, host triple, compiler
+identity, profile, features and the versions of its transitive dependencies —
+it holds no source content. For a package that arrives from an index the key is
+exact, because a published version is immutable; for a `path` dependency being
+edited it is not.
+
+`mcpp run` prints `Finished dev in 0.00s` in row three, and that line is mcpp's
+own summary rather than evidence: row two prints it too, and the artifact
+changed.
+
+**Row four does not test row two, which is why the difference is worth stating.**
+The tool's path is on the action's command line, so a new version re-runs the
+edge whether or not the compiler is also a declared input. Removing
+`a.input(compiler)` from `rules-toy` and bumping the version left the artifact
+following anyway. The isolating change is different bytes at the *same* path —
+row two — and it takes both of its directions: with the input removed, the
+artifact followed the overwrite and then stopped following the restore. CI runs
+that pair.
+
+Two ways out: bump the tool package's version, or empty the build cache with
+`mcpp cache clean` — the tool store lives inside it, at
+`<mcpp cache dir>/tool/<index>/<name>@<version>/`.
+
+**One more trap sits behind them.** Going back from `0.1.1` to `0.1.0`, whose
+clean tool was still in the store, left the artifact at `168`. The build program
+did not re-run, so the plan still named the `0.1.1` binary, which had not
+changed. `rm -rf target` cleared it. Iterating on a compiler means the version
+goes forward only.
 
 ## Three things the first version got wrong