runtime_search_dir, the prepare role, and a stamp newer than every input (mcpp#701, mcpp#702)

Re-implements #701/#702's two prior commits to design
.agents/docs/2026-09-26-compile-database-and-issue-699-design.md §5.4, and
adds P, the `prepare` role the design's O1 asks for. One protocol bump (12)
and one cache-format epoch bump (3) cover all three.

R1'. `mcpp::runtime_search_dir(dir)` (`mcpp:runtime-search-dir=`, protocol
12) replaces the branch's `runtime_library_dir`: a launch-time search
directory a build.mcpp discovers (a vcpkg prefix's `bin/`, a Qt SDK's
`bin/`, a directory a `prepare` action populates) rather than one an author
writes into a fixed TOML array. It lands DIRECTLY on
`LinkIntent::runtimeSearchDirs` -- the field `runtime_search_dirs` itself
populates -- not the retiring `RuntimeConfig::libraryDirs` the branch had
joined by mistake, so every existing reader (the plan merge, RUNPATH/rpath,
`mcpp run`'s loader path, `mcpp pack`'s closure search) sees a
directive-declared directory exactly as it sees the manifest key's, and a
dependency's declaration reaches its consumer's executable through the same
merge. The directory need not exist when the program runs.

R2. After a `check` or `prepare` command succeeds, the engine creates every
declared stamp that is missing and sets the modification time of every
existing one to the present, whether or not the command wrote it; on
failure it writes nothing. This replaces the branch's before/after time
comparison with R2's simple form: a stamp feeds no compile or link edge, so
touching one the command already wrote changes no build.

P. The `prepare` role (`mcpp::roles::prepare`, alongside `source`, `check`,
`object`, `artifact`) is for construction whose file names are unknown when
the build program runs -- installing a vcpkg manifest or a CMake subproject
into a prefix, unpacking an SDK. Outputs: one or more stamps, written by the
engine through the same wrapper as `check`, and one declared directory
(`mcpp::action::output_dir`) the command populates. When the command
succeeds and that directory does not exist, the engine writes no stamp and
fails the edge, naming the directory. Every compile edge of the declaring
package waits for it, as a blocking `check` does today; so does every LINK
edge in the plan, because `plan.linkIntent` -- and therefore the `$ldflags`
every link rule interpolates -- is one value merged from every package's
LinkGlobal directives, read alike by the declaring package's own link and
by every package that depends on it. The #534 self-check
(`check_action_ordering`) is extended to assert this for links, the same
way it already does for compiles. Progress lines label it `PREPARE`. An
unknown role string is refused, naming the value and the five roles, where
it used to be read as `source` silently -- the cache-format epoch moves to
3 so a stale entry from before this guard existed is re-validated rather
than replayed two different ways by two code paths. A build program whose
`rerun_if_changed`/`rerun_if_changed_glob` names a path inside a `prepare`
directory (of any package in the graph) is warned, naming both paths: that
directory is populated at build time, after configuration has already run.

Author: speak-agent

modules/buildmcpp/src/directives.cppm

