test(cross): pin that a cross build declares the artifact it produces

Adds ArtifactNaming (a (os, env) function on the target triple) plus the
regression assertion for a defect that exists on HEAD today.

plan.cppm's target_output() spells the artifact suffix from
mcpp::platform::exe_suffix — a HOST constant. Cross-compiling Linux -> PE that
yields `bin/foo` while mingw's GCC driver writes `bin/foo.exe`, so the file
ninja was told to produce never appears. ninja finds the declared output
missing on every run and reruns the link edge forever.

The e2e asserts both the cause and its observable consequence: that the
declared ninja output exists, and that an up-to-date rebuild does not change
the artifact's mtime.

Verified RED before the fix:

    FAIL: ninja declares output 'bin/relinkprobe' but that file does not exist
          actually produced: relinkprobe.exe
          => the link edge can never be satisfied, so it reruns every build

The unit tests cover ArtifactNaming's own logic, including the part a single
_WIN32 branch cannot express: windows-gnu uses the GNU convention (libfoo.a)
while windows-msvc uses foo.lib. They pass a deliberately bogus host answer, so
any assertion leaking through to the host axis fails loudly.

None of the other cross tests could have caught this: they look for the REAL
artifact (find -name '*.exe'), not for what ninja declared, so both of their
assertions hold while the inconsistency sits underneath them.

Refs .agents/docs/2026-08-03-b3-target-aware-artifact-naming.md

Author: Sunrisepeak

src/toolchain/triple.cppm

@@ -173,6 +173,74 @@ namespace pins {
     inline constexpr std::string_view kSuggestGccMingw      = "gcc 16.1.0";
 } // namespace pins
 
