The realised [c-abi] environment reaches assembly units too

A .S unit's command line is assembled independently of a .c/.cpp unit's
(mcpp.build.flags::CompileFlags::as, not ::cc/::cxx), and only inherits the
-D/-U/-I subset of a package's C flags on purpose -- a -std= or -O token
meant for the C compiler is meaningless to GAS. The realised environment
broadcast landed only in privateBuild.cflags/cxxflags, so it never reached
that narrower channel: within one package a .c unit saw _WIN32 undefined
while a .S unit still saw it defined, because --target=/-fno-short-wchar
never reached the assembler's command line at all. Found by the openkal-musl
spike (okm_setjmp.S, and upstream libunwind's assembly.h, both select
register-save sets on that macro) -- a jmp_buf written by one save set and
sized by the other header is a silent mismatch, the exact failure class this
feature exists to remove.

Adds UsageRequirements::asmflags, a broadcast-only channel parallel to
cflags/cxxflags (no [build] asmflags manifest key backs it -- per-glob
`flags = [{ asmflags }]` remains the author-facing one), and routes the
realised environment tokens into it for GAS units only: NASM has no
--target= concept and accepts none of these flags, so it must never receive
them, and a unit test pins that split directly. Every token was checked
against clang's assembler-with-cpp front end first; none is rejected, so
nothing is filtered a second time.

e2e 741 gains a .S unit asserting it carries the same tokens main.cpp does.

Author: speak-agent

CHANGELOG.md

@@ -46,6 +46,18 @@
   让它们的出现直接失败构建。(`src/build/prepare.cppm`,`docs/06`)
 - **指纹**:解析出的环境与 `__openkal__` 参与构建指纹,LP64 与 LLP64 两次构建绝不共享输出
   目录。安装钩子的存储键尚未补上同一个缺口,已在 `docs/22` 记录为已知差距。
+- **实现同样到达汇编单元,经 openkal-musl 尖峰实验发现并修订。** 最初的广播只写入每个包的
+  `privateBuild.cflags`/`cxxflags`,`.S` 单元走独立组装的 `f.as`,只从 `packageCflags` 里
+  继承 `-D`/`-U`/`-I` 子集(`unit_asm_flags`,本就如此,为了不让 `-std=`/`-O` 这类对汇编
+  无意义的标志混进去)——`--target=`/`-fno-short-wchar` 因此从未到达汇编器,同一个包里
+  `.c` 单元看到 `_WIN32` 未定义而 `.S` 单元仍看到它已定义(openkal-musl 自己的
+  `okm_setjmp.S`、上游 libunwind 的 `assembly.h` 都按这个宏选目标文件格式分支与寄存器保存
+  集,后果是用 SysV 保存集写、按 Win64 头部量的 `jmp_buf` 悄悄错位)。新增
+  `UsageRequirements::asmflags`——`privateBuild` 内与 `cflags`/`cxxflags` 平行、但只供引擎
+  自己广播用的第三条通道(没有对应的 `[build] asmflags = [...]` 清单键)——把同一份令牌
+  原样送进 `packageAsmflags`,绕开 D/U/I 过滤。实测 clang 对 `-x assembler-with-cpp` 接受
+  这些令牌全集,故未作裁剪。(`src/modgraph/scanner.cppm`、`src/build/prepare.cppm`,e2e
+  `tests/e2e/741_...sh` 新增 `.S` 单元与其上的断言)
 - 文档:`docs/22`(`[c-abi]`、校验、指纹)、`docs/21`(声明的环境如何移动编译三元组而不
   移动链接三元组)、`docs/24`(三组宏、`__openkal__` 的规则、平台单元)、`docs/06`
   (`platform-sdk` 标记)及对应 zh 镜像。

docs/22-target-side.md

@@ -344,8 +344,19 @@ this block, mcpp turns the request into compiler configuration for every
 target-side unit — the C library itself, the C++ runtime, the compiler
 runtime's builtins, and every ordinary package in the graph — covering C,
 C++ and assembly compiles, the dependency scan, and the `std` module
