fix(build): the fast path compares every declared build-program input

`rerun_if_changed("data/table.csv")` states that the program must run
again when that file's content changes. The project-level fast path skips
prepare_build when no source is newer than build.ninja, and prepare_build
is where the program's cache is read; the check the fast path did run
asked only about glob path sets. A data file is neither under src/ nor
named with a C++ extension, so the mtime sweep cannot see it either.
Editing it therefore left the previous run's generated header in place:
`Finished dev in 0.00s`, and the program compiled the previous bytes.

The fast path now compares the three kinds of input the cache records: a
glob's path set, a declared file's content hash, and a declared
environment variable's value. `glob_inputs_stale` is renamed
`program_inputs_stale` because the name was the reason the other two were
never asked about.

e2e 612 uses the program's output as its criterion -- a stale header and
a fresh one make the binary print different strings -- and runs the other
half of the control: with nothing touched, the next build still takes the
fast path, which "always rebuild" would also pass the first assertion
with. Verified failing on 2026.9.5.3 and passing here.

Found by mcpp.tools.embed, the first non-rule member of mcpp:plugins: it
writes a data file into a header while the build program runs, so it
submits no action and falls entirely on this path.

Documentation for both languages, CHANGELOG, and version 2026.9.5.4.

Author: speak-agent

CHANGELOG.md

@@ -5,6 +5,29 @@
 
 ## [Unreleased]
 