@@ -164,18 +164,23 @@ enum class Slot : std::size_t {
     // splitting it into two slots would let a build with N deploy directives
     // pair them up wrong the moment N > 1.
     Deploy,
-    // A LAUNCH-TIME SEARCH DIRECTORY, THE BUILD-PROGRAM FORM OF `[runtime]
-    // library_dirs` (docs/04 §2.11). A dependency that brings a prebuilt
-    // shared library (a vcpkg prefix's `bin/`, a Qt SDK's `bin/`) knows where
-    // it lives only at build-program time, and the manifest key cannot be
-    // computed -- it is a fixed TOML array. `Transform::AbsPath`, not a new
-    // path shape: this is the SAME field the manifest key feeds
-    // (`RuntimeConfig::libraryDirs`), so every consumer of it -- `mcpp run`'s
-    // loader path, `mcpp pack`'s closure search, and the ELF/Mach-O
-    // `-Wl,-rpath` rendering -- sees a directive-declared entry exactly as it
-    // sees a TOML one, through the one merge in `plan.cppm` that already
-    // exists for the manifest key. No new downstream code path.
-    RuntimeLibraryDir,
+    // A LAUNCH-TIME SEARCH DIRECTORY, THE BUILD-PROGRAM FORM OF
+    // `runtime_search_dirs` (docs/04 §2.11). A dependency that brings a
+    // prebuilt shared library (a vcpkg prefix's `bin/`, a Qt SDK's `bin/`, a
+    // directory a `prepare` action populates) knows where it lives only at
+    // build-program time, and the manifest key is a fixed TOML array.
+    // `Transform::AbsPath`: relative resolves against the package root, like
+    // `include-dir`. Feeds `LinkIntent::runtimeSearchDirs` DIRECTLY --
+    // `runtime_search_dirs`' own field, not the retiring `[runtime]
+    // library_dirs` / `RuntimeConfig::libraryDirs` (docs/04 §2.11 keeps that
+    // one "for one compatibility train" and gains no directive of its own) --
+    // so every reader of `runtimeSearchDirs` (the plan merge, RUNPATH/rpath on
+    // ELF and Mach-O, `mcpp run`'s loader path, `mcpp pack`'s closure search)
+    // sees a directive-declared directory through the one merge that already
+    // exists for the manifest key (`resolve_runtime_contract`, plan.cppm), no
+    // second path to keep in sync. The directory need not exist when the
+    // program runs: a `prepare` action may populate it later, at build time.
+    RuntimeSearchDir,
     Count
 };
 inline constexpr std::size_t kSlotCount = static_cast<std::size_t>(Slot::Count);
@@ -425,29 +430,32 @@ inline constexpr std::array<Def, 27> kTable{{
     // before `apply` on both the run path and the cache-hit path, so a cached
     // replay refuses exactly what a fresh run would.
     {"deploy",              "deploy",            Slot::Deploy,           Scope::LinkGlobal,     Transform::Deploy,        false, "",                           "",                                              11},
-    // v12. The build-program form of `[runtime] library_dirs` (docs/04
-    // §2.11): a launch-time search directory, for a dependency (a vcpkg
-    // prefix's `bin/`, a Qt SDK's `bin/`) whose location a build.mcpp learns
-    // rather than one an author can write into TOML. Scope::LinkGlobal,
-    // exactly as `deploy` above, because `apply` folds it into
-    // `RuntimeConfig::libraryDirs` -- the SAME field the manifest key
-    // populates -- so `resolve_runtime_contract`'s per-package merge
-    // (plan.cppm) carries it into a consumer's `linkIntent.runtimeSearchDirs`
-    // through the one path that already exists for the manifest key, rather
-    // than a second one this table would have to keep in sync. `mustExistAfterRun`
-    // is FALSE: a directory is not the declared-output contract's shape
-    // (`generated=`/`source=` name a file), and the directory need not even
-    // exist yet -- a payload not installed on this machine is the manifest
-    // key's own behaviour (`xpkg_dir()` returning empty configures no runner,
-    // silently and correctly).
+    // v12 (mcpp#701/#702, design §5.4 R1'). The build-program form of
+    // `runtime_search_dirs` (docs/04 §2.11): a launch-time search directory,
+    // for a dependency (a vcpkg prefix's `bin/`, a Qt SDK's `bin/`, a
+    // directory a `prepare` action populates) whose location a build.mcpp
+    // learns rather than one an author can write into TOML. Scope::LinkGlobal,
+    // exactly as `deploy` above, because `apply` folds it DIRECTLY into
+    // `LinkIntent::runtimeSearchDirs` -- NOT `RuntimeConfig::libraryDirs`,
+    // which docs/04 §2.11 keeps readable "for one compatibility train" and
+    // which gains no directive -- so `resolve_runtime_contract`'s per-package
+    // merge (plan.cppm) carries it into a consumer's `linkIntent
+    // .runtimeSearchDirs` through the one path that already exists for the
+    // manifest key, rather than a second one this table would have to keep in
+    // sync. `mustExistAfterRun` is FALSE: a directory is not the
+    // declared-output contract's shape (`generated=`/`source=` name a file),
+    // and the directory need not even exist when this program runs -- a
+    // `prepare` action (§3) may populate it later, at build time, which is
+    // the reason this directive exists at all rather than a plain manifest
+    // array.
     //
     // kCacheEpoch is NOT bumped, the same reasoning `warning`/`pack-format`
     // state explicitly: an entry written before this row carries no
-    // `d runtime-library-dir` line, and the program that wrote it could not
+    // `d runtime-search-dir` line, and the program that wrote it could not
     // emit one -- so replaying it yields exactly what that program said, and
     // the entry is still correct. An older engine reading a newer entry
     // already discards the whole record through the unknown-tag path.
-    {"runtime-library-dir", "runtime-library-dir", Slot::RuntimeLibraryDir, Scope::LinkGlobal, Transform::AbsPath,       false, "",                           "",                                              12},
+    {"runtime-search-dir",  "runtime-search-dir", Slot::RuntimeSearchDir, Scope::LinkGlobal, Transform::AbsPath,       false, "",                           "",                                              12},
 }};
 
 // ── Collected output of one run ────────────────────────────────────────────