-precompile alike. mcpp holds one mapping table from request to triple and
-flags, generic knowledge that names no C library:
+precompile alike. Assembly (`.S`/`.s`) needs its own broadcast channel to get
+this: a `.S` unit's command line is assembled independently of a `.c`/`.cpp`
+unit's (`mcpp.build.flags::CompileFlags::as`, not `::cc`/`::cxx`), and only
+takes the `-D`/`-U`/`-I` words out of a package's C flags on purpose — a
+`-std=` or `-O` token meant for the C compiler is meaningless to GAS — so the
+realised environment tokens (`--target=`, `-f[no-]short-wchar`, and anything
+`builtins = "iso"` adds) are broadcast a second time, verbatim, into that
+narrower channel (found missing, and fixed, by the openkal-musl spike: a
+`.c` unit in a package saw `_WIN32` undefined while a `.S` unit in the SAME
+package — real code, like `okm_setjmp.S` and upstream libunwind's
+`assembly.h`, selects register-save sets on it — still saw it defined). mcpp
+holds one mapping table from request to triple and flags, generic knowledge
+that names no C library:
 
 | Target | Request | Realisation |
 |---|---|---|

docs/zh/22-target-side.md

@@ -285,7 +285,14 @@ builtins   = "iso"           # iso | platform(默认 platform)
 
 **实现(realisation)。** 一旦 `c-abi` 层解析到声明了这个块的包,mcpp 就把请求转换成编译器
 配置,作用于目标侧的每一个编译单元——C 库自己、C++ 运行时、编译器运行时的 builtins,以及
-图中所有普通包——覆盖 C、C++、汇编编译,依赖扫描,以及 `std` 模块预编译。mcpp 保存的是一份
+图中所有普通包——覆盖 C、C++、汇编编译,依赖扫描,以及 `std` 模块预编译。汇编(`.S`/`.s`)要
+做到这一点需要自己单独的广播通道:`.S` 单元的命令行是独立组装的(`mcpp.build.flags::
+CompileFlags::as`,不是 `::cc`/`::cxx`),而且它有意只从包的 C 标志里取出 `-D`/`-U`/`-I`
+子集——对 C 编译器有意义的 `-std=` 或 `-O` 之类标志对 GAS 毫无意义——所以实现出来的环境
+令牌(`--target=`、`-f[no-]short-wchar`,以及 `builtins = "iso"` 添加的部分)要原样再广播
+一遍进这条更窄的通道(openkal-musl 尖峰实验发现并修好的缺口:同一个包里 `.c` 单元看到
+`_WIN32` 未定义,`.S` 单元却仍看到它已定义——真实代码,比如 `okm_setjmp.S` 与上游
+libunwind 的 `assembly.h`,正是按这个宏来选寄存器保存集的)。mcpp 保存的是一份
 「请求到三元组与开关」的映射表,是不含包名的通用知识:
 
 | 目标 | 请求 | 实现 |

src/build/prepare.cppm