+// ── Artifact naming conventions ──────────────────────────────────────────────
+//
+// How a built artifact is NAMED is a property of the TARGET, never of the
+// machine doing the build. `mcpp::platform::{exe_suffix,lib_prefix,…}` answer a
+// different question — "what does THIS machine call its own binaries" — and
+// using them to name build outputs is wrong the moment host != target.
+//
+// It is a function of (os, env), not of os alone. The trap:
+//
+//   x86_64-windows-gnu   → libfoo.a    (GNU/mingw convention)
+//   x86_64-windows-msvc  → foo.lib     (MSVC convention)
+//
+// A single `_WIN32` branch cannot express that, which is why building a static
+// library with mingw ON a Windows host produces `foo.lib` today — a GNU archive
+// wearing an MSVC name. That is a pre-existing defect, unrelated to cross
+// compilation.
+//
+// See .agents/docs/2026-08-03-b3-target-aware-artifact-naming.md.
+struct ArtifactNaming {
+    std::string_view exeSuffix;     // ""      | ".exe"
+    std::string_view libPrefix;     // "lib"   | ""
+    std::string_view staticLibExt;  // ".a"    | ".lib"
+    std::string_view sharedLibExt;  // ".so"   | ".dylib" | ".dll"
+    // PE consumers link against an import library, not the .dll itself. mcpp
+    // does not model import libraries yet, so this currently marks "shared
+    // libraries are not supported for this target" rather than describing a
+    // produced artifact. Shared libraries have never been verified end-to-end
+    // on PE or Mach-O — every shared-library e2e declares `# requires: elf`.
+    bool             sharedNeedsImportLib;
+};
+
+// Naming for an explicit target triple. An EMPTY triple means "build for this
+// machine", and only then is the host answer the correct one — so the caller
+// passes it in rather than this module reaching for mcpp::platform, which keeps
+// the decision testable from any host (and keeps this module dependency-free).
+inline ArtifactNaming artifact_naming(const Triple& t, const ArtifactNaming& hostNaming) {
+    if (t.empty()) return hostNaming;
+
+    if (t.os == "windows") {
+        // PE. The static-library convention splits on env, not on os.
+        const bool msvc = t.is_msvc_env();
+        return ArtifactNaming{
+            .exeSuffix            = ".exe",
+            .libPrefix            = msvc ? "" : "lib",
+            .staticLibExt         = msvc ? ".lib" : ".a",
+            .sharedLibExt         = ".dll",
+            .sharedNeedsImportLib = true,
+        };
+    }
+    if (t.os == "macos") {
+        return ArtifactNaming{
+            .exeSuffix = "", .libPrefix = "lib",
+            .staticLibExt = ".a", .sharedLibExt = ".dylib",
+            .sharedNeedsImportLib = false,
+        };
+    }
+    if (t.os == "linux") {
+        return ArtifactNaming{
+            .exeSuffix = "", .libPrefix = "lib",
+            .staticLibExt = ".a", .sharedLibExt = ".so",
+            .sharedNeedsImportLib = false,
+        };
+    }
+    // Outside the triple language: fall back to the host answer rather than
+    // guessing. A wrong guess here silently misnames every artifact.
+    return hostNaming;
+}
+
 } // namespace mcpp::toolchain::triple
 
 namespace mcpp::toolchain::triple {

tests/e2e/183_cross_no_relink.sh

@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+# requires: mingw-cross
+#
+# A cross build must not relink on every invocation.
+#
+# plan.cppm's target_output() used to spell the artifact suffix from
+# mcpp::platform::exe_suffix — a HOST constant. Cross-compiling from Linux to
+# a PE target, that yields `bin/foo` while mingw's GCC driver writes
+# `bin/foo.exe`, so the file ninja was told to produce never appears. ninja
+# finds the declared output missing on every run and reruns the link edge
+# forever: incremental builds are effectively off for PE targets.
+#
+# The symptom is invisible to the other cross tests because they look for the
+# REAL artifact (`find -name '*.exe'`), not for what ninja declared — both of
+# their assertions hold while the inconsistency sits underneath them.
+#
+# See .agents/docs/2026-08-03-b3-target-aware-artifact-naming.md.
+set -euo pipefail
+
+TMP="$(mktemp -d)"
+trap 'rm -rf "$TMP"' EXIT
+cd "$TMP"
+
+mkdir -p src
+cat > mcpp.toml <<'EOF'
+[package]
+name    = "relinkprobe"
+version = "0.1.0"
+EOF
+
+cat > src/main.cpp <<'EOF'
+int main() { return 0; }
+EOF
+
+TRIPLE=x86_64-windows-gnu
+
+"$MCPP" build --target "$TRIPLE" > "$TMP/build1.log" 2>&1 || {
+    echo "first cross build failed:"; cat "$TMP/build1.log"; exit 1; }
+
+# The produced artifact — whatever it is actually called.
+ART="$(find "target/$TRIPLE" -type f -path '*/bin/*' -name 'relinkprobe*' | head -1)"
+[[ -n "$ART" ]] || { echo "no artifact produced under target/$TRIPLE"; exit 1; }
+
+# ── The declared ninja output must be the file that actually gets written ────
+# This is the root assertion. Positive grep on purpose: `! cmd | grep` is exempt
+# from errexit and can never fail.
+NINJA="$(find "target/$TRIPLE" -name build.ninja | head -1)"
+[[ -n "$NINJA" ]] || { echo "no build.ninja found"; exit 1; }
+
+DECLARED="$(grep -oE '^build [^:]*bin/relinkprobe[^ :]*' "$NINJA" | head -1 | sed 's/^build //' | tr -d ' ')"
+[[ -n "$DECLARED" ]] || { echo "no link edge for relinkprobe in build.ninja"; exit 1; }
+
+BUILDDIR="$(dirname "$NINJA")"
+if [[ ! -f "$BUILDDIR/$DECLARED" ]]; then
+    echo "FAIL: ninja declares output '$DECLARED' but that file does not exist"
+    echo "      actually produced: $(basename "$ART")"
+    echo "      => the link edge can never be satisfied, so it reruns every build"
+    exit 1
+fi
+
+# ── And the observable consequence: a second build must not relink ──────────
+T1="$(stat -c %Y "$ART" 2>/dev/null || stat -f %m "$ART")"
+sleep 1   # ensure a relink would be visible at 1s mtime granularity
+"$MCPP" build --target "$TRIPLE" > "$TMP/build2.log" 2>&1 || {
+    echo "second cross build failed:"; cat "$TMP/build2.log"; exit 1; }
+T2="$(stat -c %Y "$ART" 2>/dev/null || stat -f %m "$ART")"
+
+if [[ "$T1" != "$T2" ]]; then
+    echo "FAIL: artifact was relinked on an up-to-date rebuild ($T1 -> $T2)"
+    echo "      ninja declared: $DECLARED"
+    echo "      produced:       $(basename "$ART")"
+    exit 1
+fi
+
+echo "OK: cross build declares the artifact it actually produces, and does not relink"

tests/unit/test_artifact_naming.cpp

@@ -0,0 +1,125 @@
+#include <gtest/gtest.h>
+
+import std;
+import mcpp.platform;
+import mcpp.toolchain.triple;
+
+// How a built artifact is NAMED is a property of the TARGET, never of the
+// machine doing the build.
+//
+// mcpp used to answer it with mcpp::platform::{exe_suffix,lib_prefix,
+// static_lib_ext,shared_lib_ext} — host constants selected by
+// `#if defined(_WIN32)/__APPLE__`. On a host build the two questions coincide,
+// which is why this survived; it only diverges once host != target.
+//
+// The host answer is threaded in as a parameter precisely so these can be
+// pinned from any host: the `hostNaming` argument models "what the build
+// machine would have said", and every assertion below that passes a deliberately
+// wrong one is checking that the target answer wins.
+
+namespace {
+
+namespace tr = mcpp::toolchain::triple;
+
+// A deliberately WRONG host answer. If any assertion below leaks through to it,
+// the target axis is not being honoured.
+constexpr tr::ArtifactNaming kBogusHost{
+    .exeSuffix = ".HOST", .libPrefix = "HOST", .staticLibExt = ".HOST",
+    .sharedLibExt = ".HOST", .sharedNeedsImportLib = false,
+};
+
+tr::Triple T(std::string_view s) {
+    auto t = tr::parse(s);
+    return t ? *t : tr::Triple{};
+}
+
+// ── The regression: naming must not come from the build host ────────────────
+
+TEST(ArtifactNaming, LinuxTargetIgnoresHostAnswer) {
+    auto n = tr::artifact_naming(T("x86_64-linux-musl"), kBogusHost);
+    EXPECT_EQ(n.exeSuffix, "");
+    EXPECT_EQ(n.libPrefix, "lib");
+    EXPECT_EQ(n.staticLibExt, ".a");
+    EXPECT_EQ(n.sharedLibExt, ".so");
+    EXPECT_FALSE(n.sharedNeedsImportLib);
+}
+
+TEST(ArtifactNaming, MacosTargetIgnoresHostAnswer) {
+    auto n = tr::artifact_naming(T("aarch64-macos"), kBogusHost);
+    EXPECT_EQ(n.exeSuffix, "");
+    EXPECT_EQ(n.libPrefix, "lib");
+    EXPECT_EQ(n.staticLibExt, ".a");
+    EXPECT_EQ(n.sharedLibExt, ".dylib");
+    EXPECT_FALSE(n.sharedNeedsImportLib);
+}
+
+// ── The (os, env) split — the part a single _WIN32 branch cannot express ─────
+//
+// windows-gnu uses the GNU convention. mcpp names this `foo.lib` today even on
+// a Windows host, so mingw's `ar` emits a GNU archive wearing an MSVC name.
+// That is a pre-existing defect, independent of cross compilation.
+TEST(ArtifactNaming, WindowsGnuUsesGnuConvention) {
+    auto n = tr::artifact_naming(T("x86_64-windows-gnu"), kBogusHost);
+    EXPECT_EQ(n.exeSuffix, ".exe");
+    EXPECT_EQ(n.libPrefix, "lib");       // NOT ""
+    EXPECT_EQ(n.staticLibExt, ".a");     // NOT ".lib"
+    EXPECT_EQ(n.sharedLibExt, ".dll");
+    EXPECT_TRUE(n.sharedNeedsImportLib);
+}
+
+TEST(ArtifactNaming, WindowsMsvcUsesMsvcConvention) {
+    auto n = tr::artifact_naming(T("x86_64-windows-msvc"), kBogusHost);
+    EXPECT_EQ(n.exeSuffix, ".exe");
+    EXPECT_EQ(n.libPrefix, "");
+    EXPECT_EQ(n.staticLibExt, ".lib");
+    EXPECT_EQ(n.sharedLibExt, ".dll");
+    EXPECT_TRUE(n.sharedNeedsImportLib);
+}
+
+// The legacy mingw spelling must resolve identically to the canonical one —
+// the triple parser is the single source of truth, not a substring match.
+TEST(ArtifactNaming, LegacyMingwSpellingMatchesCanonical) {
+    auto legacy    = tr::artifact_naming(T("x86_64-w64-mingw32"), kBogusHost);
+    auto canonical = tr::artifact_naming(T("x86_64-windows-gnu"), kBogusHost);
+    EXPECT_EQ(legacy.exeSuffix,    canonical.exeSuffix);
+    EXPECT_EQ(legacy.libPrefix,    canonical.libPrefix);
+    EXPECT_EQ(legacy.staticLibExt, canonical.staticLibExt);
+    EXPECT_EQ(legacy.sharedLibExt, canonical.sharedLibExt);
+}
+
+// ── Host target: the one case where the host answer IS correct ──────────────
+
+TEST(ArtifactNaming, EmptyTripleFallsBackToHost) {
+    auto n = tr::artifact_naming(tr::Triple{}, kBogusHost);
+    EXPECT_EQ(n.exeSuffix, ".HOST");
+    EXPECT_EQ(n.libPrefix, "HOST");
+}
+
+// An unparseable triple must not be guessed at — a wrong guess here silently
+// misnames every artifact of the build.
+TEST(ArtifactNaming, UnknownOsFallsBackToHost) {
+    tr::Triple wasm; wasm.arch = "wasm32"; wasm.os = "unknown";
+    auto n = tr::artifact_naming(wasm, kBogusHost);
+    EXPECT_EQ(n.exeSuffix, ".HOST");
+    EXPECT_EQ(n.staticLibExt, ".HOST");
+}
+
+// ── Host builds must be bit-for-bit unchanged ───────────────────────────────
+// Passing the real host constants for the host target has to reproduce exactly
+// what the old code produced on this machine.
+TEST(ArtifactNaming, RealHostConstantsRoundTrip) {
+    const tr::ArtifactNaming host{
+        .exeSuffix = mcpp::platform::exe_suffix,
+        .libPrefix = mcpp::platform::lib_prefix,
+        .staticLibExt = mcpp::platform::static_lib_ext,
+        .sharedLibExt = mcpp::platform::shared_lib_ext,
+        .sharedNeedsImportLib = mcpp::platform::is_windows,
+    };
+    auto n = tr::artifact_naming(tr::Triple{}, host);
+    EXPECT_EQ(n.exeSuffix,    mcpp::platform::exe_suffix);
+    EXPECT_EQ(n.libPrefix,    mcpp::platform::lib_prefix);
+    EXPECT_EQ(n.staticLibExt, mcpp::platform::static_lib_ext);
+    EXPECT_EQ(n.sharedLibExt, mcpp::platform::shared_lib_ext);
+}
+
+} // namespace