@@ -980,13 +988,14 @@ void apply(mcpp::manifest::Manifest& m, const Directives& d) {
     for (auto const& p : d.at(Slot::IncludeDirsAfter))
         bc.includeDirsAfter.emplace_back(p);
 
-    // `runtime-library-dir`: already absolute from the AbsPath
-    // transform, like IncludeDirs above. Joins `RuntimeConfig::libraryDirs`,
-    // the exact field `[runtime] library_dirs` populates from TOML -- so a
-    // consumer sees it exactly as it sees the manifest key, folded in by the
-    // SAME merge (plan.cppm's `resolve_runtime_contract`), never a second one.
-    for (auto const& p : d.at(Slot::RuntimeLibraryDir))
-        m.runtimeConfig.libraryDirs.emplace_back(p);
+    // `runtime-search-dir`: already absolute from the AbsPath transform, like
+    // IncludeDirs above. Joins `LinkIntent::runtimeSearchDirs` DIRECTLY, the
+    // exact field `[runtime] runtime_search_dirs` populates from TOML -- not
+    // the retiring `RuntimeConfig::libraryDirs` -- so a consumer sees it
+    // exactly as it sees the manifest key, folded in by the SAME merge
+    // (plan.cppm's `resolve_runtime_contract`), never a second one.
+    for (auto const& p : d.at(Slot::RuntimeSearchDir))
+        m.runtimeConfig.linkIntent.runtimeSearchDirs.emplace_back(p);
 
     // Claims join the runtime declarations the manifest could have carried
     // itself, so the version-floor check in prepare reads ONE list and never
@@ -1049,15 +1058,55 @@ void apply(mcpp::manifest::Manifest& m, const Directives& d) {
     }
 }
 