@@ -11039,6 +11039,27 @@ prepare_build(bool print_fingerprint,
         // line these tokens are appended to is untouched either way, which is
         // what keeps a package that declares neither field byte-identical to
         // a build before this feature existed.
+        //
+        // ALSO INTO `privateBuild.asmflags` (openkal-musl spike, post-review):
+        // the environment is a property of the TARGET, so it has to reach
+        // every translation unit built for that target, assembly (.S/.s)
+        // included — assembly is preprocessed with the same macros, and real
+        // code selects on them (openkal-musl's own `okm_setjmp.S`; upstream
+        // libunwind's `assembly.h`). `cflags`/`cxxflags` do not reach a .S
+        // file wholesale (`mcpp.build.compile_commands::unit_asm_flags` keeps
+        // only their -D/-U/-I words, on purpose — a -std= or -O token meant
+        // for the C compiler has no meaning for GAS), so the object-format
+        // and wchar-width tokens have to be named again here, into the
+        // channel `unit_asm_flags` passes through UNFILTERED. `__openkal__`
+        // needs no second copy: it is a -D, and the -D/-U/-I filter already
+        // carries it from `cflags` into every assembly unit.
+        //
+        // Every token in `cEnvTokens`/`cEnvBuiltinsTokens` was checked against
+        // clang's GAS (`-x assembler-with-cpp`) front end before this was
+        // written (`--target=`, `-f[no-]short-wchar`,
+        // `-fno-builtin-memset_pattern16`) and none is rejected — so nothing
+        // here is filtered a second time; if a future token IS GAS-hostile,
+        // `cenv::realise` is where to split it, not this broadcast.
         if (tc && (tc->kernelAbiIsOpenkal || !tc->cEnvTokens.empty()
                    || !tc->cEnvBuiltinsTokens.empty())) {
             static const std::vector<std::string> kOpenkalDefine = {"-D__openkal__"};
@@ -11050,8 +11071,10 @@ prepare_build(bool print_fingerprint,
                 if (p.manifest.cEnvironment == "platform") continue;
                 appendUniqueFlags(p.privateBuild.cflags, tc->cEnvTokens);
                 appendUniqueFlags(p.privateBuild.cxxflags, tc->cEnvTokens);
+                appendUniqueFlags(p.privateBuild.asmflags, tc->cEnvTokens);
                 appendUniqueFlags(p.privateBuild.cflags, tc->cEnvBuiltinsTokens);
                 appendUniqueFlags(p.privateBuild.cxxflags, tc->cEnvBuiltinsTokens);
+                appendUniqueFlags(p.privateBuild.asmflags, tc->cEnvBuiltinsTokens);
             }
         }
 

src/modgraph/scanner.cppm

@@ -121,6 +121,19 @@ struct UsageRequirements {
     std::vector<std::filesystem::path> includeDirsAfter;
     std::vector<std::string>           cflags;
     std::vector<std::string>           cxxflags;
+    // Whole-package assembler flags. There is no `[build] asmflags = [...]`
+    // manifest key to back this — a per-glob `flags = [{ glob, asmflags }]`
+    // entry is the author-facing channel (scan_one_into applies it below, via
+    // apply_glob_flags) — this field exists only for the engine's own
+    // broadcasts, today the realised [c-abi] environment tokens (design
+    // 2026-09-18 §3.2). `cflags`/`cxxflags` do NOT reach assembly wholesale:
+    // `mcpp.build.compile_commands::unit_asm_flags` narrows a unit's C flags
+    // to their -D/-U/-I words before letting them near a .S file (a -std= or
+    // -O flag meant for the C compiler is meaningless, or worse, to GAS), so
+    // a broadcast that must reach assembly UNFILTERED — `--target=`,
+    // `-f[no-]short-wchar`, the object-format identity itself — has to name
+    // itself here rather than ride along in cflags and be quietly dropped.
+    std::vector<std::string>           asmflags;
     std::vector<std::string>           ldflags;
     std::vector<std::string>           modules;
 };
@@ -1175,7 +1188,8 @@ void scan_one_into(ScanResult& result,
                    const std::vector<std::filesystem::path>& localIncludeDirs,
                    const std::vector<std::filesystem::path>& localIncludeDirsAfter,
                    const std::vector<std::string>& packageCflags,
-                   const std::vector<std::string>& packageCxxflags)
+                   const std::vector<std::string>& packageCxxflags,
+                   const std::vector<std::string>& packageAsmflags = {})
 {
     // This package's own extension table. Built once per package, not per
     // file, and taken from THIS manifest — a dependency is classified by its
@@ -1286,6 +1300,16 @@ void scan_one_into(ScanResult& result,
             u.localIncludeDirsAfter = localIncludeDirsAfter;
             u.packageCflags    = packageCflags;
             u.packageCxxflags  = packageCxxflags;
+            // GAS ONLY. NASM has no `--target=` concept and does not
+            // recognize clang-family flags at all — `packageAsmflags` here is
+            // the engine's own broadcast (today: the realised [c-abi]
+            // environment), and unlike a per-glob `flags = [{asmflags}]`
+            // entry (applied below by apply_glob_flags, to both kinds, which
+            // is safe because THAT list is author-written per glob) it is not
+            // written with any one assembler in mind. A NASM unit still gets
+            // its own per-glob asmflags untouched.
+            if (u.kind == mcpp::SourceKind::GasAsm)
+                u.packageAsmflags = packageAsmflags;
             apply_glob_flags(u);
             normalize_include_flags(root, u.packageCflags);
             normalize_include_flags(root, u.packageCxxflags);
@@ -1305,6 +1329,9 @@ void scan_one_into(ScanResult& result,
         r->localIncludeDirsAfter = localIncludeDirsAfter;
         r->packageCflags = packageCflags;
         r->packageCxxflags = packageCxxflags;
+        // See the identical GAS-only gate in the scan_overrides branch above.
+        if (r->kind == mcpp::SourceKind::GasAsm)
+            r->packageAsmflags = packageAsmflags;
         apply_glob_flags(*r);
         normalize_include_flags(root, r->packageCflags);
         normalize_include_flags(root, r->packageCxxflags);
@@ -1451,8 +1478,21 @@ ScanResult scan_packages(const std::vector<PackageRoot>& packages) {
         auto const& packageCxxflags = p.usageResolved
             ? p.privateBuild.cxxflags
             : p.manifest.buildConfig.cxxflags;
+        // No `!p.usageResolved` fallback here: unlike cflags/cxxflags there is
+        // no `manifest.buildConfig.asmflags` to fall back to (see
+        // `UsageRequirements::asmflags`'s own comment) — a package's whole-
+        // package asm broadcast exists only once usage is resolved. A static
+        // empty vector (rather than a ternary mixing an lvalue with a
+        // temporary) keeps the resolved branch a reference, not a copy — the
+        // same reason packageCflags/packageCxxflags above are two same-typed
+        // lvalues rather than one lvalue and one temporary.
+        static const std::vector<std::string> kNoAsmFlags;
+        auto const& packageAsmflags = p.usageResolved
+            ? p.privateBuild.asmflags
+            : kNoAsmFlags;
         scan_one_into(result, p.root, p.manifest, localIncludeDirs,
-                      localIncludeDirsAfter, packageCflags, packageCxxflags);
+                      localIncludeDirsAfter, packageCflags, packageCxxflags,
+                      packageAsmflags);
     }
     resolve_graph(result);
     return result;
@@ -1497,6 +1537,9 @@ ScanResult scan_packages_p1689(const std::vector<PackageRoot>&     packages,
             r->packageCxxflags = p.usageResolved
                 ? p.privateBuild.cxxflags
                 : p.manifest.buildConfig.cxxflags;
+            // GAS only — see the identical gate in scan_one_into above.
+            if (p.usageResolved && r->kind == mcpp::SourceKind::GasAsm)
+                r->packageAsmflags = p.privateBuild.asmflags;
             result.graph.units.push_back(std::move(*r));
         }
     }

tests/e2e/741_c_abi_environment_declared_by_the_c_library.sh

@@ -14,8 +14,12 @@
 # a provider's block actually reaches the resolved target side, that the
 # realised tokens reach the compile database of an ordinary package, that a
 # package opting out with `c-environment = "platform"` does not receive them,
-# and that a request this engine cannot realise is refused before anything
-# compiles -- rather than compiled wrong and shipped.
+# that a GAS (.S) unit gets the SAME tokens a .c/.cpp unit in the same package
+# does (a defect found by the openkal-musl spike after this test's first
+# version: the substitution reached `f.cc`/`f.cxx` but not `f.as`, so a .c unit
+# saw `_WIN32` undefined while a .S unit in the same package still saw it
+# defined), and that a request this engine cannot realise is refused before
+# anything compiles -- rather than compiled wrong and shipped.
 #
 # `x86_64-windows-gnu` is the flagship target (design's own motivating case),
 # and this test compiles only -- it never links or runs the artifact, so it
@@ -46,6 +50,18 @@ cat > src/main.cpp <<'EOF'
 int main() { return 0; }
 EOF
 
+# A third-party-style assembly unit, mirroring the class of file the
+# coordinator's report named (openkal-musl's `okm_setjmp.S`, upstream
+# libunwind's `assembly.h`): real GAS source that is preprocessed and reads
+# the SAME environment macros a `.c`/`.cpp` unit does. Compiled only (never
+# linked/run), so it needs no runtime -- one label is enough to be valid GAS.
+cat > src/probe.S <<'EOF'
+.text
+.globl cabi_probe_asm_marker
+cabi_probe_asm_marker:
+    ret
+EOF
+
 cat > mcpp.toml <<'EOF'
 [package]
 name    = "cabi-probe"
@@ -155,6 +171,39 @@ if "--target=x86_64-pc-cygwin" not in libc:
     print(f"FAIL: the c-abi provider's own unit is missing the realised triple\n  args: {libc}")
     sys.exit(1)
 
+# The GAS (.S) unit must carry the SAME environment tokens as the C/C++ units
+# of the SAME package -- the defect this leg pins (coordinator report,
+# openkal-musl spike): the substitution used to reach C/C++ compiles only, so
+# a `.c` unit in a package saw `_WIN32` undefined while a `.S` unit in the
+# SAME package still saw it defined, because `--target=`/`-fno-short-wchar`
+# never reached the assembler's command line at all. `--target=` is asserted
+# by full-string match (assembly's flag string is independently assembled --
+# `mcpp.build.flags::f.as`, not `f.cc` -- so a match here proves the token
+# actually reached that channel, not merely that it exists somewhere in the
+# database). `-fno-short-wchar` is meaningless to GAS (no wchar_t in
+# assembly) and is asserted too regardless, on the coordinator's own
+# instruction: "whatever the C units get for the environment, the assembler
+# units should get too, minus anything meaningless to the assembler" --
+# clang accepts the flag for `.S` input (measured, does not error), so
+# nothing here justifies dropping it just because assembly has no use for it.
+asm_args = list(args_for("probe.S"))
+if not asm_args:
+    print("FAIL: could not find the .S unit's compile command at all")
+    sys.exit(1)
+asm_joined = joined(iter(asm_args))
+missing = [tok for tok in ("--target=x86_64-pc-cygwin", "-fno-short-wchar")
+           if tok not in asm_joined]
+if missing:
+    print(f"FAIL: the assembly unit is missing realised tokens {missing} "
+          f"-- the [c-abi] substitution must reach .S the same as .c/.cpp\n"
+          f"  args: {asm_joined}")
+    sys.exit(1)
+present = [tok for tok in ("-U__CYGWIN__", "-U__CYGWIN32__") if tok in asm_joined]
+if present:
+    print(f"FAIL: __CYGWIN__/__CYGWIN32__ must stay defined on assembly too, "
+          f"but found {present}\n  args: {asm_joined}")
+    sys.exit(1)
+
 # openkalwin declared c-environment = "platform" and must NOT see the
 # substituted triple: it needs the real Windows identity to include platform
 # declarations.

tests/unit/test_modgraph.cpp

@@ -541,6 +541,58 @@ TEST(Scanner, UsesResolvedPackagePrivateBuildIncludeDirs) {
     std::filesystem::remove_all(dir);
 }
 
+// The realised [c-abi] environment (design 2026-09-18) broadcasts into
+// `privateBuild.asmflags`, and this proves the wiring on the ONE point that
+// went wrong first (coordinator report, openkal-musl spike): the broadcast
+// must reach a GAS (.S) unit's `packageAsmflags`, exactly as it reaches a
+// `.c`/`.cpp` unit's cflags/cxxflags -- and it must NOT reach a NASM (.asm)
+// unit's, because NASM has no `--target=` concept and does not recognize a
+// single clang-family flag. A `--target=x86_64-pc-cygwin` handed to `nasm`
+// is not a degraded build, it is a build that does not assemble at all, so
+// this is a refusal-shaped guarantee even though nothing here calls
+// `refusal::record`: the wrong list for the wrong assembler.
+TEST(Scanner, ResolvedCEnvAsmflagsReachGasUnitsOnlyNotNasm) {
+    auto dir = make_tempdir("mcpp-scanner-cenv-asm");
+    write(dir / "src" / "gas.S",
+          ".text\n.globl gas_marker\ngas_marker:\n  ret\n");
+    write(dir / "src" / "nasm.asm",
+          "section .text\nglobal nasm_marker\nnasm_marker:\n  ret\n");
+
+    mcpp::manifest::Manifest m;
+    m.package.name = "pkg";
+    m.modules.sources = {"src/*.S", "src/*.asm"};
+
+    PackageRoot p{dir, m};
+    p.usageResolved = true;
+    p.privateBuild.asmflags = {"--target=x86_64-pc-cygwin", "-fno-short-wchar"};
+
+    auto r = scan_packages({p});
+    ASSERT_TRUE(r.errors.empty());
+    ASSERT_EQ(r.graph.units.size(), 2u);
+
+    bool sawGas = false, sawNasm = false;
+    for (auto const& u : r.graph.units) {
+        if (u.kind == mcpp::SourceKind::GasAsm) {
+            sawGas = true;
+            EXPECT_NE(std::find(u.packageAsmflags.begin(), u.packageAsmflags.end(),
+                                "--target=x86_64-pc-cygwin"),
+                     u.packageAsmflags.end())
+                << "the realised environment must reach a GAS unit";
+        } else if (u.kind == mcpp::SourceKind::NasmAsm) {
+            sawNasm = true;
+            EXPECT_EQ(std::find(u.packageAsmflags.begin(), u.packageAsmflags.end(),
+                                "--target=x86_64-pc-cygwin"),
+                     u.packageAsmflags.end())
+                << "NASM does not understand a clang --target= flag and must "
+                   "never receive it";
+        }
+    }
+    EXPECT_TRUE(sawGas);
+    EXPECT_TRUE(sawNasm);
+
+    std::filesystem::remove_all(dir);
+}
+
 TEST(Scanner, PartitionImportFromPrimaryInterface) {
     // Primary module interface: `export module foo;` → logicalName = "foo".
     // `import :tls;` resolves to "foo:tls".