+## [2026.9.5.4] — 2026-09-06
+
+### 构建程序声明的文件输入,快路径此前不比较
+
+`rerun_if_changed("data/table.csv")` 声明的是「这个文件的内容变了就重跑」。工程级快路径
+在没有任何**源文件**比 `build.ninja` 新时跳过 `prepare_build`,而构建程序缓存正是在
+`prepare_build` 里被读取的;快路径自己只问过 glob 输入的**路径集合**(#359),没问过声明
+文件的内容。数据文件既不在 `src/` 下也没有 C++ 扩展名,mtime 扫描看不见它,于是改了数据、
+`mcpp build` 打印 `Finished dev in 0.00s`、程序里编进去的还是上一次的字节。
+
+快路径现在按缓存里记录的方式比较三类构建程序输入:glob 的路径集合、声明文件的内容哈希、
+声明环境变量的值。e2e 612 用程序的**输出**做判据(陈旧的头文件与新的头文件让二进制打印
+不同的字符串),并跑对照的另一半:输入没变时第二次构建仍然走快路径,否则「总是重建」也能
+让第一条断言通过。发现它的是 `mcpp.tools.embed`——mcpp-plugins 0.1.1 里第一个非规则成员,
+它把数据文件写成头文件,没有 action 可提交,所以完全落在这条路径上。
+
+### 注释与文档里不再有装饰性符号
+
+2026.9.5.3 的清理覆盖了 `docs/`、`README.md`、CHANGELOG、引擎源码、测试、示例与工作流
+文件,没有覆盖 `bench/`、`tools/`、`scripts/`、`mcpp.toml` 与 `README.zh-CN.md`。程序
+输出保留原样:用户在终端上读到的一行既不是文档也不是注释。`README.zh-CN.md` 同时补上英文
+版已有的 Cortex-M 行,状态列改用与英文版相同的词。
+
 ## [2026.9.5.3] — 2026-09-05
 
 ### 官方构建插件集中为一个包:`mcpp:plugins`

docs/07-build-mcpp.md

@@ -348,6 +348,17 @@ paths** and nothing else:
 The build output tree and `.git` are never part of the set, so a wide pattern
 cannot make the program re-run forever against its own outputs.
 
+**Every declared input is compared on the fast path too** (2026.9.5.4+). A
+project whose sources are all older than `build.ninja` takes a fast path that
+skips the phase where the program's cache is normally consulted, and until
+2026.9.5.4 that path asked only about glob path sets. A data file a program
+reads is neither under `src/` nor named with a C++ extension, so the mtime
+sweep cannot see it either: editing it left the previous run's output in place
+and the build reported `Finished dev in 0.00s`. The fast path now compares what
+the cache records — a glob's path set, a declared file's content hash, and a
+declared environment variable's value — so `rerun_if_changed` means the same
+thing under both paths.
+
 ### Declaring work instead of doing it: `mcpp::action` (2026.8.5.1+)
 
 Generating a source by writing it *here* is the easy path and the wrong one

docs/zh/07-build-mcpp.md

@@ -305,6 +305,13 @@ int main() {
 构建输出目录与 `.git` 永远不进入集合,因此再宽的模式也不会让程序对着自己的产物
 无限重跑。
 
+**声明过的输入在快路径上同样被比较**(2026.9.5.4+)。当所有源文件都不比
+`build.ninja` 新时,工程走快路径,跳过读取构建程序缓存的那个阶段;在 2026.9.5.4
+之前,快路径只问 glob 的路径集合。数据文件既不在 `src/` 下也没有 C++ 扩展名,mtime
+扫描同样看不见它:改了它,上一次的产出原样留着,构建打印 `Finished dev in 0.00s`。
+现在快路径按缓存记录的方式比较三类输入 —— glob 的路径集合、声明文件的内容哈希、
+声明环境变量的值 —— 因此 `rerun_if_changed` 在两条路径上含义相同。
+
 ### 声明产出而非执行动作:`mcpp::action`(2026.8.5.1+)
 
 在**这里**直接把源码写出来是省事的路,超过一定规模就是错的:它每次 prepare 跑

mcpp.toml

@@ -1,6 +1,6 @@
 [package]
 name        = "mcpp"
-version = "2026.9.5.3"
+version = "2026.9.5.4"
 description = "Modern C++ build & package management tool"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]

modules/versioning/src/version.cppm

@@ -31,6 +31,6 @@ import std;
 
 export namespace mcpp {
 
-inline constexpr std::string_view MCPP_VERSION = "2026.9.5.3";
+inline constexpr std::string_view MCPP_VERSION = "2026.9.5.4";
 
 } // namespace mcpp

src/build/build_program.cppm

@@ -255,8 +255,9 @@ std::expected<void, std::string> run_build_program(
     const mcpp::manifest::CppStandardConfig& cppStandard,
     const BuildProgramEnv& env);
 
-// #359: has any recorded glob input's path SET changed since its build.mcpp
-// cache was written?
+// Has any recorded build-program input changed since its build.mcpp cache was
+// written: a glob's path SET (#359), a declared file's CONTENT, or a declared
+// environment variable's value?
 //
 // The project-level fast path skips prepare_build entirely when no source is
 // newer than build.ninja, and prepare is where the build.mcpp cache is
@@ -267,10 +268,19 @@ std::expected<void, std::string> run_build_program(
 // the build.mcpp source itself; a glob is one more kind of build-program input,
 // so it belongs to the same question.
 //
+// A DECLARED FILE IS THE SAME QUESTION AND WAS NOT ASKED (2026.9.5.4). The
+// mtime sweep that guards the fast path walks SOURCES, so a data file a build
+// program reads -- `rerun_if_changed("data/table.csv")` -- is invisible to it,
+// and this function used to skip a cache record that carried no glob at all.
+// The result was that editing such a file left the generated header from the
+// previous build in place: `Finished dev in 0.00s`, and the program compiled
+// the previous bytes. `mcpp.tools.embed` is the case that found it. Contents,
+// not mtime, exactly as the cache records them.
+//
 // Scans the caches under `<projectRoot>/target/.build-mcpp` (the root's own and
-// each dependency's). Each cache records the root its globs were relative to,
-// so a dependency's glob is evaluated against the dependency's tree.
-bool glob_inputs_stale(const std::filesystem::path& projectRoot);
+// each dependency's). Each cache records the root its entries were relative to,
+// so a dependency's input is evaluated against the dependency's tree.
+bool program_inputs_stale(const std::filesystem::path& projectRoot);
 
 } // namespace mcpp::build
 
@@ -1199,7 +1209,7 @@ std::expected<void, std::string> run_build_program(
     return {};
 }
 
-bool glob_inputs_stale(const fs::path& projectRoot) {
+bool program_inputs_stale(const fs::path& projectRoot) {
     std::error_code ec;
     const fs::path base = projectRoot / "target" / ".build-mcpp";
     if (!fs::exists(base, ec)) return false;
@@ -1216,11 +1226,19 @@ bool glob_inputs_stale(const fs::path& projectRoot) {
         if (it.depth() >= 3) { it.disable_recursion_pending(); continue; }
         if (it->path().filename() != "build.mcpp.cache") continue;
         auto rec = read_cache(it->path().parent_path());
-        if (!rec.loaded || rec.globs.empty() || rec.rootPath.empty()) continue;
+        if (!rec.loaded || rec.rootPath.empty()) continue;
         fs::path recRoot{rec.rootPath};
         auto outName = output_dir_name(recRoot, it->path().parent_path());
         for (auto const& [h, pattern] : rec.globs)
             if (dirs::glob_fingerprint(recRoot, pattern, outName) != h) return true;
+        // The same comparison `cache_fresh` makes when prepare_build runs. It
+        // is repeated here rather than shared because the fast path has no
+        // manifest, no toolchain and no context hash -- only the recorded
+        // entries and the tree they were measured against.
+        for (auto const& [h, rel] : rec.inputs)
+            if (mcpp::toolchain::hash_file(abs_against_root(recRoot, rel)) != h) return true;
+        for (auto const& [h, name] : rec.envs)
+            if (mcpp::toolchain::hash_string(env_value(name)) != h) return true;
     }
     return false;
 }

src/build/execute.cppm

@@ -918,7 +918,12 @@ bool sources_newer_than(const std::filesystem::path& projectRoot,
     // sweep therefore cannot see it, and the fast path would report
     // "Finished dev in 0.00s" while the new file is never generated. Same
     // question as the build.mcpp check above, different kind of input.
-    if (mcpp::build::glob_inputs_stale(projectRoot)) return true;
+    //
+    // 2026.9.5.4: the same call now also compares a declared FILE's content and
+    // a declared environment variable's value. The sweep below walks sources,
+    // so a data file a build program reads is invisible to it for the same
+    // reason a new .proto is.
+    if (mcpp::build::program_inputs_stale(projectRoot)) return true;
     // mcpp#365: an author-written `.rc` is a third input of the same kind. It
     // is not under src/ and has no C++ extension, so the sweep below cannot see
     // it — and unlike the icon or a header the script includes, editing it can

tests/e2e/612_build_program_file_input_fast_path.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# requires: gcc
+# 612_build_program_file_input_fast_path.sh — editing a file a build program
+# declared with `rerun_if_changed` rebuilds, even on the fast path
+# (mcpp 2026.9.5.4+).
+#
+# The fast path skips prepare_build when no SOURCE is newer than build.ninja,
+# and prepare_build is where the build.mcpp cache is consulted. A data file is
+# not a source: it has no C++ extension and does not live under src/, so the
+# mtime sweep cannot see it, and the staleness check the fast path did run
+# asked only about glob path SETS. Editing the file therefore left the header
+# generated by the previous run in place, `mcpp build` reported
+# "Finished dev in 0.00s", and the program kept compiling the previous bytes.
+#
+# The criterion is the program's OUTPUT, not a line of build log: a stale
+# header and a fresh one differ in what the binary prints.
+set -e
+
+TMP=$(mktemp -d)
+trap "rm -rf $TMP" EXIT
+cd "$TMP"
+
+"$MCPP" new probe > /dev/null; cd probe
+rm -f src/*.cppm
+mkdir -p data
+printf 'first\n' > data/value.txt
+
+cat > mcpp.toml <<'EOT'
+[package]
+name = "probe"
+version = "0.1.0"
+[language]
+standard = "c++23"
+modules = true
+import_std = true
+
+[targets.probe]
+kind = "bin"
+main = "src/main.cpp"
+EOT
+
+# A build program that reads a data file and writes a header from it. No
+# action is submitted: the work happens while the program runs, which is the
+# shape `mcpp.tools.embed` has and the shape the fast path used to skip.
+cat > build.mcpp <<'EOT'
+import std;
+import mcpp;
+int main() {
+    const std::filesystem::path root(mcpp::manifest_dir());
+    const std::filesystem::path gen(std::string(mcpp::out_dir()) + "/include");
+    std::error_code ec;
+    std::filesystem::create_directories(gen, ec);
+    std::ifstream in(root / "data" / "value.txt");
+    std::string value;
+    std::getline(in, value);
+    std::ofstream out(gen / "value.h", std::ios::trunc);
+    out << "#pragma once\n#define PROBE_VALUE \"" << value << "\"\n";
+    mcpp::rerun_if_changed((root / "data" / "value.txt").string().c_str());
+    mcpp::include_dir(gen.string().c_str());
+    return 0;
+}
+EOT
+
+cat > src/main.cpp <<'EOT'
+#include <cstdio>
+#include "value.h"
+int main() { std::printf("VALUE=%s\n", PROBE_VALUE); }
+EOT
+
+value() { "$MCPP" run 2>&1 | grep '^VALUE=' | tail -1; }
+
+"$MCPP" build > b1.log 2>&1 || { cat b1.log; echo "FAIL: the first build failed"; exit 1; }
+[[ "$(value)" == "VALUE=first" ]] || { echo "FAIL: the first build did not embed the first value"; exit 1; }
+
+# Content only. The path set is unchanged, so a glob fingerprint cannot see
+# this, and no source's mtime moves.
+printf 'second\n' > data/value.txt
+
+"$MCPP" build > b2.log 2>&1 || { cat b2.log; echo "FAIL: the second build failed"; exit 1; }
+out="$(value)"
+[[ "$out" == "VALUE=second" ]] || {
+    echo "FAIL: a declared file input changed and the build replayed the old header ($out)"
+    cat b2.log
+    exit 1
+}
+echo "PASS: a declared file input is compared on the fast path"
+
+# The mirror half: an unchanged input must NOT force work. Two builds in a row
+# with nothing touched, and the second one has to take the fast path -- without
+# this the fix could be "always rebuild", which passes the assertion above and
+# is not the behaviour asked for.
+"$MCPP" build > b3.log 2>&1
+grep -qE 'Finished .* in ' b3.log || { cat b3.log; echo "FAIL: the third build did not finish"; exit 1; }
+"$MCPP" build > b4.log 2>&1
+grep -q 'Compiling probe' b4.log && { cat b4.log; echo "FAIL: an unchanged input recompiled the project"; exit 1; }
+echo "PASS: an unchanged input still takes the fast path"

tests/unit/test_source_kind.cpp

@@ -116,7 +116,7 @@ TEST(SourceKind, PredicatesAgreeWithTheKind) {
     // Assembly is absent on purpose — it has no import and no scanned include
     // graph, so editing one changes its object (ninja tracks that) and nothing
     // else. A NEW assembly file is a different question, answered by
-    // glob_inputs_stale.
+    // program_inputs_stale.
     EXPECT_TRUE(mcpp::affects_graph_shape(SourceKind::ModuleInterface));
     EXPECT_TRUE(mcpp::affects_graph_shape(SourceKind::Cxx));
     EXPECT_TRUE(mcpp::affects_graph_shape(SourceKind::C));
@@ -305,7 +305,7 @@ TEST(SourceKind, DevicePredicates) {
     EXPECT_FALSE(mcpp::is_cxx_like(SourceKind::Device));
     EXPECT_FALSE(mcpp::links_unconditionally(SourceKind::Device));
     // Absent for the same reason assembly is absent: the content change is
-    // tracked by ninja, and a NEW file is `glob_inputs_stale`'s question.
+    // tracked by ninja, and a NEW file is `program_inputs_stale`'s question.
     EXPECT_FALSE(mcpp::affects_graph_shape(SourceKind::Device));
     EXPECT_EQ(mcpp::to_string(SourceKind::Device), "device");
 }