+// The five roles `mcpp::action::role` may name, in the order
+// `mcpp::manifest::BuildAction::Role` declares them (mcpp#702). A build.mcpp
+// SHOULD spell one of `mcpp::roles::{source, check, object, artifact,
+// prepare}` (SPEC-007 R3.6): those constants exist only from protocol 12, so
+// a program that misspells the role fails to COMPILE on an older engine and
+// names the missing constant, instead of reaching this decoder as an
+// unrecognised string. A hand-written `printf("mcpp:action=...")` program
+// (the frozen surface, protocol 0) has no such guard, which is the case this
+// list is for.
+constexpr std::array<std::string_view, 5> kActionRoles{
+    "source", "check", "object", "artifact", "prepare"};
+
+bool is_known_action_role(std::string_view role) {
+    return std::ranges::find(kActionRoles, role) != kActionRoles.end();
+}
+
+// The bare `role` an `mcpp:action=` payload named, or "source" when the key
+// is absent (the same default `decode_action` uses) -- independent of
+// whether the REST of the payload is well-formed, so `action_error` can name
+// an unrecognised role even when the action is otherwise malformed, instead
+// of folding both failures into one generic message.
+std::optional<std::string> action_role_of(std::string_view payload) {
+    try {
+        auto j = nlohmann::json::parse(payload);
+        return j.value("role", std::string{"source"});
+    } catch (...) {
+        return std::nullopt;
+    }
+}
+
 std::optional<mcpp::manifest::BuildAction> decode_action(std::string_view payload) {
     try {
         auto j = nlohmann::json::parse(payload);
         mcpp::manifest::BuildAction a;
         a.id = j.value("id", std::string{});
         auto role = j.value("role", std::string{"source"});
+        // An unrecognised role is refused here, not read as Source: before
+        // mcpp#702 this fell through to Source silently, changing an action's
+        // meaning without a word (SPEC-007 R3.6). `action_error` names the
+        // offending value before anything is applied; this path is also the
+        // one a cache-hit replay runs through `apply` (which calls no
+        // validator), so it has to refuse on its own rather than assume
+        // `action_error` already ran -- `epoch` 3 (program_protocol.cppm)
+        // makes sure no such entry survives from before this row existed.
+        if (!is_known_action_role(role)) return std::nullopt;
         a.role = role == "check"    ? mcpp::manifest::BuildAction::Role::Check
                : role == "artifact" ? mcpp::manifest::BuildAction::Role::Artifact
                : role == "object"   ? mcpp::manifest::BuildAction::Role::Object
+               : role == "prepare"  ? mcpp::manifest::BuildAction::Role::Prepare
                                     : mcpp::manifest::BuildAction::Role::Source;
         auto arr = [&](const char* k, std::vector<std::string>& dst) {
             if (auto it = j.find(k); it != j.end() && it->is_array())
@@ -1073,7 +1122,18 @@ std::optional<mcpp::manifest::BuildAction> decode_action(std::string_view payloa
         a.blocking    = j.value("blocking", false);
         a.depfile     = j.value("depfile", std::string{});
         a.description = j.value("description", std::string{});
+        // Omitted by every role but Prepare, exactly as `depfile` is omitted
+        // by an action that declares none -- the decoder's default (empty)
+        // is identical either way, so a cache entry written before this field
+        // existed replays as one that never set it.
+        a.outputDir   = j.value("output_dir", std::string{});
         if (a.command.empty() || a.outputs.empty()) return std::nullopt;
+        // Prepare only: `output_dir` is the whole point of the role (R3.2,
+        // R3.3) -- a `prepare` action with none declared would have a stamp
+        // and nothing else, indistinguishable from a `check` that merely
+        // forgot `blocking = true`.
+        if (a.role == mcpp::manifest::BuildAction::Role::Prepare && a.outputDir.empty())
+            return std::nullopt;
         if (a.id.empty()) a.id = a.outputs.front();
         return a;
     } catch (...) {
@@ -1187,6 +1247,18 @@ std::string action_error(const Directives& d) {
                 "and cannot be used.\n"
                 "       payload: {}", payload);
         }
+        // Named BEFORE the general decode below, so the message identifies
+        // the unrecognised VALUE and lists the five roles the engine knows,
+        // rather than folding it into "malformed action" -- which is what an
+        // unknown role used to become (silently read as Source) until
+        // mcpp#702 (SPEC-007 R3.6).
+        if (auto role = action_role_of(payload); role && !is_known_action_role(*role)) {
+            return std::format(
+                "build.mcpp declared an action with role \"{}\", which is not "
+                "one of the five mcpp knows: source, check, object, artifact, "
+                "prepare.\n"
+                "       payload: {}", *role, payload);
+        }
         if (decode_action(payload)) continue;
         // A malformed action is a hard error, never a skip: an action that
         // silently does not exist produces a build missing generated sources,
@@ -1195,7 +1267,10 @@ std::string action_error(const Directives& d) {
             "build.mcpp declared a malformed action.\n"
             "       Every action needs a non-empty `command` and at least one\n"
             "       declared `output` — mcpp fixes the source set during prepare,\n"
-            "       so an output whose NAME is unknown cannot be built.\n"
+            "       so an output whose NAME is unknown cannot be built. A\n"
+            "       `prepare` action also needs a non-empty `output_dir`\n"
+            "       (mcpp::action::output_dir), the directory its command\n"
+            "       populates.\n"
             "       payload: {}", payload);
     }
     return {};
@@ -1235,6 +1310,14 @@ void prepare_actions(std::vector<mcpp::manifest::BuildAction>& actions,
         // simply never match the file the command actually wrote.
         if (!a.depfile.empty() && a.depfile.find("${mcpp.") == std::string::npos)
             a.depfile = abs_against(pkgRoot, a.depfile);
+        // Prepare only: the same anchoring, for the same reason -- the
+        // directory the command populates and the post-condition the engine
+        // checks after that command succeeds (`__action-stamp`, src/cli.cppm)
+        // both need it absolute, or a package-relative spelling would be
+        // interpreted relative to the ninja build directory instead of the
+        // package root it was written against.
+        if (!a.outputDir.empty() && a.outputDir.find("${mcpp.") == std::string::npos)
+            a.outputDir = abs_against(pkgRoot, a.outputDir);
         if (a.role != mcpp::manifest::BuildAction::Role::Source) continue;
         for (auto const& o : a.outputs) {
             if (o.find("${mcpp.") != std::string::npos) continue;

modules/buildmcpp/src/program_protocol.cppm

@@ -81,13 +81,21 @@ export namespace mcpp::build::program_protocol {
 // at a path relative to the executable. Same cost as v5's: a package calling
 // `mcpp::deploy()` fails on an older engine at the build.mcpp COMPILE, because
 // that engine's bundled module has no such function.
-// v12: adds `runtime-library-dir` -- the build-program form of `[runtime]
-// library_dirs`: a launch-time search directory for a dependency (a vcpkg
-// prefix's `bin/`, a Qt SDK's `bin/`) whose location a build.mcpp learns
-// rather than one an author can write into TOML. Same cost as v5's: a
-// package calling `mcpp::runtime_library_dir()` fails on an older engine at
-// the build.mcpp COMPILE, because that engine's bundled module has no such
-// function.
+// v12 (mcpp#701/#702): adds `runtime-search-dir` -- the build-program form of
+// `runtime_search_dirs`: a launch-time search directory for a dependency (a
+// vcpkg prefix's `bin/`, a Qt SDK's `bin/`, a directory a `prepare` action
+// populates) whose location a build.mcpp learns rather than one an author can
+// write into TOML. Same cost as v5's: a package calling
+// `mcpp::runtime_search_dir()` fails on an older engine at the build.mcpp
+// COMPILE, because that engine's bundled module has no such function.
+//
+// v12 also adds the `prepare` role: construction whose file names are not
+// known when the build program runs. Its constants
+// (`mcpp::roles::{source, check, object, artifact, prepare}`) and its
+// `mcpp::action::output_dir()` method live in the bundled module for the
+// same reason `deploy` and `runtime_search_dir` do -- a program that uses
+// them fails to COMPILE on an older engine, naming the missing symbol,
+// rather than reaching that engine as a string it misreads.
 inline constexpr int kProtocolVersion = 12;
 
 // ── Cache-format epoch ─────────────────────────────────────────────────────
@@ -101,7 +109,17 @@ inline constexpr int kProtocolVersion = 12;
 // Epoch 2 (#359): entries gained `glob` records. An engine that does not know
 // them would replay a strict subset of the declared inputs and call a stale
 // build fresh, which is exactly the silent-wrong-answer this guard exists for.
-inline constexpr int kCacheEpoch = 2;
+// Epoch 3 (mcpp#702): `decode_action` now refuses an `mcpp:action=` payload
+// whose `role` names none of the five the engine knows, where it used to read
+// an unrecognised string as `Source` silently. That is an INTERPRETATION
+// change on an existing tag (`action`, since v1) rather than a new one: an
+// entry cached under epoch 2 could hold such a role and decoded successfully
+// then; replaying it through `apply` (which runs no validator) would now
+// either refuse or, worse, silently drop the action, neither of which is what
+// a fresh run of the SAME build.mcpp would do. Bumping the epoch forces one
+// fresh run, which goes through `action_error` and reports exactly what
+// changed, instead of a stale entry reinterpreted two ways by two code paths.
+inline constexpr int kCacheEpoch = 3;
 
 // ── Run bound ──────────────────────────────────────────────────────────────
 //