From c8043129df8eb31f5229f8234c3a998822104bb3 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Wed, 16 Sep 2026 06:29:58 +0800
Subject: [PATCH 01/10] dist-web: options::page names the page (#649 P2)

---
 dist/web.cppm                        | 49 +++++++++++++++++++++++++---
 tests/web-consumer/check-web-plan.sh | 29 +++++++++++++++-
 2 files changed, 72 insertions(+), 6 deletions(-)

diff --git a/dist/web.cppm b/dist/web.cppm
index 941f38a..0c33e6f 100644
--- a/dist/web.cppm
+++ b/dist/web.cppm
@@ -1,5 +1,6 @@
 // mcpp.dist.web -- the wasm32-emscripten stem family becomes a static
-// directory a browser can load, with an `index.html` this member writes.
+// directory a browser can load, with a page this member writes (`index.html`
+// unless `options::page` names another).
 //
 // WHY THIS IS NEITHER A RULE NOR A TOOL, AND WHY IT COMPILES NO TRANSLATION
 // UNIT. Same shape `dist/appimage.cppm` and `dist/apple.cppm` already state:
@@ -117,6 +118,14 @@ struct options {
     // `{{title}}` in the template. Empty means `[package] name`.
     std::string title;
 
+    // The page's file name inside the produced directory. Empty means
+    // `index.html`, what a static file server answers for the directory itself.
+    // A bare `*.html` name with no directory component: an Emscripten build
+    // through CMake names the page after the target (`<target>.html`), and a
+    // project that ships such a page keeps its name (#649 P2). A name with a
+    // separator, or without the `.html` extension, is refused at plan time.
+    std::string page;
+
     // Where the produced directory lands. Empty means `<out_dir>/web`.
     std::string output;
     std::string out_dir = std::string(mcpp::out_dir());
@@ -176,6 +185,25 @@ inline std::string target_for(const options& opt) {
     return (n && *n) ? std::string(n) : std::string();
 }
 
+// The page name `options::page` asks for, or the reason it cannot be used.
+// Bare, because the page is written beside the launcher it loads with a
+// relative `<script src>`; a page in a subdirectory would load nothing.
+inline std::expected<std::string, std::string> page_name(const options& opt) {
+    if (opt.page.empty()) return std::string("index.html");
+    const std::string& n = opt.page;
+    if (n.find('/') != std::string::npos || n.find('\\') != std::string::npos)
+        return std::unexpected(std::format(
+            "`options::page` names '{}', which has a directory component; the "
+            "page is written beside `<name>.js`, so it is a bare file name", n));
+    if (n == ".html" || n.size() <= 5 || !n.ends_with(".html"))
+        return std::unexpected(std::format(
+            "`options::page` names '{}', which is not a `*.html` file name", n));
+    if (n.starts_with("."))
+        return std::unexpected(std::format(
+            "`options::page` names '{}', a hidden file a server does not list", n));
+    return n;
+}
+
 inline std::string replace_all_copy(std::string s, std::string_view from, std::string_view to) {
     if (from.empty()) return s;
     std::size_t pos = 0;
@@ -261,6 +289,14 @@ inline plan plan_for(options opt = {}) {
         return p;
     }
 
+    const auto pageFile = page_name(opt);
+    if (!pageFile) {
+        std::cerr << "mcpp.dist.web: " << pageFile.error() << '\n';
+        mcpp::warning(("mcpp.dist.web: " + pageFile.error()).c_str());
+        p.reason = "page name refused";
+        return p;
+    }
+
     if (!opt.template_file.empty()) {
         const std::string tpl =
             (std::filesystem::path(mcpp::manifest_dir()) / opt.template_file).string();
@@ -291,11 +327,14 @@ inline plan plan_for(options opt = {}) {
     const std::string webDir = !opt.output.empty() ? opt.output
                               : (std::filesystem::path(opt.out_dir) / "web").string();
 
+    // The side file carries the page name, so two packs of one program with
+    // different pages do not overwrite each other's rendering; the default
+    // keeps the name 0.11 wrote (`<target>-index.html`).
     const std::string indexSrc =
-        (std::filesystem::path(opt.out_dir) / (target + "-index.html")).string();
+        (std::filesystem::path(opt.out_dir) / (target + "-" + *pageFile)).string();
     if (!write_if_different(indexSrc, templateBytes)) {
         std::cerr << std::format("mcpp.dist.web: cannot write {}", indexSrc) << '\n';
-        p.reason = "cannot write index.html";
+        p.reason = std::format("cannot write {}", *pageFile);
         return p;
     }
 
@@ -363,9 +402,9 @@ inline plan plan_for(options opt = {}) {
     page.role        = "artifact";
     page.description = "INDEX.HTML";
     page.argv    = { "${mcpp.self}", "stage", "--verify", "content", "--output",
-                     webDir + "/index.html", indexSrc };
+                     webDir + "/" + *pageFile, indexSrc };
     page.inputs  = { indexSrc };
-    page.outputs = { webDir + "/index.html" };
+    page.outputs = { webDir + "/" + *pageFile };
     p.steps.push_back(std::move(page));
 
     p.applies = true;
diff --git a/tests/web-consumer/check-web-plan.sh b/tests/web-consumer/check-web-plan.sh
index 96cb001..3878589 100755
--- a/tests/web-consumer/check-web-plan.sh
+++ b/tests/web-consumer/check-web-plan.sh
@@ -73,5 +73,32 @@ out=$(node "$WEB/web-consumer.js")
 [ "$out" = "1-2-3" ] || fail "node did not print 1-2-3 (got: $out)"
 echo "ok: node $WEB/web-consumer.js prints 1-2-3"
 
+echo "== options::page names the page, and refuses a name that is not a bare *.html file =="
+# A copy of this fixture beside it, so its path dependency on the collection
+# (`../..`) still resolves; the copy's build program sets `options::page`.
+PAGE_FIXTURE="../.web-consumer-page"
+rm -rf "$PAGE_FIXTURE"
+mkdir -p "$PAGE_FIXTURE"
+cp -r mcpp.toml build.mcpp src "$PAGE_FIXTURE"/
+sed -i.bak 's|    opt.target = "web-consumer";|    opt.target = "web-consumer";\n    opt.page   = "web-consumer.html";|' "$PAGE_FIXTURE/build.mcpp"
+grep -q 'opt.page   = "web-consumer.html"' "$PAGE_FIXTURE/build.mcpp" \
+    || fail "the named-page fixture was not written" "$PAGE_FIXTURE/build.mcpp"
+( cd "$PAGE_FIXTURE" && "$MCPP" pack --format web --target wasm32-emscripten > pack.log 2>&1 ) \
+    || fail "mcpp pack --format web with options::page failed" "$PAGE_FIXTURE/pack.log"
+PWEB=$(find "$PAGE_FIXTURE/target" -type d -name web | head -1)
+[ -f "$PWEB/web-consumer.html" ] || fail "options::page = web-consumer.html produced no such page" "$PAGE_FIXTURE/pack.log"
+[ -e "$PWEB/index.html" ] && fail "options::page named another page, and index.html was written as well"
+grep -q 'web-consumer.js' "$PWEB/web-consumer.html" || fail "the named page does not load the launcher" "$PWEB/web-consumer.html"
+echo "ok: options::page = web-consumer.html writes that page and no index.html"
+
+sed -i.bak 's|    opt.page   = "web-consumer.html";|    opt.page   = "pages/web-consumer.html";|' "$PAGE_FIXTURE/build.mcpp"
+if ( cd "$PAGE_FIXTURE" && "$MCPP" pack --format web --target wasm32-emscripten > refuse.log 2>&1 ); then
+    fail "options::page = pages/web-consumer.html was accepted" "$PAGE_FIXTURE/refuse.log"
+fi
+grep -q "has a directory component" "$PAGE_FIXTURE/refuse.log" \
+    || fail "the refusal does not say why the page name was refused" "$PAGE_FIXTURE/refuse.log"
+echo "ok: a page name with a directory component is refused, and the refusal says why"
+rm -rf "$PAGE_FIXTURE"
+
 rm -f build.log pack.log
-echo "PASS: dist-web produces a static directory, node runs it, 1-2-3"
+echo "PASS: dist-web produces a static directory, node runs it, 1-2-3; options::page names the page"

From b5f759ebbe7570214ea1b184a5832a2b9fff9b50 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Wed, 16 Sep 2026 06:31:35 +0800
Subject: [PATCH 02/10] dist-apple: options::omit_keys leaves a defaulted
 Info.plist key out (#649 P1)

---
 dist/apple.cppm                          | 38 ++++++++++++++++++++++++
 tests/ios-app-consumer/build.mcpp        | 13 +++++++-
 tests/ios-app-consumer/check-ios-plan.sh | 35 ++++++++++++++++++++++
 3 files changed, 85 insertions(+), 1 deletion(-)

diff --git a/dist/apple.cppm b/dist/apple.cppm
index c76ef34..3888f99 100644
--- a/dist/apple.cppm
+++ b/dist/apple.cppm
@@ -293,6 +293,17 @@ struct options {
     // `NSHighResolutionCapable`) are replaced by the project's value.
     std::string info_plist;
 
+    // DEFAULTED Info.plist KEYS TO LEAVE OUT (0.12.0). A property list has no
+    // null, so `info_plist` can replace a default's value but cannot remove the
+    // key; a project whose other build states neither `NSHighResolutionCapable`
+    // nor `LSRequiresIPhoneOS` names them here (#649 P1). Only the three keys
+    // this member defaults are accepted: a key it derives is refused by name, as
+    // `info_plist` refuses it, and so is any other key, which this member never
+    // writes. A key named here and also set by `info_plist` is refused, because
+    // the two statements contradict each other. A key that does not apply to the
+    // row (`UIDeviceFamily` on macOS) is accepted and changes nothing.
+    std::vector<std::string> omit_keys;
+
     // AN iOS DEVICE BUNDLE'S PROVISIONING PROFILE (0.11.0), manifest-relative or
     // absolute: embedded as `embedded.mobileprovision`, and, when `entitlements`
     // is empty, the source of the entitlements the bundle is signed with (the
@@ -948,6 +959,33 @@ inline plan plan_for(options opt = {}) {
         if (!read_info_plist_fragment(opt.info_plist, extraEntries, replacedKeys, message))
             return refuse(p, "unusable info_plist", message);
     }
+    for (std::size_t i = 0; i < opt.omit_keys.size(); ++i) {
+        const auto& key = opt.omit_keys[i];
+        if (std::ranges::find(derived_plist_keys(), key) != derived_plist_keys().end()) {
+            return refuse(p, "omit_keys names a derived key", std::format(
+                "mcpp.dist.apple: `options::omit_keys` names {}, which this member derives "
+                "from its options and the engine; a derived key cannot be omitted.", key));
+        }
+        if (std::ranges::find(defaulted_plist_keys(), key) == defaulted_plist_keys().end()) {
+            return refuse(p, "omit_keys names a key this member does not default", std::format(
+                "mcpp.dist.apple: `options::omit_keys` names {}, which this member does not "
+                "write; only UIDeviceFamily, LSRequiresIPhoneOS and NSHighResolutionCapable "
+                "can be omitted.", key));
+        }
+        if (std::find(opt.omit_keys.begin(), opt.omit_keys.begin() + static_cast<std::ptrdiff_t>(i), key)
+                != opt.omit_keys.begin() + static_cast<std::ptrdiff_t>(i)) {
+            return refuse(p, "omit_keys names a key twice", std::format(
+                "mcpp.dist.apple: `options::omit_keys` names {} twice.", key));
+        }
+        if (std::ranges::find(replacedKeys, key) != replacedKeys.end()) {
+            return refuse(p, "omit_keys and info_plist name one key", std::format(
+                "mcpp.dist.apple: `options::omit_keys` names {}, and `options::info_plist` ({}) "
+                "sets it; state one of the two.", key, opt.info_plist));
+        }
+    }
+    // An omitted default is written the way a replaced one is: not at all. The
+    // replaced list is what `plist_document` consults, so the two share it.
+    for (auto const& key : opt.omit_keys) replacedKeys.push_back(key);
     if (!opt.entitlements.empty() && !is_file(opt.entitlements)) {
         return refuse(p, "entitlements not found", std::format(
             "mcpp.dist.apple: the entitlements file {} was not found", opt.entitlements));
diff --git a/tests/ios-app-consumer/build.mcpp b/tests/ios-app-consumer/build.mcpp
index 6b830ce..8d90ec1 100644
--- a/tests/ios-app-consumer/build.mcpp
+++ b/tests/ios-app-consumer/build.mcpp
@@ -26,8 +26,19 @@ int main() {
     // leave the options as they are, because the script passes every variable
     // to every row. The macOS runner's real pack names the first one too.
     for (const char* v : {"IOS_APP_CONSUMER_INFO_PLIST", "IOS_APP_CONSUMER_PROFILE",
-                          "IOS_APP_CONSUMER_NO_IDENTITY"})
+                          "IOS_APP_CONSUMER_NO_IDENTITY", "IOS_APP_CONSUMER_OMIT_KEYS"})
         mcpp::rerun_if_env_changed(v);
+    // 0.12.0: `options::omit_keys`, comma-separated in the variable.
+    if (const char* v = std::getenv("IOS_APP_CONSUMER_OMIT_KEYS"); v && *v) {
+        std::string list = v;
+        for (std::size_t b = 0; b <= list.size();) {
+            const auto e = list.find(',', b);
+            const auto key = list.substr(b, e == std::string::npos ? std::string::npos : e - b);
+            if (!key.empty()) opt.omit_keys.push_back(key);
+            if (e == std::string::npos) break;
+            b = e + 1;
+        }
+    }
     if (const char* v = std::getenv("IOS_APP_CONSUMER_INFO_PLIST"); v && *v) opt.info_plist = v;
     if (const char* v = std::getenv("IOS_APP_CONSUMER_PROFILE"); v && *v) opt.provisioning_profile = v;
     if (const char* v = std::getenv("IOS_APP_CONSUMER_NO_IDENTITY"); v && *v) opt.identity.clear();
diff --git a/tests/ios-app-consumer/check-ios-plan.sh b/tests/ios-app-consumer/check-ios-plan.sh
index 6c8320a..39ef243 100755
--- a/tests/ios-app-consumer/check-ios-plan.sh
+++ b/tests/ios-app-consumer/check-ios-plan.sh
@@ -122,6 +122,7 @@ run_row() {
         IOS_APP_CONSUMER_INFO_PLIST="${IOS_APP_CONSUMER_INFO_PLIST:-}" \
         IOS_APP_CONSUMER_PROFILE="${IOS_APP_CONSUMER_PROFILE:-}" \
         IOS_APP_CONSUMER_NO_IDENTITY="${IOS_APP_CONSUMER_NO_IDENTITY:-}" \
+        IOS_APP_CONSUMER_OMIT_KEYS="${IOS_APP_CONSUMER_OMIT_KEYS:-}" \
         "$BIN" > "$log" 2>&1
     echo "$out"
 }
@@ -250,6 +251,40 @@ grep -q 'mcpp.dist.apple.layout' /tmp/ios-plan-sim-derived.log \
 unset IOS_APP_CONSUMER_INFO_PLIST
 echo "ok: an entry this member derives is refused, naming the key"
 
+# ── 0.12.0 ─────────────────────────────────────────────────────────────────
+echo "== 0.12.0: options::omit_keys leaves a defaulted key out =="
+export IOS_APP_CONSUMER_OMIT_KEYS="LSRequiresIPhoneOS"
+outdir=$(run_row simomit ios sim /tmp/ios-plan-sim-omit.log)
+plist="$outdir/IosAppConsumer-Info.plist"
+[ -f "$plist" ] || fail "no Info.plist written with options::omit_keys" /tmp/ios-plan-sim-omit.log
+grep -q '<key>LSRequiresIPhoneOS</key>' "$plist" && fail "LSRequiresIPhoneOS was written although omitted" "$plist"
+grep -q '<key>UIDeviceFamily</key>' "$plist" || fail "omitting one default removed another" "$plist"
+check_terminal_bundle /tmp/ios-plan-sim-omit.log
+export IOS_APP_CONSUMER_OMIT_KEYS="NSHighResolutionCapable,UIDeviceFamily"
+outdir=$(run_row macosomit macos "" /tmp/ios-plan-macos-omit.log)
+plist="$outdir/IosAppConsumer-Info.plist"
+grep -q '<key>NSHighResolutionCapable</key>' "$plist" && fail "NSHighResolutionCapable was written on macOS although omitted" "$plist"
+grep -q '<key>CFBundleExecutable</key>' "$plist" || fail "the macOS plist lost a derived key" "$plist"
+echo "ok: an omitted default is not written, on iOS and on macOS, and the rest of the plist is unchanged"
+
+export IOS_APP_CONSUMER_OMIT_KEYS="CFBundleIdentifier"
+run_row simomitderived ios sim /tmp/ios-plan-sim-omit-derived.log > /dev/null
+grep -q 'names CFBundleIdentifier, which this member derives' /tmp/ios-plan-sim-omit-derived.log \
+    || fail "omitting a derived key was not refused by name" /tmp/ios-plan-sim-omit-derived.log
+grep -q 'mcpp.dist.apple.layout' /tmp/ios-plan-sim-omit-derived.log \
+    && fail "steps were planned although omit_keys was refused" /tmp/ios-plan-sim-omit-derived.log
+export IOS_APP_CONSUMER_OMIT_KEYS="NSCameraUsageDescription"
+run_row simomitother ios sim /tmp/ios-plan-sim-omit-other.log > /dev/null
+grep -q 'names NSCameraUsageDescription, which this member does not write' /tmp/ios-plan-sim-omit-other.log \
+    || fail "omitting a key this member does not default was not refused by name" /tmp/ios-plan-sim-omit-other.log
+export IOS_APP_CONSUMER_OMIT_KEYS="UIDeviceFamily"
+export IOS_APP_CONSUMER_INFO_PLIST="$PWD/info-plist/usage.plist"
+run_row simomitboth ios sim /tmp/ios-plan-sim-omit-both.log > /dev/null
+grep -q 'names UIDeviceFamily, and `options::info_plist`' /tmp/ios-plan-sim-omit-both.log \
+    || fail "a key both omitted and set by info_plist was not refused" /tmp/ios-plan-sim-omit-both.log
+unset IOS_APP_CONSUMER_OMIT_KEYS IOS_APP_CONSUMER_INFO_PLIST
+echo "ok: omitting a derived key, a key this member does not write, or a key info_plist sets is refused by name"
+
 # A provisioning profile is a CMS-signed plist; the member reads the plist from
 # between its markers, so a plan needs only those bytes framed by binary data.
 make_profile() {  # make_profile <file> <application-identifier>

From ad7a3ddf16f3c0274ac689d9c7e16fe1cfd67504 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Wed, 16 Sep 2026 06:39:20 +0800
Subject: [PATCH 03/10] dist-apk follows the engine's strip decision:
 --no-strip and --debug-symbols reach the packed libraries (#649 E5)

---
 dist/apk.cppm                            | 71 ++++++++++++++++++++++--
 tests/apk-consumer/check-apk-features.sh | 42 ++++++++++++++
 2 files changed, 109 insertions(+), 4 deletions(-)

diff --git a/dist/apk.cppm b/dist/apk.cppm
index 3d9ab07..8c31024 100644
--- a/dist/apk.cppm
+++ b/dist/apk.cppm
@@ -221,6 +221,16 @@ struct options {
     // drops the symbol table and the debug information -- what the Android
     // Gradle plugin does to every library it packages, and what `mcpp pack`
     // reports it did.
+    //
+    // FROM 0.12.0 THE ENGINE'S DECISION GOVERNS AS WELL. An engine that strips
+    // what the graph built (mcpp 2026.9.16.1, #649 E5) tells a build program
+    // whether this packaging pass strips (`MCPP_PACK_STRIP`, "1" or "0") and
+    // where `--debug-symbols` sends the separated debug information
+    // (`MCPP_PACK_DEBUG_SYMBOLS_DIR`), so `mcpp pack --no-strip` and
+    // `--debug-symbols <dir>` reach the libraries this member packs as they
+    // reach the ones the engine stages. A library is stripped unless either
+    // this option or the engine says to keep it. An older engine publishes
+    // neither variable, and the member strips as before.
     bool keep_debug_symbols = false;
 
     // LEVEL 1, KOTLIN (0.11.0). One or more directories of `.kt` sources,
@@ -1998,10 +2008,24 @@ inline plan plan_for(options opt = {}) {
     }
     const bool inPlaceLibraries = loads_native_libraries_in_place(manifestBytes);
 
+    // THE ENGINE'S STRIP DECISION (0.12.0), read through the environment
+    // rather than an `mcpp::` accessor so the member still builds, and still
+    // strips, under an engine that predates the accessor. See
+    // `options::keep_debug_symbols`.
+    const char* engineStrip = std::getenv("MCPP_PACK_STRIP");
+    const bool engineKeeps = engineStrip && std::string_view(engineStrip) == "0";
+    const char* engineDebugDir = std::getenv("MCPP_PACK_DEBUG_SYMBOLS_DIR");
+    const std::string debugDir = engineDebugDir ? engineDebugDir : "";
+
     // THE BUILD'S OWN llvm-strip (0.11.1): the one beside the compiler mcpp
-    // resolved for this row, the NDK's.
+    // resolved for this row, the NDK's. With a debug-symbols directory,
+    // `llvm-objcopy` beside it separates the debug information first, in the
+    // order the engine's own strip uses (`src/pack/strip.cppm`): a copy of the
+    // debug sections while the library still has them, then the stripped
+    // library with a `.gnu_debuglink` naming that copy.
     std::string llvmStrip;
-    if (!opt.keep_debug_symbols) {
+    std::string llvmObjcopy;
+    if (!opt.keep_debug_symbols && !engineKeeps) {
         const std::string toolchain = mcpp::toolchain_dir();
         const fs::path candidate = fs::path(toolchain) / "bin" / "llvm-strip";
         if (!toolchain.empty() && is_file(candidate.string())) {
@@ -2011,6 +2035,17 @@ inline plan plan_for(options opt = {}) {
                 "mcpp.dist.apk: no llvm-strip beside the toolchain ({}); the native libraries are packed "
                 "with their debug information.", toolchain.empty() ? "none reported" : toolchain).c_str());
         }
+        if (!llvmStrip.empty() && !debugDir.empty()) {
+            const fs::path objcopy = fs::path(toolchain) / "bin" / "llvm-objcopy";
+            if (is_file(objcopy.string())) {
+                llvmObjcopy = objcopy.string();
+            } else {
+                mcpp::warning(std::format(
+                    "mcpp.dist.apk: --debug-symbols names {}, and there is no llvm-objcopy beside the "
+                    "toolchain ({}) to separate the libraries' debug information; they are stripped "
+                    "without it.", debugDir, toolchain).c_str());
+            }
+        }
     }
 
     // ── the temporary staging tree: lib/<abi>/, assets/ ─────────────────
@@ -2047,10 +2082,38 @@ inline plan plan_for(options opt = {}) {
         }
         std::error_code ec;
         fs::create_directories(dst.parent_path(), ec);
+        const std::string leaf = fs::path(so).filename().string();
+        if (!llvmObjcopy.empty()) {
+            // One subdirectory per ABI: a package carries the same library name
+            // once for every ABI, and a flat directory would let the last one
+            // overwrite the others' debug information.
+            const fs::path debugFile = fs::path(debugDir) / abi / (leaf + ".debug");
+            fs::create_directories(debugFile.parent_path(), ec);
+            step keep;
+            keep.id          = std::format("{}:debug:{}:{}", bundle ? "aab" : "apk", abi, leaf);
+            keep.role        = "artifact";
+            keep.description = "LLVM-OBJCOPY --only-keep-debug " + abi + "/" + leaf;
+            keep.output      = debugFile.string();
+            keep.argv        = { llvmObjcopy, "--only-keep-debug", so, keep.output };
+            keep.inputs      = { so };
+            p.steps.push_back(keep);
+
+            step strip;
+            strip.id          = std::format("{}:strip:{}:{}", bundle ? "aab" : "apk", abi, leaf);
+            strip.role        = "artifact";
+            strip.description = "LLVM-OBJCOPY --strip-unneeded " + abi + "/" + leaf;
+            strip.output      = dst.string();
+            strip.argv        = { llvmObjcopy, "--strip-unneeded",
+                                  "--add-gnu-debuglink=" + debugFile.string(), so, strip.output };
+            strip.inputs      = { so, keep.output };
+            p.steps.push_back(strip);
+            libInputs.push_back(strip.output);
+            return;
+        }
         step strip;
-        strip.id          = std::format("{}:strip:{}:{}", bundle ? "aab" : "apk", abi, fs::path(so).filename().string());
+        strip.id          = std::format("{}:strip:{}:{}", bundle ? "aab" : "apk", abi, leaf);
         strip.role        = "artifact";
-        strip.description = "LLVM-STRIP " + abi + "/" + fs::path(so).filename().string();
+        strip.description = "LLVM-STRIP " + abi + "/" + leaf;
         strip.output      = dst.string();
         strip.argv        = { llvmStrip, "--strip-unneeded", "-o", strip.output, so };
         strip.inputs      = { so };
diff --git a/tests/apk-consumer/check-apk-features.sh b/tests/apk-consumer/check-apk-features.sh
index 9e1b09b..86f718b 100755
--- a/tests/apk-consumer/check-apk-features.sh
+++ b/tests/apk-consumer/check-apk-features.sh
@@ -308,3 +308,45 @@ grep -q '\.symtab' sections-l.log || fail "keep_debug_symbols packed a stripped
 unset APK_CONSUMER_KEEP_DEBUG_SYMBOLS
 rm -rf k
 echo "ok: keep_debug_symbols packs the library with its symbol table"
+
+# ── (m),(n) 0.12.0: the engine's strip decision reaches the packed libraries ─
+#
+# An engine that strips what the graph built (mcpp 2026.9.16.1) publishes its
+# decision to the build program, so (m) `mcpp pack --no-strip` packs the library
+# with its symbol table, and (n) `--debug-symbols <dir>` separates its debug
+# information into `<dir>/<abi>/<library>.debug` and leaves a `.gnu_debuglink`
+# in the packed copy. An older engine publishes nothing, so these legs are
+# skipped there; (k) is the behaviour that engine keeps.
+engine_version=$("$MCPP" --version | awk '{print $2}')
+if [ "$(printf '%s\n%s\n' 2026.9.16.1 "$engine_version" | sort -V | head -1)" = 2026.9.16.1 ]; then
+    echo "== (m) mcpp pack --no-strip =="
+    rm -rf target k
+    "$MCPP" pack --format apk --target "$TARGET" --no-strip > pack-m.log 2>&1 || fail "pack --no-strip failed" pack-m.log
+    APK=$(find target -name 'apk-consumer.apk' | head -1)
+    [ -n "$APK" ] || fail "no apk-consumer.apk" pack-m.log
+    mkdir -p k && unzip -q -o "$APK" "$LIB" -d k
+    readelf -S "k/$LIB" > sections-m.log
+    grep -q '\.symtab' sections-m.log || fail "--no-strip packed a stripped library" sections-m.log
+    rm -rf k
+    echo "ok: --no-strip packs the library with its symbol table"
+
+    echo "== (n) mcpp pack --debug-symbols <dir> =="
+    rm -rf target k debug-n
+    DEBUG_DIR="$PWD/debug-n"
+    "$MCPP" pack --format apk --target "$TARGET" --debug-symbols "$DEBUG_DIR" > pack-n.log 2>&1 \
+        || fail "pack --debug-symbols failed" pack-n.log
+    APK=$(find target -name 'apk-consumer.apk' | head -1)
+    [ -n "$APK" ] || fail "no apk-consumer.apk" pack-n.log
+    mkdir -p k && unzip -q -o "$APK" "$LIB" -d k
+    readelf -S "k/$LIB" > sections-n.log
+    if grep -qE '\.symtab|\.debug_' sections-n.log; then fail "the packed library keeps its symbol table or debug information" sections-n.log; fi
+    grep -q '\.gnu_debuglink' sections-n.log || fail "the packed library does not name its debug file" sections-n.log
+    DEBUG_FILE="$DEBUG_DIR/x86_64/libapk-consumer.so.debug"
+    [ -f "$DEBUG_FILE" ] || fail "no $DEBUG_FILE" pack-n.log
+    readelf -S "$DEBUG_FILE" > sections-n-debug.log
+    grep -q '\.debug_' sections-n-debug.log || fail "the separated file carries no debug sections" sections-n-debug.log
+    rm -rf k debug-n
+    echo "ok: --debug-symbols separates the library's debug information and links the packed copy to it"
+else
+    echo "skip: (m),(n) need an engine that publishes MCPP_PACK_STRIP (2026.9.16.1+); this is $engine_version"
+fi

From 38ac2bae58e7d804a50195e66bf406e09f2c5860 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Wed, 16 Sep 2026 06:39:20 +0800
Subject: [PATCH 04/10] rules-swift: one package's Swift sources compile into
 its images, with a generated header and the Swift runtime on the link (#647
 E2)

---
 .github/workflows/ci.yml                |  12 +
 mcpp.toml                               |  12 +-
 rules/swift.cppm                        | 337 ++++++++++++++++++++++++
 src/plugins.cppm                        |   2 +-
 tests/all-rules-compile/build.mcpp      |   4 +
 tests/all-rules-compile/mcpp.toml       |   2 +-
 tests/swift-consumer/build.mcpp         |  12 +
 tests/swift-consumer/check-swift.sh     |  69 +++++
 tests/swift-consumer/mcpp.toml          |  33 +++
 tests/swift-consumer/src/main.cpp       |  15 ++
 tests/swift-consumer/src/marker.c       |   2 +
 tests/swift-consumer/swift/answer.swift |  10 +
 tests/swift-consumer/swift/bridge.h     |   4 +
 13 files changed, 511 insertions(+), 3 deletions(-)
 create mode 100644 rules/swift.cppm
 create mode 100644 tests/swift-consumer/build.mcpp
 create mode 100755 tests/swift-consumer/check-swift.sh
 create mode 100644 tests/swift-consumer/mcpp.toml
 create mode 100644 tests/swift-consumer/src/main.cpp
 create mode 100644 tests/swift-consumer/src/marker.c
 create mode 100644 tests/swift-consumer/swift/answer.swift
 create mode 100644 tests/swift-consumer/swift/bridge.h

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 9275318..70afe83 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -2046,6 +2046,18 @@ jobs:
         working-directory: tests/metal-consumer
         run: MCPP="$MCPP" ./check-metal.sh
 
+      # rules-swift (mcpp#647 E2): a C++ program calling a Swift function, which
+      # calls back into C through the bridging header, printing a line from each
+      # side; the generated header declares the exported function; the fixture
+      # links for the iOS simulator when the runner has that SDK. On a runner
+      # without swiftc the script asserts the rule's refusal and annotates the
+      # run instead.
+      - name: rules-swift compiles a package's Swift sources, or records that this runner has no swiftc
+        if: ${{ !cancelled() && runner.os == 'macOS' }}
+        timeout-minutes: 20
+        working-directory: tests/swift-consumer
+        run: MCPP="$MCPP" ./check-swift.sh
+
       # THE iOS ROW, FOR REAL (#622 B1's other half). `tests/ios-app-consumer`
       # is the same fixture the Linux `consumers` job checks at the plan
       # level (see that fixture's own header); here it is built, packed and
diff --git a/mcpp.toml b/mcpp.toml
index cb7a6a7..ccc6e1a 100644
--- a/mcpp.toml
+++ b/mcpp.toml
@@ -1,7 +1,7 @@
 [package]
 name        = "plugins"
 namespace   = "mcpp"
-version     = "0.11.1"
+version     = "0.12.0"
 description = "Official mcpp build plugins: rule packages under mcpp.rules.*, build-time utilities under mcpp.tools.*, each member selected by a feature"
 license     = "Apache-2.0"
 authors     = ["mcpp-community"]
@@ -94,6 +94,16 @@ implies           = ["surface"]
 rule_module       = "mcpp.rules.metal"
 device_extensions = [".metal"]
 
+# `.swift` sources become one object per package through `xcrun swiftc`, with a
+# generated header for the package's C and C++ sources and the Swift runtime's
+# search directories on the link. No payload is declared, for the reason
+# `rules-metal` gives: the compiler ships with Xcode and the Command Line Tools.
+[features.rules-swift]
+sources           = ["rules/swift.cppm"]
+implies           = ["surface"]
+rule_module       = "mcpp.rules.swift"
+device_extensions = [".swift"]
+
 [features.rules-hip]
 sources           = ["rules/hip.cppm"]
 implies           = ["surface"]
diff --git a/rules/swift.cppm b/rules/swift.cppm
new file mode 100644
index 0000000..717e822
--- /dev/null
+++ b/rules/swift.cppm
@@ -0,0 +1,337 @@
+// mcpp.rules.swift -- how one package's Swift sources become one object file
+// the package's images link, stated once.
+//
+// THE DIVISION OF LABOUR IS `mcpp.rules.metal`'S. The ENGINE owns the graph:
+// `.swift` is a device extension this feature declares, so a `.swift` file the
+// project names in `[build] sources` reaches this rule through
+// `mcpp::device_sources()` instead of being refused, and every command below is
+// an action with declared inputs and outputs. The RULE owns the spelling: which
+// SDK, which compiler, which flags, and which runtime the link needs
+// (mcpp-community/mcpp#647 E2).
+//
+// ONE MODULE, ONE OBJECT. Swift compiles a module, not a file: a declaration in
+// one source is visible in every other source of the same module without an
+// import. The package's sources are therefore compiled together, in one
+// whole-module invocation (`-wmo`), into one object named after the package,
+// through an action whose role is `object`, so the object joins the link of every
+// image the package produces.
+//
+// A HEADER FOR THE C AND C++ SIDE. `swiftc -emit-objc-header-path` writes the
+// declarations Swift exports to C and Objective-C (`@_cdecl` functions and
+// `@objc` classes) as a header. It is produced by a second action whose role is
+// `source`, so every compile edge of this package waits for it, and its directory
+// is added with `mcpp::include_dir`, so the package's C++ sources include it as
+// `#include "<module>-Swift.h"`. The header action type-checks and emits no
+// object, which keeps the object action free of an output the link must not
+// receive.
+//
+// C FROM SWIFT. `options::bridging_header` names a C header whose declarations
+// Swift sees without an import (`-import-objc-header`). It is an input of both
+// actions, so editing it recompiles the module.
+//
+// THE RUNTIME. A Swift object refers to the Swift runtime and records the
+// libraries it needs as linker options inside the object; the link finds them
+// through two search directories, the toolchain's `usr/lib/swift/<platform>` and
+// the SDK's `usr/lib/swift`, which reach the link through `mcpp::link_flag`. The
+// runtime itself is part of the operating system from macOS 10.14.4 and iOS 12.2,
+// so the program's run path names `/usr/lib/swift`.
+//
+// THE TOOLCHAIN IS LOCATED, NOT INSTALLED. `swiftc` ships with Xcode and with the
+// Command Line Tools, neither of which is redistributable, so no payload is
+// declared. Before planning anything the rule asks `xcrun --sdk <sdk>
+// --show-sdk-path` and `xcrun --sdk <sdk> --find swiftc`, and refuses naming the
+// command that answered nothing. The commands run through `xcrun --sdk <sdk>`, so
+// the compiler targets the SDK of the row.
+//
+// ROWS. macOS and the iOS rows (the simulator and a device). Every other row is
+// refused by name: Swift on Linux and Windows is a different toolchain and a
+// different runtime, neither of which this rule knows how to link.
+//
+// WHAT THIS RULE DOES NOT DO, stated so that its absence is not mistaken for a
+// defect:
+//   - A Swift `import` of ANOTHER package's Swift module. That needs the other
+//     package's `.swiftmodule` directory on this package's search path, and a
+//     package's compile-interface directories are private to it by design
+//     (`mcpp::include_dir` colours the declaring package's own translation units
+//     only). It waits for an engine channel that publishes such a directory to
+//     dependents.
+//   - A C++ translation unit of another package including this package's
+//     generated header, for the same reason.
+//   - Swift Package Manager dependencies. A SwiftPM package is not a package in
+//     the mcpp graph.
+
+module;
+#include <cstdio>
+
+export module mcpp.rules.swift;
+
+import std;
+import mcpp;
+import mcpp.plugins;
+
+// Nothing here uses `std::println`, for the reason `rules/metal.cppm` gives.
+
+export namespace mcpp::rules::swift {
+
+struct options {
+    // The Swift module name. Empty means the package name, with every character
+    // that is not a letter, a digit or `_` replaced by `_` (a module name is an
+    // identifier; `swift-consumer` is not one).
+    std::string module_name;
+    // A C header Swift sees without an import (`-import-objc-header`). Relative
+    // paths resolve against the package root. Empty passes none.
+    std::string bridging_header;
+    // `-D` for Swift's conditional compilation (`#if NAME`).
+    std::vector<std::string> defines;
+    // Further arguments for both `swiftc` invocations, after the rule's own.
+    std::vector<std::string> flags;
+    // `false` compiles without the header action and adds no include directory,
+    // for a package whose C++ side declares the Swift functions itself.
+    bool emit_header = true;
+    // The SDK `xcrun` compiles against. Empty derives it from the target row:
+    // `macosx`, `iphoneos` or `iphonesimulator`.
+    std::string sdk;
+    // The deployment target in the `-target` triple. Empty takes the row's
+    // minimum platform version from the engine, and a default when the engine
+    // states none (14.0 on macOS, 17.0 on iOS).
+    std::string min_os_version;
+    std::string out_dir = std::string(mcpp::out_dir());
+};
+
+// ─── What the engine said ──────────────────────────────────────────────────
+
+// The SDK a target row compiles against, or empty on a row Swift does not
+// serve.
+inline std::string sdk_for(const options& opt) {
+    if (!opt.sdk.empty()) return opt.sdk;
+    const std::string os = mcpp::target_os();
+    if (os == "macos") return "macosx";
+    if (os == "ios")
+        return std::string(mcpp::target_env()) == "sim" ? "iphonesimulator" : "iphoneos";
+    return {};
+}
+
+// The `-target` triple swiftc takes: Apple's architecture spelling, the
+// platform, the deployment version, and `-simulator` on the simulator row.
+inline std::string swift_target_for(const options& opt, const std::string& sdk) {
+    std::string arch = mcpp::target_arch();
+    if (arch == "aarch64" || arch.empty()) arch = "arm64";
+    std::string version = opt.min_os_version;
+    if (version.empty()) version = mcpp::min_platform_version();
+    if (sdk == "macosx") {
+        if (version.empty()) version = "14.0";
+        return arch + "-apple-macosx" + version;
+    }
+    if (version.empty()) version = "17.0";
+    return arch + "-apple-ios" + version + (sdk == "iphonesimulator" ? "-simulator" : "");
+}
+
+// The platform directory name under a toolchain's `usr/lib/swift/`.
+inline std::string platform_dir_for(const std::string& sdk) {
+    return sdk;   // `macosx`, `iphoneos`, `iphonesimulator`: the same spelling
+}
+
+inline std::string module_name_for(const options& opt) {
+    std::string name = opt.module_name;
+    if (name.empty()) {
+        const char* pkg = mcpp::package_name();
+        name = (pkg && *pkg) ? pkg : "swift_module";
+    }
+    // Indices rather than iterators: a string iterator's operators are
+    // `always_inline` in libstdc++, and GCC 16 does not carry their bodies
+    // through this module's interface to the build program that inlines this
+    // function ("inlining failed ... function body not available", measured).
+    for (std::size_t i = 0; i < name.size(); ++i) {
+        const unsigned char c = static_cast<unsigned char>(name[i]);
+        if (!std::isalnum(c) && name[i] != '_') name[i] = '_';
+    }
+    if (!name.empty() && std::isdigit(static_cast<unsigned char>(name[0])))
+        name.insert(0, 1, '_');
+    return name;
+}
+
+// `mcpp::device_sources()` is the package's whole device set, one path per
+// line, and a rule takes the extensions it claims (see `rules/spirv.cppm`).
+inline std::vector<std::string> device_swift_sources() {
+    std::vector<std::string> out;
+    const std::string all = mcpp::device_sources();
+    std::size_t i = 0;
+    while (i <= all.size()) {
+        auto nl = all.find('\n', i);
+        std::string one = all.substr(i, nl == std::string::npos ? std::string::npos : nl - i);
+        i = nl == std::string::npos ? all.size() + 1 : nl + 1;
+        while (!one.empty() && (one.back() == ' ' || one.back() == '\r')) one.pop_back();
+        if (one.size() > 6 && one.substr(one.size() - 6) == ".swift") out.push_back(one);
+    }
+    return out;
+}
+
+// ─── The toolchain ─────────────────────────────────────────────────────────
+
+// The first line a command prints, or empty. `popen` is POSIX; this module is
+// compiled on every host (`tests/all-rules-compile`), so Windows is spelled.
+inline std::string first_line_of(const std::string& cmd) {
+#if defined(_WIN32)
+    FILE* p = ::_popen(cmd.c_str(), "r");
+#else
+    FILE* p = ::popen(cmd.c_str(), "r");
+#endif
+    if (!p) return {};
+    char buf[1024];
+    std::string line;
+    if (std::fgets(buf, sizeof buf, p)) line = buf;
+#if defined(_WIN32)
+    ::_pclose(p);
+#else
+    ::pclose(p);
+#endif
+    while (!line.empty() && (line.back() == '\n' || line.back() == '\r')) line.pop_back();
+    return line;
+}
+
+inline std::string sdk_path(const std::string& sdk) {
+#if defined(_WIN32)
+    (void)sdk;
+    return {};
+#else
+    const std::string path = first_line_of(
+        "/usr/bin/xcrun --sdk " + sdk + " --show-sdk-path 2>/dev/null");
+    std::error_code ec;
+    return !path.empty() && std::filesystem::is_directory(path, ec) ? path : std::string();
+#endif
+}
+
+inline std::string find_swiftc(const std::string& sdk) {
+#if defined(_WIN32)
+    (void)sdk;
+    return {};
+#else
+    const std::string path = first_line_of(
+        "/usr/bin/xcrun --sdk " + sdk + " --find swiftc 2>/dev/null");
+    std::error_code ec;
+    return !path.empty() && std::filesystem::is_regular_file(path, ec) ? path : std::string();
+#endif
+}
+
+// ─── The rule ──────────────────────────────────────────────────────────────
+
+// Compiles `sources` (absolute, or relative to the package root) as one Swift
+// module. A build that names no `.swift` file has nothing to do, which is not a
+// mistake: a project names the Swift sources on the rows that compile them.
+inline bool compile(std::span<const std::string> sources, options opt = {}) {
+    if (sources.empty()) return true;
+
+    const std::string sdk = sdk_for(opt);
+    if (sdk.empty()) {
+        std::cerr << std::format(
+            "mcpp.rules.swift: {} Swift source(s) reached this rule on a '{}' "
+            "target; this rule compiles Swift for macOS and iOS only. Condition "
+            "the sources on the row, e.g. [target.'cfg(any(os = \"macos\", os = \"ios\"))'.build] "
+            "sources = [\"swift/*.swift\"].",
+            sources.size(), std::string(mcpp::target_os())) << '\n';
+        mcpp::warning("mcpp.rules.swift: Swift sources on a row this rule does not serve");
+        return false;
+    }
+    const std::string sdkRoot = sdk_path(sdk);
+    if (sdkRoot.empty()) {
+        std::cerr << std::format(
+            "mcpp.rules.swift: the {0} SDK was not found: `xcrun --sdk {0} "
+            "--show-sdk-path` answered nothing. The macOS SDK ships with Xcode "
+            "and with the Command Line Tools, the iOS SDKs with Xcode alone.",
+            sdk) << '\n';
+        return false;
+    }
+    const std::string swiftc = find_swiftc(sdk);
+    if (swiftc.empty()) {
+        std::cerr << std::format(
+            "mcpp.rules.swift: no Swift compiler was found for the {0} SDK: "
+            "`xcrun --sdk {0} --find swiftc` answered nothing. It ships with "
+            "Xcode and with the Command Line Tools.", sdk) << '\n';
+        return false;
+    }
+    // `<toolchain>/usr/bin/swiftc`: the toolchain root is three components up.
+    const auto toolchainRoot = std::filesystem::path(swiftc).parent_path().parent_path().parent_path();
+
+    const std::string root = mcpp::manifest_dir();
+    const auto resolve = [&](const std::string& p) {
+        return std::filesystem::path(p).is_absolute() ? p : root + "/" + p;
+    };
+    std::vector<std::string> absSources;
+    for (auto const& s : sources) absSources.push_back(resolve(s));
+    std::string bridging;
+    if (!opt.bridging_header.empty()) {
+        bridging = resolve(opt.bridging_header);
+        std::error_code ec;
+        if (!std::filesystem::is_regular_file(bridging, ec)) {
+            std::cerr << std::format(
+                "mcpp.rules.swift: `options::bridging_header` ({}) was not found", bridging) << '\n';
+            return false;
+        }
+    }
+
+    const std::string module = module_name_for(opt);
+    const std::string target = swift_target_for(opt, sdk);
+    const auto gen = std::filesystem::path(opt.out_dir) / "swift" / module;
+    std::error_code ec;
+    std::filesystem::create_directories(gen, ec);
+
+    // The arguments both invocations share.
+    const auto common = [&](mcpp::action& a) {
+        a.arg("/usr/bin/xcrun").arg("--sdk").arg(sdk.c_str()).arg("swiftc");
+        a.arg("-target").arg(target.c_str());
+        a.arg("-module-name").arg(module.c_str());
+        a.arg("-parse-as-library");
+        for (auto const& d : opt.defines) a.arg(("-D" + d).c_str());
+        if (!bridging.empty()) {
+            a.arg("-import-objc-header").arg(bridging.c_str());
+            a.input(bridging.c_str());
+        }
+        for (auto const& f : opt.flags) a.arg(f.c_str());
+        for (auto const& s : absSources) { a.arg(s.c_str()); a.input(s.c_str()); }
+    };
+
+    if (opt.emit_header) {
+        const std::string header = (gen / (module + "-Swift.h")).string();
+        const std::string id   = "swift-header:" + module;
+        const std::string desc = "SWIFT HEADER " + module;
+        mcpp::action h;
+        h.id          = id.c_str();
+        h.role        = "source";     // a header: ordered before compilation
+        h.description = desc.c_str();
+        common(h);
+        h.arg("-typecheck").arg("-emit-objc-header-path").arg(header.c_str());
+        h.output(header.c_str());
+        h.submit();
+        mcpp::include_dir(gen.string().c_str());
+    }
+
+    const std::string object = (gen / (module + ".o")).string();
+    {
+        const std::string id   = "swift-object:" + module;
+        const std::string desc = "SWIFTC " + module;
+        mcpp::action o;
+        o.id          = id.c_str();
+        o.role        = "object";     // joins the link of every image of the package
+        o.description = desc.c_str();
+        common(o);
+        o.arg("-wmo").arg("-emit-object").arg("-o").arg(object.c_str());
+        o.output(object.c_str());
+        o.submit();
+    }
+
+    const std::string platform = platform_dir_for(sdk);
+    mcpp::link_flag(("-L" + (toolchainRoot / "usr" / "lib" / "swift" / platform).string()).c_str());
+    mcpp::link_flag(("-L" + (std::filesystem::path(sdkRoot) / "usr" / "lib" / "swift").string()).c_str());
+    mcpp::link_flag("-Wl,-rpath,/usr/lib/swift");
+
+    mcpp::fact("mcpp.plugins", std::string(mcpp::plugins::version).c_str());
+    return true;
+}
+
+// The `.swift` files the project named in `[build] sources`, as one module.
+inline bool compile(options opt = {}) {
+    const auto list = device_swift_sources();
+    return compile(std::span<const std::string>(list), std::move(opt));
+}
+
+} // namespace mcpp::rules::swift
diff --git a/src/plugins.cppm b/src/plugins.cppm
index f70e49f..b9e9987 100644
--- a/src/plugins.cppm
+++ b/src/plugins.cppm
@@ -49,7 +49,7 @@ export namespace mcpp::plugins {
 //
 // One package, one version: the number lives in mcpp.toml, and the CI step
 // `the collection states its own version` compares the two.
-inline constexpr std::string_view version = "0.11.1";
+inline constexpr std::string_view version = "0.12.0";
 
 } // namespace mcpp::plugins
 
diff --git a/tests/all-rules-compile/build.mcpp b/tests/all-rules-compile/build.mcpp
index a607850..f98093b 100644
--- a/tests/all-rules-compile/build.mcpp
+++ b/tests/all-rules-compile/build.mcpp
@@ -11,6 +11,7 @@ import mcpp.rules.hip;
 import mcpp.rules.metal;
 import mcpp.rules.slang;
 import mcpp.rules.spirv;
+import mcpp.rules.swift;
 import mcpp.rules.sycl;
 import mcpp.tools.embed;
 import mcpp.tools.island;
@@ -33,6 +34,9 @@ int main() {
            && mcpp::rules::metal::compile()
            && mcpp::rules::slang::compile()
            && mcpp::rules::spirv::compile()
+           // No `.swift` source is named, so the Swift rule plans nothing and
+           // never asks `xcrun`, as the Metal rule above.
+           && mcpp::rules::swift::compile()
            && mcpp::rules::sycl::compile();
     // `tools::embed` has no accelerator gate, so it is asked the one question
     // that writes nothing: where it WOULD put a header. `embed::file` is not
diff --git a/tests/all-rules-compile/mcpp.toml b/tests/all-rules-compile/mcpp.toml
index e657ccd..1fd2359 100644
--- a/tests/all-rules-compile/mcpp.toml
+++ b/tests/all-rules-compile/mcpp.toml
@@ -41,7 +41,7 @@ import_std = true
 [build-dependencies.mcpp]
 plugins = { path = "../..", features = [
   "rules-ascendc", "rules-cuda", "rules-hip", "rules-metal", "rules-slang",
-  "rules-spirv", "rules-sycl",
+  "rules-spirv", "rules-swift", "rules-sycl",
   "tools-embed", "tools-island",
   "dist-appimage", "dist-wix", "dist-apple", "dist-web", "dist-apk",
   "dist-apk-kotlin", "dist-apk-maven",
diff --git a/tests/swift-consumer/build.mcpp b/tests/swift-consumer/build.mcpp
new file mode 100644
index 0000000..efb0916
--- /dev/null
+++ b/tests/swift-consumer/build.mcpp
@@ -0,0 +1,12 @@
+import std;
+import mcpp;
+import mcpp.rules.swift;
+
+int main() {
+    // The `.swift` files `[build] sources` names on this row, as one module named
+    // after the package (`swift_consumer`), with the C declarations of
+    // `swift/bridge.h` visible to Swift.
+    mcpp::rules::swift::options opt;
+    opt.bridging_header = "swift/bridge.h";
+    return mcpp::rules::swift::compile(opt) ? 0 : 1;
+}
diff --git a/tests/swift-consumer/check-swift.sh b/tests/swift-consumer/check-swift.sh
new file mode 100755
index 0000000..69d4647
--- /dev/null
+++ b/tests/swift-consumer/check-swift.sh
@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+# rules-swift on macOS (mcpp#647 E2).
+#
+#   1. A C++ program calls a Swift function exported with `@_cdecl`, which calls
+#      back into a C function through the bridging header; the program prints a
+#      line from each side and exits 0 with the answer 42.
+#   2. The header the rule generates exists; whether it declares the exported
+#      function for a plain C++ caller depends on the Swift version, and is
+#      recorded as a reading.
+#   3. On the iOS simulator row, when this runner has the iphonesimulator SDK,
+#      the same fixture builds; running it needs a booted simulator and is left
+#      to `simctl-run`, so this step checks the link only.
+#
+# THE TOOLCHAIN IS A PROPERTY OF THE RUNNER, as in `tests/metal-consumer`: when
+# `xcrun --sdk macosx --find swiftc` answers nothing, the script asserts the
+# rule's refusal naming that command and exits 0 with a warning annotation.
+#
+# Usage: MCPP=<mcpp> ./check-swift.sh   (run from this directory, on macOS)
+set -eu
+
+MCPP="${MCPP:-mcpp}"
+fail() { echo "FAIL: $1"; shift; for f in "$@"; do echo "--- $f ---"; cat "$f" 2>/dev/null; done; exit 1; }
+reading() { printf 'READING %s: %s\n' "$1" "$2"; }
+
+found=$(xcrun --sdk macosx --find swiftc 2>/dev/null || true)
+reading xcrun-find-swiftc "${found:-nothing}"
+
+rm -rf target
+if [ -z "$found" ]; then
+    rc=0
+    "$MCPP" build > swift-build.log 2>&1 || rc=$?
+    [ "$rc" -ne 0 ] || fail "the build succeeded, and xcrun finds no swiftc" swift-build.log
+    grep -q "xcrun --sdk macosx --find swiftc" swift-build.log \
+        || fail "the build failed without naming the command that found no swiftc" swift-build.log
+    reading criterion "UNMEASURED on this runner: no swiftc"
+    echo "::warning title=rules-swift unmeasured::xcrun --sdk macosx --find swiftc answered nothing on this runner"
+    exit 0
+fi
+
+"$MCPP" build > swift-build.log 2>&1 || fail "mcpp build failed" swift-build.log
+"$MCPP" run > swift-run.log 2>&1 || fail "mcpp run failed" swift-run.log
+reading run "$(tr '\n' '|' < swift-run.log)"
+grep -q '^swift side: base 2, from C 40$' swift-run.log || fail "the Swift side did not print its line" swift-run.log
+grep -q '^swift-consumer: cpp side, answer 42$' swift-run.log || fail "the C++ side did not print the answer 42" swift-run.log
+echo "ok: C++ calls Swift, Swift calls C, and both sides print"
+
+header=$(find target -name 'swift_consumer-Swift.h' | head -1)
+[ -n "$header" ] || fail "no generated swift_consumer-Swift.h" swift-build.log
+[ -s "$header" ] || fail "the generated header is empty" "$header"
+if grep -q 'swift_consumer_answer' "$header"; then
+    reading header "declares swift_consumer_answer"
+else
+    reading header "does not declare swift_consumer_answer with this Swift version"
+fi
+echo "ok: the rule generated the package's Swift header"
+
+if xcrun --sdk iphonesimulator --show-sdk-path > /dev/null 2>&1; then
+    rm -rf target
+    "$MCPP" build --target aarch64-ios-sim > swift-sim.log 2>&1 || fail "the iOS simulator build failed" swift-sim.log
+    bin=$(find target -type f -name swift-consumer -perm -u+x | head -1)
+    [ -n "$bin" ] || fail "no swift-consumer program for the simulator" swift-sim.log
+    reading ios-sim "$(file "$bin")"
+    echo "ok: the fixture links for the iOS simulator"
+else
+    reading ios-sim "UNMEASURED on this runner: no iphonesimulator SDK"
+fi
+
+rm -rf target swift-build.log swift-run.log swift-sim.log
+echo "PASS: rules-swift compiles a package's Swift sources into its program"
diff --git a/tests/swift-consumer/mcpp.toml b/tests/swift-consumer/mcpp.toml
new file mode 100644
index 0000000..e142b17
--- /dev/null
+++ b/tests/swift-consumer/mcpp.toml
@@ -0,0 +1,33 @@
+# Fixture: a C++ program calling Swift, and Swift calling back into C, compiled
+# by rules-swift.
+#
+# `swift/answer.swift` exports `swift_consumer_answer` with `@_cdecl` and calls
+# `swift_consumer_c_marker`, which `src/marker.c` defines and `swift/bridge.h`
+# declares for Swift through `options::bridging_header`. `src/main.cpp` calls the
+# exported function and prints a marker built from both sides. The Swift sources
+# are named on the macOS and iOS rows only, where this fixture is built: the rule
+# refuses them on any other row, by name.
+[package]
+name        = "swift-consumer"
+version     = "0.1.0"
+description = "Fixture: Swift sources compiled by rules-swift and linked into a C++ program"
+license     = "Apache-2.0"
+authors     = ["mcpp-community"]
+
+[language]
+standard   = "c++23"
+modules    = true
+import_std = true
+
+[build-dependencies.mcpp]
+plugins = { path = "../..", features = ["rules-swift"], host-module = true }
+
+[build]
+sources = ["src/*.cpp", "src/*.c"]
+
+[target.'cfg(any(os = "macos", os = "ios"))'.build]
+sources = ["src/*.cpp", "src/*.c", "swift/*.swift"]
+
+[targets.swift-consumer]
+kind = "bin"
+main = "src/main.cpp"
diff --git a/tests/swift-consumer/src/main.cpp b/tests/swift-consumer/src/main.cpp
new file mode 100644
index 0000000..579b93c
--- /dev/null
+++ b/tests/swift-consumer/src/main.cpp
@@ -0,0 +1,15 @@
+#include <cstdio>
+
+// The Swift function this program calls, declared here rather than taken from
+// the header rules-swift generates. That header is written for C and
+// Objective-C callers, and which of its declarations a plain C++ translation
+// unit sees depends on the Swift version; `check-swift.sh` reads the header and
+// records what it declares, while this program depends only on the symbol the
+// `@_cdecl` attribute fixes.
+extern "C" int swift_consumer_answer(int base);
+
+int main() {
+    const int answer = swift_consumer_answer(2);
+    std::printf("swift-consumer: cpp side, answer %d\n", answer);
+    return answer == 42 ? 0 : 1;
+}
diff --git a/tests/swift-consumer/src/marker.c b/tests/swift-consumer/src/marker.c
new file mode 100644
index 0000000..ec9b2fc
--- /dev/null
+++ b/tests/swift-consumer/src/marker.c
@@ -0,0 +1,2 @@
+/* The C function Swift calls back into. */
+int swift_consumer_c_marker(void) { return 40; }
diff --git a/tests/swift-consumer/swift/answer.swift b/tests/swift-consumer/swift/answer.swift
new file mode 100644
index 0000000..2963179
--- /dev/null
+++ b/tests/swift-consumer/swift/answer.swift
@@ -0,0 +1,10 @@
+// Exported to C under a fixed symbol name, and calling back into C through the
+// bridging header.
+@_cdecl("swift_consumer_answer")
+public func swiftConsumerAnswer(_ base: Int32) -> Int32 {
+    let fromC = swift_consumer_c_marker()
+    // String interpolation and `print` reach the Swift standard library, so a
+    // program that prints this line has linked and loaded the Swift runtime.
+    print("swift side: base \(base), from C \(fromC)")
+    return base + fromC
+}
diff --git a/tests/swift-consumer/swift/bridge.h b/tests/swift-consumer/swift/bridge.h
new file mode 100644
index 0000000..75d5085
--- /dev/null
+++ b/tests/swift-consumer/swift/bridge.h
@@ -0,0 +1,4 @@
+// The C declarations Swift sees without an import (rules-swift's
+// `options::bridging_header`).
+#pragma once
+int swift_consumer_c_marker(void);

From e169786d70ed94949f4448571b1e71b4f46fe1a6 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Wed, 16 Sep 2026 06:40:21 +0800
Subject: [PATCH 05/10] 0.12.0: the README states omit_keys, page, the engine's
 strip decision in dist-apk, and rules-swift

---
 README.md | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index b14580f..04e754d 100644
--- a/README.md
+++ b/README.md
@@ -69,14 +69,15 @@ engine's own module family and is not used here.
 | `rules-metal` | `mcpp.rules.metal` | 2026.9.8.1 | the Metal toolchain of the macOS host's Xcode, located rather than installed: Xcode is not redistributable, so no payload is declared. `.metal` sources the project names on a macOS or iOS row become one `xcrun --sdk <sdk> metal` action per shader (`-MMD`, so an edited `#include` recompiles the shaders that include it) and one `xcrun --sdk <sdk> metallib` action per library, placed beside the program with `mcpp::deploy` under `metallib/`, which `dist-apple` maps into the bundle's resources. `compile(shaders)` compiles one source several times with definitions of its own, one library per `shader`; `options::library` links every shader into one library (`default` is the one `newDefaultLibrary` finds). Before planning anything the rule asks `xcrun --sdk <sdk> --show-sdk-path` and `--find metal` / `--find metallib`, and refuses naming the command that answered nothing, because a missing SDK and a missing compiler have different remedies (Xcode 26 installs the Metal toolchain as a separate component). A shader on any other row is refused naming the row. CI compiles the fixture on `macos-15` and checks each library's magic, and that a header edit recompiles only the shaders that include it |
 | `rules-slang` | `mcpp.rules.slang` | 2026.9.7.1 | `[build] accel = "vulkan1.2"`, a constrained glob for `*.slang`. Slang is a different language from GLSL rather than a second driver for it -- its own module system, generics, and targets beyond SPIR-V -- so it is a rule of its own. `.slang` is **not** in the engine's device-source table: this feature declares `device_extensions = [".slang"]` and `rule_module = "mcpp.rules.slang"`, and the engine routes it from there. That is the criterion for the whole arrangement -- a new device language costs no engine release. Since 0.7.0 it has the same `options::storage` axis as `rules-spirv` (header / object / sidecar), `options::extra_args` for the arguments the rule has no field for, and `options::per_file` for what one shader gets that the others do not -- a project with a `-fvk-use-gl-layout` and one shader needing `-emit-spirv-via-glsl` writes both without leaving one `compile()` call |
 | `rules-spirv` | `mcpp.rules.spirv` | 2026.9.6.6 | `[build] accel = "vulkan1.2"`, a constrained glob for the shader stages; compiles each shader through a `role = "source"` action and states which of the two compilers produced it |
+| `rules-swift` | `mcpp.rules.swift` | 2026.9.8.1 | the Swift compiler of the macOS host's Xcode or Command Line Tools, located rather than installed, as `rules-metal` locates its toolchain. From 0.12.0. The `.swift` sources a project names on a macOS or iOS row compile as one module named after the package: one whole-module `xcrun --sdk <sdk> swiftc -wmo -emit-object -target <triple>` action whose role is `object`, so the object joins every image of the package, and one `swiftc -typecheck -emit-objc-header-path` action whose role is `source`, whose directory `mcpp::include_dir` adds, so the package's C and C++ sources include `<module>-Swift.h`. `options::bridging_header` names a C header Swift sees without an import. The link receives the toolchain's `usr/lib/swift/<platform>` and the SDK's `usr/lib/swift` as search directories and `/usr/lib/swift` as a run path through `mcpp::link_flag`. Before planning anything the rule asks `xcrun --sdk <sdk> --show-sdk-path` and `--find swiftc`, and refuses naming the command that answered nothing; a Swift source on any other row is refused naming the row. Not supported: a Swift `import` of another package's module, and another package's C++ including this package's generated header, which both need an engine channel that publishes a package's interface directory to its dependents; and SwiftPM dependencies. CI builds `tests/swift-consumer` on `macos-15` -- a C++ program calling a `@_cdecl` Swift function that calls back into C -- and runs it |
 | `rules-sycl` | `mcpp.rules.sycl` | 2026.9.6.6 | `[build] accel = "sycl"` or `"sycl, cuda12.9+{sm_89}"`, a constrained glob for `*.sycl`, and `compat:sycl-runtime` so the artifact can reach `libsycl.so.9` at run time. Its own engine need is `.sycl` in the device-source table, 2026.9.6.1 |
 | `tools-embed` | `mcpp.tools.embed` | 2026.9.5.4 | nothing beyond mcpp: it reads a file and writes a header while the build program runs. The floor is the release whose fast path compares a declared file input, without which an edit to the data does not reach the binary |
 | `tools-island` | `mcpp.tools.island` | 2026.9.7.1 | nothing beyond mcpp: it reads marked entry points out of an island's own source and writes the `extern "C"` boundary header its compiler reads and the module the C++ side imports. Not a device rule -- it claims no extension, and a project calls it from its own `build.mcpp` |
 | `dist-appimage` | `mcpp.dist.appimage` | 2026.9.11.1 | `xim:appimagetool`, which this feature declares on the `cfg(linux)` axis. Linux only. Turns the tree `mcpp pack` staged into one AppImage: the staged bundle is already an AppDir bar three files, so the member writes an `AppRun`, a `.desktop` entry and an icon into it and invokes one tool -- it never copies or re-lays-out a tree that can be hundreds of megabytes. From 0.11.1 `options::icon` may be an SVG as well as a PNG: the image carries `<name>.svg`, because the desktop entry names the icon without an extension and a reader finds it by the file's, and any other format is refused by name |
 | `dist-wix` | `mcpp.dist.wix` | 2026.9.11.1 | `xim:wix` 5.0.2-1, which this feature declares on the Windows target axis; the .NET 6 runtime the tool needs is a Windows component the payload does not carry, and `wix --version` names it when it is missing. Windows only. `--format msi` renders a `.wxs` and passes the program in as a preprocessor variable, because a bind path that resolves to nothing is silent. From 0.10.0 `--format setup` is a Burn bundle chaining that MSI, with WiX's stock bootstrapper application (`bal:WixStandardBootstrapperApplication`, theme `hyperlinkLicense`, `options::license_url` its link) loaded through the `WixToolset.BootstrapperApplications.wixext` extension the 5.0.2-1 payload carries (`options::extension` names another). The bundle is written as `<product_name>-<arch>.exe` beside the MSI, with an UpgradeCode of its own, and `options::bundle_output` naming `setup.exe` is refused before `wix` runs, because `wix` refuses that name (WIX0388). A project with its own bootstrapper application supplies `options::bundle_wxs`, which receives the MSI as `$(Msi)`. From 0.10.1 the MSI installs the staged tree, not the program alone: every file `mcpp pack` stages beside the program (a deployed file, a resolved DLL) is named file by file in a `StagedFiles` component group written beside the definition -- enumerated while the tree exists, never harvested from a directory -- placed at its staged path under `INSTALLFOLDER`, and declared an input of the action; the generated definition references the group, and a project's own `options::wxs` installs it with `<ComponentGroupRef Id="StagedFiles" />`. `options::inputs` and `options::bundle_inputs` declare the files a project's own definitions name beyond that (an icon, a bootstrapper application and its payloads). CI builds the bundle on `windows-2022` and compares the MSI `wix burn extract` takes out of it with the one the first action wrote, and installs the MSI administratively and compares both the program and a deployed file |
-| `dist-apple` | `mcpp.dist.apple` | 2026.9.14.2 (0.10.0); 2026.9.11.2 (macOS) and 2026.9.12.3 (iOS) before it | the base macOS install (`ditto`, `codesign`, `hdiutil`), and `xim:macapp-run` for `mcpp run` on macOS, which this feature declares with `when = "run"`. macOS: `Contents/`-shaped, as always. iOS (`aarch64-ios-sim`, `aarch64-ios`): a flat bundle at the same call site -- no separate feature, no separate module -- with `MinimumOSVersion` from `mcpp::min_platform_version()` (#622 A11), `CFBundleSupportedPlatforms` read from `env == "sim"`, `UIDeviceFamily`, `LSRequiresIPhoneOS`, and a directory of flat PNGs listed under `CFBundleIcons` in place of macOS's single `.icns` file. Signing is skipped on the simulator row (`options::identity` is ignored, with a `mcpp::warning` naming why), and the device row signs only with an identity. The iOS row is measured end to end on `macos-15`: a real `mcpp build`, `mcpp pack --format app` and `mcpp run` against `aarch64-ios-sim`, through `xim:apple-simulator-tools`' `simctl-run`. **The macOS floor is one release higher than its siblings** and the reason is not this member: under 2026.9.11.1 `mcpp pack` staged before dispatching and let a staging failure fail the command, so on a Mach-O program -- which the built-in closure walk refuses, because it uses `LD_TRACE_LOADED_OBJECTS` and dyld answers that by running the program -- every dispatched format was unreachable, including one that reads no staged tree. 2026.9.11.2 makes staging a service to the provider. From 0.9.2 the staged tree's deployed files (`bin/<to>/...`, which the engine stages for a Mach-O program before the closure walk since the release for mcpp#630) land at the bundle's resource destination -- `Contents/Resources/<to>/...` on macOS, the bundle root on iOS -- and the launcher alone goes to the executable directory, so `CFBundleExecutable` names a file that is where it says. The iOS fixture declares `llvm.libcxx` and `llvm.compiler-rt-builtins` under `cfg(os = "ios")`, which is what an application that imports `std` on those rows declares. From 0.10.0, with mcpp 2026.9.14.2: the dylibs the engine stages beside a Mach-O program, which the stage manifest's `needs` lines name, go to `Contents/Frameworks/` (`Frameworks/` on iOS) and not to the resources; the program is linked with the rpath that finds them there (`@executable_path/../Frameworks`, `@executable_path/Frameworks` on iOS) through `mcpp::link_flag`, so no file is edited after the link; a macOS bundle without `options::identity` is signed ad hoc, frameworks first and the bundle second, which `codesign --verify --deep --strict` requires of a bundle that carries a framework; an incomplete closure is a `mcpp::warning` naming the unresolved libraries; every refusal is a `mcpp::warning` as well, because the engine discards a build program's output when it exits 0. On macOS the member supplies the runner named `app` (`macapp-run`), so `mcpp run --format app` runs the bundle's executable in the foreground and returns its status with no runner in the manifest; a manifest runner of that name wins. `--format dmg` stages the bundle beside an `Applications` link and writes a UDZO image with `hdiutil create` (`options::volume_name`, `options::dmg`); it is refused on iOS. An engine below 2026.9.14.2 stages no `needs` lines, so the bundle carries no framework, anchors the rpath to the package directory, and hands the bundle directory to the kernel under `mcpp run --format app` unless `--runner app` is typed. CI measures the bundle on `macos-15`: the load command, the signature, the program with and without its framework (exit 7, then "Library not loaded"), `mcpp run --format app` with and without `--runner app`, and `hdiutil verify` and an attached image. From 0.11.0: a project's own Info.plist entries (`options::info_plist`), an iOS device bundle's provisioning profile (`options::provisioning_profile`), and `devicectl-run` (`xim:apple-device-tools`) as the device row's runner named `app` -- see [`dist-apple`: a project's Info.plist, and an iOS device](#dist-apple-a-projects-infoplist-and-an-ios-device) |
-| `dist-web` | `mcpp.dist.web` | 2026.9.13.1, the release that carries `${mcpp.self}` and `mcpp stage`'s argument shape as an engine contract (`stage --verify content --output <dst> <src>`) -- what lets this member's copy run on every host mcpp does, Windows included, in place of the `cp` this member used through 0.8.0 | nothing beyond mcpp: `wasm32-emscripten` only. Copies `${mcpp.stage_dir}/bin/` -- the `.js` launcher, the implicit `.wasm`, the `.data` when present, and every `mcpp::deploy`'d file, all of which #622 A5 and A4 already stage there -- to `<out_dir>/web/`, dropping the `bin/` prefix a browser has no use for, and writes an `index.html` rendered from a project template or a built-in default that loads the script with a plain `<script src>`. Each staged file and the rendered page are copied with `${mcpp.self} stage --verify content --output <dst> <src>`, the same copier every `stage_file` edge in `build.ninja` already runs -- no host-specific copy tool, no plan-time `create_directories` (`stage` creates the destination's parent), and a second `mcpp pack --format web` with nothing changed copies nothing |
-| `dist-apk` | `mcpp.dist.apk` | 2026.9.14.2 from 0.10.0, which stages the closure this member reads; before it 2026.9.13.1, raised alongside `dist-web` in the same 0.9.0 release: this member's own manifest-template and Java-array changes ask nothing new of the engine, but this collection publishes one package at one version, and this is the release CI verifies it under from here on | `xim:android-build-tools`, `xim:android-platform` (versioned by API level, read back for `targetSdkVersion`), `xim:jdk-temurin` (`javac`/`jar`/`jarsigner`; `android-build-tools`' own runtime dependency provisions a JDK for its OWN wrappers only), `xim:android-debug-keystore`, `xim:bundletool` (0.10.0, for `--format aab`), all on the `cfg(env = "android")` axis. Generates `AndroidManifest.xml` and signs with the published Android debug key by default. Level 0 needs no Java (`hasCode="false"`, `android.app.NativeActivity`); `options::java_sources` adds `javac` + `d8` and a real `<activity>`. `options::manifest_template` renders a project manifest with six tokens substituted verbatim; `{{application_id}}` and `{{activity}}` are required always and `{{lib_name}}` at level 0, each refused by name at plan time when missing (naming `assets/mcpp-run.json`, which `adb-run` reads them from too) or when the template names an unknown token; empty renders 0.8.0's manifest byte-identically. From 0.9.3 the manifest template gains `{{version_name}}` / `{{version_code}}` (the package version, and `major * 1000000 + minor * 1000 + patch`). `options::resources` is a project's own `res/`, linked as the application's base resources from 0.9.1 (0.9.0 linked it as an aapt2 overlay, which refuses every resource the base does not already define -- a launcher icon could not be supplied). `options::java_sources` is an array: one `javac` over every root's `.java` files and one `d8` over the result, so a project's own sources and a path dependency's join without being merged into one directory first, and `rerun_if_changed_glob` is declared only for a root under `mcpp::manifest_dir()` -- a dependency root's files are already inputs of the `javac` action and its version is already in the build's fingerprint. Android only -- an `app` target is a shared object on this row (#622 A3). From 0.10.0, with mcpp 2026.9.14.2, the member reads the native closure the engine stages -- the application object, the graph's shared libraries and `libc++_shared.so` under `lib/` for one `--target`, `lib/<abi>/` for several -- and packs every ABI the tree carries into one APK; its own `NEEDED` walk and the stamp that lost a dependency's library on a second pack are gone. A stage manifest without `needs` lines comes from an engine below 2026.9.14.2 and is refused naming that floor, as is an incomplete closure, naming the unresolved libraries; every refusal is also a `mcpp::warning`, because the engine discards a build program's output when it exits 0. `--format aab` shares every step but the last three: `aapt2 link --proto-format` (with `--version-code` / `--version-name`, which bundletool requires), a base module in the layout bundletool reads, `bundletool build-bundle` from `xim:bundletool` (declared on the same axis), and `jarsigner` with the same keystore. CI packages both level 0 and level 1 and checks the archive (`mcpp::deploy`'d files under `assets/`), and on `tests/apk-consumer-shared` two packs in a row, a two-ABI APK (`aapt2` reports both, `apksigner` verifies it), an App Bundle (`bundletool validate`, `jarsigner -verify`, a universal APK from `bundletool build-apks`), a refusal's reason in `mcpp pack`'s output, and the floor refusal; the runner has no emulator or device, so the two rows that actually run were measured locally on 2026-09-12, through `adb-run`, against a KVM-accelerated x86_64 emulator and a physical arm64-v8a phone, both printing `1-2-3` and exiting 0. From 0.11.0: Kotlin sources (`dist-apk-kotlin`, which declares `xim:kotlin`), R classes, Android libraries from source, local AARs and JARs, a Maven graph through a lock file (`dist-apk-maven`, which declares `xim:coursier`), a manifest merge, and an unsigned package -- see [`dist-apk`: Kotlin, libraries and a Maven graph](#dist-apk-kotlin-libraries-and-a-maven-graph). From 0.11.1 the native libraries are packed as the Android Gradle plugin packs them: each is stripped with the build's own `llvm-strip --strip-unneeded` (the NDK's, beside the compiler `mcpp::toolchain_dir()` reports; `options::keep_debug_symbols` packs them as staged), and a manifest stating `android:extractNativeLibs="false"` gets them stored uncompressed on a 16 KB page, which loading them from the APK in place requires; CI checks both, and the symbol table `keep_debug_symbols` keeps |
+| `dist-apple` | `mcpp.dist.apple` | 2026.9.14.2 (0.10.0); 2026.9.11.2 (macOS) and 2026.9.12.3 (iOS) before it | the base macOS install (`ditto`, `codesign`, `hdiutil`), and `xim:macapp-run` for `mcpp run` on macOS, which this feature declares with `when = "run"`. macOS: `Contents/`-shaped, as always. iOS (`aarch64-ios-sim`, `aarch64-ios`): a flat bundle at the same call site -- no separate feature, no separate module -- with `MinimumOSVersion` from `mcpp::min_platform_version()` (#622 A11), `CFBundleSupportedPlatforms` read from `env == "sim"`, `UIDeviceFamily`, `LSRequiresIPhoneOS`, and a directory of flat PNGs listed under `CFBundleIcons` in place of macOS's single `.icns` file. Signing is skipped on the simulator row (`options::identity` is ignored, with a `mcpp::warning` naming why), and the device row signs only with an identity. The iOS row is measured end to end on `macos-15`: a real `mcpp build`, `mcpp pack --format app` and `mcpp run` against `aarch64-ios-sim`, through `xim:apple-simulator-tools`' `simctl-run`. **The macOS floor is one release higher than its siblings** and the reason is not this member: under 2026.9.11.1 `mcpp pack` staged before dispatching and let a staging failure fail the command, so on a Mach-O program -- which the built-in closure walk refuses, because it uses `LD_TRACE_LOADED_OBJECTS` and dyld answers that by running the program -- every dispatched format was unreachable, including one that reads no staged tree. 2026.9.11.2 makes staging a service to the provider. From 0.9.2 the staged tree's deployed files (`bin/<to>/...`, which the engine stages for a Mach-O program before the closure walk since the release for mcpp#630) land at the bundle's resource destination -- `Contents/Resources/<to>/...` on macOS, the bundle root on iOS -- and the launcher alone goes to the executable directory, so `CFBundleExecutable` names a file that is where it says. The iOS fixture declares `llvm.libcxx` and `llvm.compiler-rt-builtins` under `cfg(os = "ios")`, which is what an application that imports `std` on those rows declares. From 0.10.0, with mcpp 2026.9.14.2: the dylibs the engine stages beside a Mach-O program, which the stage manifest's `needs` lines name, go to `Contents/Frameworks/` (`Frameworks/` on iOS) and not to the resources; the program is linked with the rpath that finds them there (`@executable_path/../Frameworks`, `@executable_path/Frameworks` on iOS) through `mcpp::link_flag`, so no file is edited after the link; a macOS bundle without `options::identity` is signed ad hoc, frameworks first and the bundle second, which `codesign --verify --deep --strict` requires of a bundle that carries a framework; an incomplete closure is a `mcpp::warning` naming the unresolved libraries; every refusal is a `mcpp::warning` as well, because the engine discards a build program's output when it exits 0. On macOS the member supplies the runner named `app` (`macapp-run`), so `mcpp run --format app` runs the bundle's executable in the foreground and returns its status with no runner in the manifest; a manifest runner of that name wins. `--format dmg` stages the bundle beside an `Applications` link and writes a UDZO image with `hdiutil create` (`options::volume_name`, `options::dmg`); it is refused on iOS. An engine below 2026.9.14.2 stages no `needs` lines, so the bundle carries no framework, anchors the rpath to the package directory, and hands the bundle directory to the kernel under `mcpp run --format app` unless `--runner app` is typed. CI measures the bundle on `macos-15`: the load command, the signature, the program with and without its framework (exit 7, then "Library not loaded"), `mcpp run --format app` with and without `--runner app`, and `hdiutil verify` and an attached image. From 0.11.0: a project's own Info.plist entries (`options::info_plist`), an iOS device bundle's provisioning profile (`options::provisioning_profile`), and `devicectl-run` (`xim:apple-device-tools`) as the device row's runner named `app` -- see [`dist-apple`: a project's Info.plist, and an iOS device](#dist-apple-a-projects-infoplist-and-an-ios-device). From 0.12.0 `options::omit_keys` leaves out a key the member only defaults -- see [`dist-apple`: a project's Info.plist, and an iOS device](#dist-apple-a-projects-infoplist-and-an-ios-device) |
+| `dist-web` | `mcpp.dist.web` | 2026.9.13.1, the release that carries `${mcpp.self}` and `mcpp stage`'s argument shape as an engine contract (`stage --verify content --output <dst> <src>`) -- what lets this member's copy run on every host mcpp does, Windows included, in place of the `cp` this member used through 0.8.0 | nothing beyond mcpp: `wasm32-emscripten` only. Copies `${mcpp.stage_dir}/bin/` -- the `.js` launcher, the implicit `.wasm`, the `.data` when present, and every `mcpp::deploy`'d file, all of which #622 A5 and A4 already stage there -- to `<out_dir>/web/`, dropping the `bin/` prefix a browser has no use for, and writes an `index.html` rendered from a project template or a built-in default that loads the script with a plain `<script src>`. Each staged file and the rendered page are copied with `${mcpp.self} stage --verify content --output <dst> <src>`, the same copier every `stage_file` edge in `build.ninja` already runs -- no host-specific copy tool, no plan-time `create_directories` (`stage` creates the destination's parent), and a second `mcpp pack --format web` with nothing changed copies nothing. From 0.12.0 `options::page` names the page (`index.html` by default), for a project whose other build names it after the target; a name that is not a bare `*.html` file name is refused at plan time |
+| `dist-apk` | `mcpp.dist.apk` | 2026.9.14.2 from 0.10.0, which stages the closure this member reads; before it 2026.9.13.1, raised alongside `dist-web` in the same 0.9.0 release: this member's own manifest-template and Java-array changes ask nothing new of the engine, but this collection publishes one package at one version, and this is the release CI verifies it under from here on | `xim:android-build-tools`, `xim:android-platform` (versioned by API level, read back for `targetSdkVersion`), `xim:jdk-temurin` (`javac`/`jar`/`jarsigner`; `android-build-tools`' own runtime dependency provisions a JDK for its OWN wrappers only), `xim:android-debug-keystore`, `xim:bundletool` (0.10.0, for `--format aab`), all on the `cfg(env = "android")` axis. Generates `AndroidManifest.xml` and signs with the published Android debug key by default. Level 0 needs no Java (`hasCode="false"`, `android.app.NativeActivity`); `options::java_sources` adds `javac` + `d8` and a real `<activity>`. `options::manifest_template` renders a project manifest with six tokens substituted verbatim; `{{application_id}}` and `{{activity}}` are required always and `{{lib_name}}` at level 0, each refused by name at plan time when missing (naming `assets/mcpp-run.json`, which `adb-run` reads them from too) or when the template names an unknown token; empty renders 0.8.0's manifest byte-identically. From 0.9.3 the manifest template gains `{{version_name}}` / `{{version_code}}` (the package version, and `major * 1000000 + minor * 1000 + patch`). `options::resources` is a project's own `res/`, linked as the application's base resources from 0.9.1 (0.9.0 linked it as an aapt2 overlay, which refuses every resource the base does not already define -- a launcher icon could not be supplied). `options::java_sources` is an array: one `javac` over every root's `.java` files and one `d8` over the result, so a project's own sources and a path dependency's join without being merged into one directory first, and `rerun_if_changed_glob` is declared only for a root under `mcpp::manifest_dir()` -- a dependency root's files are already inputs of the `javac` action and its version is already in the build's fingerprint. Android only -- an `app` target is a shared object on this row (#622 A3). From 0.10.0, with mcpp 2026.9.14.2, the member reads the native closure the engine stages -- the application object, the graph's shared libraries and `libc++_shared.so` under `lib/` for one `--target`, `lib/<abi>/` for several -- and packs every ABI the tree carries into one APK; its own `NEEDED` walk and the stamp that lost a dependency's library on a second pack are gone. A stage manifest without `needs` lines comes from an engine below 2026.9.14.2 and is refused naming that floor, as is an incomplete closure, naming the unresolved libraries; every refusal is also a `mcpp::warning`, because the engine discards a build program's output when it exits 0. `--format aab` shares every step but the last three: `aapt2 link --proto-format` (with `--version-code` / `--version-name`, which bundletool requires), a base module in the layout bundletool reads, `bundletool build-bundle` from `xim:bundletool` (declared on the same axis), and `jarsigner` with the same keystore. CI packages both level 0 and level 1 and checks the archive (`mcpp::deploy`'d files under `assets/`), and on `tests/apk-consumer-shared` two packs in a row, a two-ABI APK (`aapt2` reports both, `apksigner` verifies it), an App Bundle (`bundletool validate`, `jarsigner -verify`, a universal APK from `bundletool build-apks`), a refusal's reason in `mcpp pack`'s output, and the floor refusal; the runner has no emulator or device, so the two rows that actually run were measured locally on 2026-09-12, through `adb-run`, against a KVM-accelerated x86_64 emulator and a physical arm64-v8a phone, both printing `1-2-3` and exiting 0. From 0.11.0: Kotlin sources (`dist-apk-kotlin`, which declares `xim:kotlin`), R classes, Android libraries from source, local AARs and JARs, a Maven graph through a lock file (`dist-apk-maven`, which declares `xim:coursier`), a manifest merge, and an unsigned package -- see [`dist-apk`: Kotlin, libraries and a Maven graph](#dist-apk-kotlin-libraries-and-a-maven-graph). From 0.11.1 the native libraries are packed as the Android Gradle plugin packs them: each is stripped with the build's own `llvm-strip --strip-unneeded` (the NDK's, beside the compiler `mcpp::toolchain_dir()` reports; `options::keep_debug_symbols` packs them as staged), and a manifest stating `android:extractNativeLibs="false"` gets them stored uncompressed on a 16 KB page, which loading them from the APK in place requires; CI checks both, and the symbol table `keep_debug_symbols` keeps. From 0.12.0 the engine's strip decision governs these libraries as well: under mcpp 2026.9.16.1, which publishes it to build programs as `MCPP_PACK_STRIP` and `MCPP_PACK_DEBUG_SYMBOLS_DIR`, `mcpp pack --no-strip` packs them as staged and `--debug-symbols <dir>` separates each library's debug information into `<dir>/<abi>/<library>.debug` with `llvm-objcopy` before stripping it and linking the packed copy to that file (`.gnu_debuglink`); a library is stripped unless either `keep_debug_symbols` or the engine says to keep it, and under an older engine, which publishes neither variable, the member strips as before |
 
 ### Each rule brings its own environment
 
@@ -139,6 +140,7 @@ Each rule therefore selects the extensions it claims and leaves the rest:
 | `rules-hip` | `.hip` |
 | `rules-metal` | `.metal` |
 | `rules-slang` | `.slang` |
+| `rules-swift` | `.swift` |
 | `rules-sycl` | `.sycl` |
 | `rules-spirv` | `.comp .vert .frag .geom .tesc .tese .mesh .task .rgen .rint .rahit .rchit .rmiss .rcall`, and `.glsl` / `.hlsl` so that a stage-less name is refused by name rather than by absence |
 
@@ -751,6 +753,7 @@ Windows NDK carries no libc++ module surface (`xim-pkgindex`,
 | option | what it does |
 |---|---|
 | `info_plist` | A plist whose top-level `<dict>` entries join the bundle's Info.plist: usage descriptions, URL types, background modes. A key the member derives is refused by name: `CFBundleExecutable`, `CFBundleIdentifier`, `CFBundleName`, `CFBundleShortVersionString`, `CFBundleVersion`, `CFBundlePackageType`, `LSMinimumSystemVersion`, `MinimumOSVersion`, `CFBundleSupportedPlatforms`, `CFBundleIconFile`, `CFBundleIcons`. A key it only defaults takes the project's value: `UIDeviceFamily`, `LSRequiresIPhoneOS`, `NSHighResolutionCapable`. Without `info_plist` the plist is byte-identical to 0.10.1's |
+| `omit_keys` | From 0.12.0. Defaulted keys to leave out of the Info.plist, for a project whose other build states neither: `UIDeviceFamily`, `LSRequiresIPhoneOS`, `NSHighResolutionCapable`. A property list has no null, so `info_plist` can replace a default's value but cannot remove its key. A key the member derives, a key it never writes, a key named twice, and a key `info_plist` also sets are each refused by name. A key that does not apply to the row (`UIDeviceFamily` on macOS) changes nothing |
 | `provisioning_profile` | The device row (`aarch64-ios`) only, and only with `identity`. The profile is embedded as `embedded.mobileprovision`. Its `Entitlements` dictionary signs the bundle unless `entitlements` names a file, with a wildcard `application-identifier` stated as the bundle's own. That identifier must cover the bundle identifier: exactly, `<team>.*`, or `<team>.<prefix>.*`. The plist is read from the profile's bytes, so a plan made on any host checks it; verifying the profile's CMS signature is left to `codesign` and the device |
 
 On the device row the member supplies the runner named `app`: `devicectl-run`,
@@ -766,7 +769,8 @@ device bundle, its signature and whether `devicectl` returns the program's exit
 status have not been measured on one; `devicectl-run` prints that when it runs.
 CI measures the rest:
 
-- On Linux, the plan: the entries, a refused key, the embedded profile, the
+- On Linux, the plan: the entries, a refused key, an omitted default on iOS
+  and on macOS and the three refusals of `omit_keys`, the embedded profile, the
   entitlements, a wildcard profile, and the refusals of a profile for another
   identifier, on the simulator row, or without an identity.
 - On `macos-15`: the entries in a real macOS bundle that `plutil` accepts and

From 35c49803453264647e1b39774ce0409e504da70d Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Wed, 16 Sep 2026 06:53:50 +0800
Subject: [PATCH 06/10] dist-apk and dist-apple collect what the resolved
 graph's packages contribute; one JSON reader for both (#647 E1)

---
 .github/workflows/ci.yml                      |  13 +
 README.md                                     |  61 ++++-
 dist/apk.cppm                                 | 237 +++++++++---------
 dist/apple.cppm                               | 128 ++++++++--
 src/plugins.cppm                              | 226 +++++++++++++++++
 .../app-res/values/strings.xml                |   6 +
 tests/apk-consumer-graph/build.mcpp           |  26 ++
 tests/apk-consumer-graph/check-apk-graph.sh   |  96 +++++++
 tests/apk-consumer-graph/lib/mcpp.toml        |  22 ++
 .../lib/res/values/strings.xml                |   4 +
 tests/apk-consumer-graph/lib/src/lib.cpp      |   1 +
 tests/apk-consumer-graph/mcpp.toml            |  34 +++
 tests/apk-consumer-graph/src/main.cpp         |  16 ++
 tests/ios-app-consumer/build.mcpp             |   5 +-
 tests/ios-app-consumer/check-ios-plan.sh      |  91 +++++++
 .../ios-app-consumer/info-plist/graph-a.plist |  16 ++
 .../ios-app-consumer/info-plist/graph-b.plist |  11 +
 .../info-plist/graph-derived.plist            |   9 +
 18 files changed, 864 insertions(+), 138 deletions(-)
 create mode 100644 tests/apk-consumer-graph/app-res/values/strings.xml
 create mode 100644 tests/apk-consumer-graph/build.mcpp
 create mode 100755 tests/apk-consumer-graph/check-apk-graph.sh
 create mode 100644 tests/apk-consumer-graph/lib/mcpp.toml
 create mode 100644 tests/apk-consumer-graph/lib/res/values/strings.xml
 create mode 100644 tests/apk-consumer-graph/lib/src/lib.cpp
 create mode 100644 tests/apk-consumer-graph/mcpp.toml
 create mode 100644 tests/apk-consumer-graph/src/main.cpp
 create mode 100644 tests/ios-app-consumer/info-plist/graph-a.plist
 create mode 100644 tests/ios-app-consumer/info-plist/graph-b.plist
 create mode 100644 tests/ios-app-consumer/info-plist/graph-derived.plist

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 70afe83..de3c4e6 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1352,6 +1352,19 @@ jobs:
         working-directory: tests/apk-consumer-libraries
         run: MCPP="$MCPP" ./check-apk-libraries.sh
 
+      # LIBRARIES THE GRAPH CONTRIBUTES (0.12.0). `tests/apk-consumer-graph/lib`
+      # states `[package.metadata.dist-apk]`, and the application names it only
+      # as a dependency. Under an engine that gives the root build program the
+      # resolved graph (mcpp 2026.9.16.1+) the library's resource is in the APK,
+      # `graph_libraries = false` reads none, the application's own library wins
+      # a resource both define, and a malformed contribution is refused naming
+      # the package and the key; under an older engine the pack succeeds without
+      # the contribution. The script chooses its legs from `mcpp --version`.
+      - name: dist-apk collects the libraries the resolved graph contributes
+        timeout-minutes: 30
+        working-directory: tests/apk-consumer-graph
+        run: MCPP="$MCPP" ./check-apk-graph.sh
+
       # Compiles the device unit on a machine with no GPU: the clang route
       # produces sm_89 code from the payload toolkit. Running it needs a
       # device, so the run is of the CPU variant, which the same seam serves.
diff --git a/README.md b/README.md
index 04e754d..6d2b553 100644
--- a/README.md
+++ b/README.md
@@ -75,9 +75,9 @@ engine's own module family and is not used here.
 | `tools-island` | `mcpp.tools.island` | 2026.9.7.1 | nothing beyond mcpp: it reads marked entry points out of an island's own source and writes the `extern "C"` boundary header its compiler reads and the module the C++ side imports. Not a device rule -- it claims no extension, and a project calls it from its own `build.mcpp` |
 | `dist-appimage` | `mcpp.dist.appimage` | 2026.9.11.1 | `xim:appimagetool`, which this feature declares on the `cfg(linux)` axis. Linux only. Turns the tree `mcpp pack` staged into one AppImage: the staged bundle is already an AppDir bar three files, so the member writes an `AppRun`, a `.desktop` entry and an icon into it and invokes one tool -- it never copies or re-lays-out a tree that can be hundreds of megabytes. From 0.11.1 `options::icon` may be an SVG as well as a PNG: the image carries `<name>.svg`, because the desktop entry names the icon without an extension and a reader finds it by the file's, and any other format is refused by name |
 | `dist-wix` | `mcpp.dist.wix` | 2026.9.11.1 | `xim:wix` 5.0.2-1, which this feature declares on the Windows target axis; the .NET 6 runtime the tool needs is a Windows component the payload does not carry, and `wix --version` names it when it is missing. Windows only. `--format msi` renders a `.wxs` and passes the program in as a preprocessor variable, because a bind path that resolves to nothing is silent. From 0.10.0 `--format setup` is a Burn bundle chaining that MSI, with WiX's stock bootstrapper application (`bal:WixStandardBootstrapperApplication`, theme `hyperlinkLicense`, `options::license_url` its link) loaded through the `WixToolset.BootstrapperApplications.wixext` extension the 5.0.2-1 payload carries (`options::extension` names another). The bundle is written as `<product_name>-<arch>.exe` beside the MSI, with an UpgradeCode of its own, and `options::bundle_output` naming `setup.exe` is refused before `wix` runs, because `wix` refuses that name (WIX0388). A project with its own bootstrapper application supplies `options::bundle_wxs`, which receives the MSI as `$(Msi)`. From 0.10.1 the MSI installs the staged tree, not the program alone: every file `mcpp pack` stages beside the program (a deployed file, a resolved DLL) is named file by file in a `StagedFiles` component group written beside the definition -- enumerated while the tree exists, never harvested from a directory -- placed at its staged path under `INSTALLFOLDER`, and declared an input of the action; the generated definition references the group, and a project's own `options::wxs` installs it with `<ComponentGroupRef Id="StagedFiles" />`. `options::inputs` and `options::bundle_inputs` declare the files a project's own definitions name beyond that (an icon, a bootstrapper application and its payloads). CI builds the bundle on `windows-2022` and compares the MSI `wix burn extract` takes out of it with the one the first action wrote, and installs the MSI administratively and compares both the program and a deployed file |
-| `dist-apple` | `mcpp.dist.apple` | 2026.9.14.2 (0.10.0); 2026.9.11.2 (macOS) and 2026.9.12.3 (iOS) before it | the base macOS install (`ditto`, `codesign`, `hdiutil`), and `xim:macapp-run` for `mcpp run` on macOS, which this feature declares with `when = "run"`. macOS: `Contents/`-shaped, as always. iOS (`aarch64-ios-sim`, `aarch64-ios`): a flat bundle at the same call site -- no separate feature, no separate module -- with `MinimumOSVersion` from `mcpp::min_platform_version()` (#622 A11), `CFBundleSupportedPlatforms` read from `env == "sim"`, `UIDeviceFamily`, `LSRequiresIPhoneOS`, and a directory of flat PNGs listed under `CFBundleIcons` in place of macOS's single `.icns` file. Signing is skipped on the simulator row (`options::identity` is ignored, with a `mcpp::warning` naming why), and the device row signs only with an identity. The iOS row is measured end to end on `macos-15`: a real `mcpp build`, `mcpp pack --format app` and `mcpp run` against `aarch64-ios-sim`, through `xim:apple-simulator-tools`' `simctl-run`. **The macOS floor is one release higher than its siblings** and the reason is not this member: under 2026.9.11.1 `mcpp pack` staged before dispatching and let a staging failure fail the command, so on a Mach-O program -- which the built-in closure walk refuses, because it uses `LD_TRACE_LOADED_OBJECTS` and dyld answers that by running the program -- every dispatched format was unreachable, including one that reads no staged tree. 2026.9.11.2 makes staging a service to the provider. From 0.9.2 the staged tree's deployed files (`bin/<to>/...`, which the engine stages for a Mach-O program before the closure walk since the release for mcpp#630) land at the bundle's resource destination -- `Contents/Resources/<to>/...` on macOS, the bundle root on iOS -- and the launcher alone goes to the executable directory, so `CFBundleExecutable` names a file that is where it says. The iOS fixture declares `llvm.libcxx` and `llvm.compiler-rt-builtins` under `cfg(os = "ios")`, which is what an application that imports `std` on those rows declares. From 0.10.0, with mcpp 2026.9.14.2: the dylibs the engine stages beside a Mach-O program, which the stage manifest's `needs` lines name, go to `Contents/Frameworks/` (`Frameworks/` on iOS) and not to the resources; the program is linked with the rpath that finds them there (`@executable_path/../Frameworks`, `@executable_path/Frameworks` on iOS) through `mcpp::link_flag`, so no file is edited after the link; a macOS bundle without `options::identity` is signed ad hoc, frameworks first and the bundle second, which `codesign --verify --deep --strict` requires of a bundle that carries a framework; an incomplete closure is a `mcpp::warning` naming the unresolved libraries; every refusal is a `mcpp::warning` as well, because the engine discards a build program's output when it exits 0. On macOS the member supplies the runner named `app` (`macapp-run`), so `mcpp run --format app` runs the bundle's executable in the foreground and returns its status with no runner in the manifest; a manifest runner of that name wins. `--format dmg` stages the bundle beside an `Applications` link and writes a UDZO image with `hdiutil create` (`options::volume_name`, `options::dmg`); it is refused on iOS. An engine below 2026.9.14.2 stages no `needs` lines, so the bundle carries no framework, anchors the rpath to the package directory, and hands the bundle directory to the kernel under `mcpp run --format app` unless `--runner app` is typed. CI measures the bundle on `macos-15`: the load command, the signature, the program with and without its framework (exit 7, then "Library not loaded"), `mcpp run --format app` with and without `--runner app`, and `hdiutil verify` and an attached image. From 0.11.0: a project's own Info.plist entries (`options::info_plist`), an iOS device bundle's provisioning profile (`options::provisioning_profile`), and `devicectl-run` (`xim:apple-device-tools`) as the device row's runner named `app` -- see [`dist-apple`: a project's Info.plist, and an iOS device](#dist-apple-a-projects-infoplist-and-an-ios-device). From 0.12.0 `options::omit_keys` leaves out a key the member only defaults -- see [`dist-apple`: a project's Info.plist, and an iOS device](#dist-apple-a-projects-infoplist-and-an-ios-device) |
+| `dist-apple` | `mcpp.dist.apple` | 2026.9.14.2 (0.10.0); 2026.9.11.2 (macOS) and 2026.9.12.3 (iOS) before it | the base macOS install (`ditto`, `codesign`, `hdiutil`), and `xim:macapp-run` for `mcpp run` on macOS, which this feature declares with `when = "run"`. macOS: `Contents/`-shaped, as always. iOS (`aarch64-ios-sim`, `aarch64-ios`): a flat bundle at the same call site -- no separate feature, no separate module -- with `MinimumOSVersion` from `mcpp::min_platform_version()` (#622 A11), `CFBundleSupportedPlatforms` read from `env == "sim"`, `UIDeviceFamily`, `LSRequiresIPhoneOS`, and a directory of flat PNGs listed under `CFBundleIcons` in place of macOS's single `.icns` file. Signing is skipped on the simulator row (`options::identity` is ignored, with a `mcpp::warning` naming why), and the device row signs only with an identity. The iOS row is measured end to end on `macos-15`: a real `mcpp build`, `mcpp pack --format app` and `mcpp run` against `aarch64-ios-sim`, through `xim:apple-simulator-tools`' `simctl-run`. **The macOS floor is one release higher than its siblings** and the reason is not this member: under 2026.9.11.1 `mcpp pack` staged before dispatching and let a staging failure fail the command, so on a Mach-O program -- which the built-in closure walk refuses, because it uses `LD_TRACE_LOADED_OBJECTS` and dyld answers that by running the program -- every dispatched format was unreachable, including one that reads no staged tree. 2026.9.11.2 makes staging a service to the provider. From 0.9.2 the staged tree's deployed files (`bin/<to>/...`, which the engine stages for a Mach-O program before the closure walk since the release for mcpp#630) land at the bundle's resource destination -- `Contents/Resources/<to>/...` on macOS, the bundle root on iOS -- and the launcher alone goes to the executable directory, so `CFBundleExecutable` names a file that is where it says. The iOS fixture declares `llvm.libcxx` and `llvm.compiler-rt-builtins` under `cfg(os = "ios")`, which is what an application that imports `std` on those rows declares. From 0.10.0, with mcpp 2026.9.14.2: the dylibs the engine stages beside a Mach-O program, which the stage manifest's `needs` lines name, go to `Contents/Frameworks/` (`Frameworks/` on iOS) and not to the resources; the program is linked with the rpath that finds them there (`@executable_path/../Frameworks`, `@executable_path/Frameworks` on iOS) through `mcpp::link_flag`, so no file is edited after the link; a macOS bundle without `options::identity` is signed ad hoc, frameworks first and the bundle second, which `codesign --verify --deep --strict` requires of a bundle that carries a framework; an incomplete closure is a `mcpp::warning` naming the unresolved libraries; every refusal is a `mcpp::warning` as well, because the engine discards a build program's output when it exits 0. On macOS the member supplies the runner named `app` (`macapp-run`), so `mcpp run --format app` runs the bundle's executable in the foreground and returns its status with no runner in the manifest; a manifest runner of that name wins. `--format dmg` stages the bundle beside an `Applications` link and writes a UDZO image with `hdiutil create` (`options::volume_name`, `options::dmg`); it is refused on iOS. An engine below 2026.9.14.2 stages no `needs` lines, so the bundle carries no framework, anchors the rpath to the package directory, and hands the bundle directory to the kernel under `mcpp run --format app` unless `--runner app` is typed. CI measures the bundle on `macos-15`: the load command, the signature, the program with and without its framework (exit 7, then "Library not loaded"), `mcpp run --format app` with and without `--runner app`, and `hdiutil verify` and an attached image. From 0.11.0: a project's own Info.plist entries (`options::info_plist`), an iOS device bundle's provisioning profile (`options::provisioning_profile`), and `devicectl-run` (`xim:apple-device-tools`) as the device row's runner named `app` -- see [`dist-apple`: a project's Info.plist, and an iOS device](#dist-apple-a-projects-infoplist-and-an-ios-device). From 0.12.0 `options::omit_keys` leaves out a key the member only defaults -- see [`dist-apple`: a project's Info.plist, and an iOS device](#dist-apple-a-projects-infoplist-and-an-ios-device). From 0.12.0 a package in the resolved graph contributes Info.plist entries through `[package.metadata.dist-apple]`, applied before the application's own |
 | `dist-web` | `mcpp.dist.web` | 2026.9.13.1, the release that carries `${mcpp.self}` and `mcpp stage`'s argument shape as an engine contract (`stage --verify content --output <dst> <src>`) -- what lets this member's copy run on every host mcpp does, Windows included, in place of the `cp` this member used through 0.8.0 | nothing beyond mcpp: `wasm32-emscripten` only. Copies `${mcpp.stage_dir}/bin/` -- the `.js` launcher, the implicit `.wasm`, the `.data` when present, and every `mcpp::deploy`'d file, all of which #622 A5 and A4 already stage there -- to `<out_dir>/web/`, dropping the `bin/` prefix a browser has no use for, and writes an `index.html` rendered from a project template or a built-in default that loads the script with a plain `<script src>`. Each staged file and the rendered page are copied with `${mcpp.self} stage --verify content --output <dst> <src>`, the same copier every `stage_file` edge in `build.ninja` already runs -- no host-specific copy tool, no plan-time `create_directories` (`stage` creates the destination's parent), and a second `mcpp pack --format web` with nothing changed copies nothing. From 0.12.0 `options::page` names the page (`index.html` by default), for a project whose other build names it after the target; a name that is not a bare `*.html` file name is refused at plan time |
-| `dist-apk` | `mcpp.dist.apk` | 2026.9.14.2 from 0.10.0, which stages the closure this member reads; before it 2026.9.13.1, raised alongside `dist-web` in the same 0.9.0 release: this member's own manifest-template and Java-array changes ask nothing new of the engine, but this collection publishes one package at one version, and this is the release CI verifies it under from here on | `xim:android-build-tools`, `xim:android-platform` (versioned by API level, read back for `targetSdkVersion`), `xim:jdk-temurin` (`javac`/`jar`/`jarsigner`; `android-build-tools`' own runtime dependency provisions a JDK for its OWN wrappers only), `xim:android-debug-keystore`, `xim:bundletool` (0.10.0, for `--format aab`), all on the `cfg(env = "android")` axis. Generates `AndroidManifest.xml` and signs with the published Android debug key by default. Level 0 needs no Java (`hasCode="false"`, `android.app.NativeActivity`); `options::java_sources` adds `javac` + `d8` and a real `<activity>`. `options::manifest_template` renders a project manifest with six tokens substituted verbatim; `{{application_id}}` and `{{activity}}` are required always and `{{lib_name}}` at level 0, each refused by name at plan time when missing (naming `assets/mcpp-run.json`, which `adb-run` reads them from too) or when the template names an unknown token; empty renders 0.8.0's manifest byte-identically. From 0.9.3 the manifest template gains `{{version_name}}` / `{{version_code}}` (the package version, and `major * 1000000 + minor * 1000 + patch`). `options::resources` is a project's own `res/`, linked as the application's base resources from 0.9.1 (0.9.0 linked it as an aapt2 overlay, which refuses every resource the base does not already define -- a launcher icon could not be supplied). `options::java_sources` is an array: one `javac` over every root's `.java` files and one `d8` over the result, so a project's own sources and a path dependency's join without being merged into one directory first, and `rerun_if_changed_glob` is declared only for a root under `mcpp::manifest_dir()` -- a dependency root's files are already inputs of the `javac` action and its version is already in the build's fingerprint. Android only -- an `app` target is a shared object on this row (#622 A3). From 0.10.0, with mcpp 2026.9.14.2, the member reads the native closure the engine stages -- the application object, the graph's shared libraries and `libc++_shared.so` under `lib/` for one `--target`, `lib/<abi>/` for several -- and packs every ABI the tree carries into one APK; its own `NEEDED` walk and the stamp that lost a dependency's library on a second pack are gone. A stage manifest without `needs` lines comes from an engine below 2026.9.14.2 and is refused naming that floor, as is an incomplete closure, naming the unresolved libraries; every refusal is also a `mcpp::warning`, because the engine discards a build program's output when it exits 0. `--format aab` shares every step but the last three: `aapt2 link --proto-format` (with `--version-code` / `--version-name`, which bundletool requires), a base module in the layout bundletool reads, `bundletool build-bundle` from `xim:bundletool` (declared on the same axis), and `jarsigner` with the same keystore. CI packages both level 0 and level 1 and checks the archive (`mcpp::deploy`'d files under `assets/`), and on `tests/apk-consumer-shared` two packs in a row, a two-ABI APK (`aapt2` reports both, `apksigner` verifies it), an App Bundle (`bundletool validate`, `jarsigner -verify`, a universal APK from `bundletool build-apks`), a refusal's reason in `mcpp pack`'s output, and the floor refusal; the runner has no emulator or device, so the two rows that actually run were measured locally on 2026-09-12, through `adb-run`, against a KVM-accelerated x86_64 emulator and a physical arm64-v8a phone, both printing `1-2-3` and exiting 0. From 0.11.0: Kotlin sources (`dist-apk-kotlin`, which declares `xim:kotlin`), R classes, Android libraries from source, local AARs and JARs, a Maven graph through a lock file (`dist-apk-maven`, which declares `xim:coursier`), a manifest merge, and an unsigned package -- see [`dist-apk`: Kotlin, libraries and a Maven graph](#dist-apk-kotlin-libraries-and-a-maven-graph). From 0.11.1 the native libraries are packed as the Android Gradle plugin packs them: each is stripped with the build's own `llvm-strip --strip-unneeded` (the NDK's, beside the compiler `mcpp::toolchain_dir()` reports; `options::keep_debug_symbols` packs them as staged), and a manifest stating `android:extractNativeLibs="false"` gets them stored uncompressed on a 16 KB page, which loading them from the APK in place requires; CI checks both, and the symbol table `keep_debug_symbols` keeps. From 0.12.0 the engine's strip decision governs these libraries as well: under mcpp 2026.9.16.1, which publishes it to build programs as `MCPP_PACK_STRIP` and `MCPP_PACK_DEBUG_SYMBOLS_DIR`, `mcpp pack --no-strip` packs them as staged and `--debug-symbols <dir>` separates each library's debug information into `<dir>/<abi>/<library>.debug` with `llvm-objcopy` before stripping it and linking the packed copy to that file (`.gnu_debuglink`); a library is stripped unless either `keep_debug_symbols` or the engine says to keep it, and under an older engine, which publishes neither variable, the member strips as before |
+| `dist-apk` | `mcpp.dist.apk` | 2026.9.14.2 from 0.10.0, which stages the closure this member reads; before it 2026.9.13.1, raised alongside `dist-web` in the same 0.9.0 release: this member's own manifest-template and Java-array changes ask nothing new of the engine, but this collection publishes one package at one version, and this is the release CI verifies it under from here on | `xim:android-build-tools`, `xim:android-platform` (versioned by API level, read back for `targetSdkVersion`), `xim:jdk-temurin` (`javac`/`jar`/`jarsigner`; `android-build-tools`' own runtime dependency provisions a JDK for its OWN wrappers only), `xim:android-debug-keystore`, `xim:bundletool` (0.10.0, for `--format aab`), all on the `cfg(env = "android")` axis. Generates `AndroidManifest.xml` and signs with the published Android debug key by default. Level 0 needs no Java (`hasCode="false"`, `android.app.NativeActivity`); `options::java_sources` adds `javac` + `d8` and a real `<activity>`. `options::manifest_template` renders a project manifest with six tokens substituted verbatim; `{{application_id}}` and `{{activity}}` are required always and `{{lib_name}}` at level 0, each refused by name at plan time when missing (naming `assets/mcpp-run.json`, which `adb-run` reads them from too) or when the template names an unknown token; empty renders 0.8.0's manifest byte-identically. From 0.9.3 the manifest template gains `{{version_name}}` / `{{version_code}}` (the package version, and `major * 1000000 + minor * 1000 + patch`). `options::resources` is a project's own `res/`, linked as the application's base resources from 0.9.1 (0.9.0 linked it as an aapt2 overlay, which refuses every resource the base does not already define -- a launcher icon could not be supplied). `options::java_sources` is an array: one `javac` over every root's `.java` files and one `d8` over the result, so a project's own sources and a path dependency's join without being merged into one directory first, and `rerun_if_changed_glob` is declared only for a root under `mcpp::manifest_dir()` -- a dependency root's files are already inputs of the `javac` action and its version is already in the build's fingerprint. Android only -- an `app` target is a shared object on this row (#622 A3). From 0.10.0, with mcpp 2026.9.14.2, the member reads the native closure the engine stages -- the application object, the graph's shared libraries and `libc++_shared.so` under `lib/` for one `--target`, `lib/<abi>/` for several -- and packs every ABI the tree carries into one APK; its own `NEEDED` walk and the stamp that lost a dependency's library on a second pack are gone. A stage manifest without `needs` lines comes from an engine below 2026.9.14.2 and is refused naming that floor, as is an incomplete closure, naming the unresolved libraries; every refusal is also a `mcpp::warning`, because the engine discards a build program's output when it exits 0. `--format aab` shares every step but the last three: `aapt2 link --proto-format` (with `--version-code` / `--version-name`, which bundletool requires), a base module in the layout bundletool reads, `bundletool build-bundle` from `xim:bundletool` (declared on the same axis), and `jarsigner` with the same keystore. CI packages both level 0 and level 1 and checks the archive (`mcpp::deploy`'d files under `assets/`), and on `tests/apk-consumer-shared` two packs in a row, a two-ABI APK (`aapt2` reports both, `apksigner` verifies it), an App Bundle (`bundletool validate`, `jarsigner -verify`, a universal APK from `bundletool build-apks`), a refusal's reason in `mcpp pack`'s output, and the floor refusal; the runner has no emulator or device, so the two rows that actually run were measured locally on 2026-09-12, through `adb-run`, against a KVM-accelerated x86_64 emulator and a physical arm64-v8a phone, both printing `1-2-3` and exiting 0. From 0.11.0: Kotlin sources (`dist-apk-kotlin`, which declares `xim:kotlin`), R classes, Android libraries from source, local AARs and JARs, a Maven graph through a lock file (`dist-apk-maven`, which declares `xim:coursier`), a manifest merge, and an unsigned package -- see [`dist-apk`: Kotlin, libraries and a Maven graph](#dist-apk-kotlin-libraries-and-a-maven-graph). From 0.11.1 the native libraries are packed as the Android Gradle plugin packs them: each is stripped with the build's own `llvm-strip --strip-unneeded` (the NDK's, beside the compiler `mcpp::toolchain_dir()` reports; `options::keep_debug_symbols` packs them as staged), and a manifest stating `android:extractNativeLibs="false"` gets them stored uncompressed on a 16 KB page, which loading them from the APK in place requires; CI checks both, and the symbol table `keep_debug_symbols` keeps. From 0.12.0 the engine's strip decision governs these libraries as well: under mcpp 2026.9.16.1, which publishes it to build programs as `MCPP_PACK_STRIP` and `MCPP_PACK_DEBUG_SYMBOLS_DIR`, `mcpp pack --no-strip` packs them as staged and `--debug-symbols <dir>` separates each library's debug information into `<dir>/<abi>/<library>.debug` with `llvm-objcopy` before stripping it and linking the packed copy to that file (`.gnu_debuglink`); a library is stripped unless either `keep_debug_symbols` or the engine says to keep it, and under an older engine, which publishes neither variable, the member strips as before. From 0.12.0 a library in the resolved graph contributes libraries and archives through `[package.metadata.dist-apk]`, ranked below the application's own -- see [A library states its contribution](#a-library-states-its-contribution-packagemetadatadist-apk) |
 
 ### Each rule brings its own environment
 
@@ -682,6 +682,7 @@ Every path option is relative to the manifest or absolute.
 | `libraries` | Android libraries from source, each with `package` (its R package), `resources`, `manifest`, `assets`, `java_sources` and `kotlin_sources`. A library listed earlier wins a resource both define, and the application's own `resources` win over every library | |
 | `aars`, `jars` | Local archives. A JAR joins the classpath and the dex. An AAR contributes `classes.jar`, `res/` (under the package its manifest names), its manifest, `jni/<abi>/*.so` and `assets/`. Archives rank after `libraries` | |
 | `maven`, `maven_repositories`, `maven_lock`, `maven_cache` | `group:artifact:version` coordinates, resolved with their transitive dependencies into a lock file. The resolved AARs and JARs are then handled like `aars` and `jars`, and rank after them. The defaults are Google's Maven repository then Maven Central, `maven.lock` beside the manifest, and `COURSIER_CACHE` then coursier's own cache directory for the host | `xim:coursier`, declared by the `dist-apk-maven` feature |
+| `graph_libraries` | From 0.12.0, `true` by default: the libraries and archives the resolved graph's packages state in `[package.metadata.dist-apk]` (see below). `false` reads none, for an application that lists every library itself | |
 | `sign` | `false` writes the aligned package unsigned, with no `apksigner` for an APK and no `jarsigner` for an App Bundle, for a pipeline that signs elsewhere. It is refused together with `keystore` | |
 
 Both features imply `dist-apk`, so a project names them in its place:
@@ -748,14 +749,65 @@ target triple on that host's link line only for an Apple row
 Windows NDK carries no libc++ module surface (`xim-pkgindex`,
 `pkgs/a/android-ndk.lua`).
 
+### A library states its contribution: `[package.metadata.dist-apk]`
+
+From 0.12.0, with mcpp 2026.9.16.1, a library states in its own manifest what it
+contributes to an Android package, and every application that depends on it
+carries that without naming the library in its build program:
+
+```toml
+# the library's mcpp.toml
+[package.metadata.dist-apk]
+package        = "org.example.widgets"   # its R package
+resources      = "android/res"
+manifest       = "android/AndroidManifest.xml"
+assets         = "android/assets"
+java_sources   = ["android/java"]
+kotlin_sources = ["android/kotlin"]
+jars           = ["android/libs/support.jar"]
+aars           = ["android/libs/player.aar"]
+```
+
+Every key is optional, and each has the meaning of the `library` field or the
+option of the same name; paths are relative to the library's directory. The
+engine hands the application's build program the resolved graph
+(`MCPP_GRAPH_FILE`), and `dist-apk` reads the table of every package in it other
+than the application. The contributions rank below the application's own
+`libraries`, `jars` and `aars`, and a package ranks above the packages it depends
+on, so an application's resource overrides a library's and a library's overrides
+the framework beneath it. A key of the wrong shape is refused naming the package
+and the key; a key this version does not read is reported with a warning and
+ignored, so a library may state a key a newer collection reads. Under an older
+engine there is no graph, and nothing is contributed. CI checks both engines on
+`tests/apk-consumer-graph`.
+
 ## `dist-apple`: a project's Info.plist, and an iOS device
 
 | option | what it does |
 |---|---|
 | `info_plist` | A plist whose top-level `<dict>` entries join the bundle's Info.plist: usage descriptions, URL types, background modes. A key the member derives is refused by name: `CFBundleExecutable`, `CFBundleIdentifier`, `CFBundleName`, `CFBundleShortVersionString`, `CFBundleVersion`, `CFBundlePackageType`, `LSMinimumSystemVersion`, `MinimumOSVersion`, `CFBundleSupportedPlatforms`, `CFBundleIconFile`, `CFBundleIcons`. A key it only defaults takes the project's value: `UIDeviceFamily`, `LSRequiresIPhoneOS`, `NSHighResolutionCapable`. Without `info_plist` the plist is byte-identical to 0.10.1's |
 | `omit_keys` | From 0.12.0. Defaulted keys to leave out of the Info.plist, for a project whose other build states neither: `UIDeviceFamily`, `LSRequiresIPhoneOS`, `NSHighResolutionCapable`. A property list has no null, so `info_plist` can replace a default's value but cannot remove its key. A key the member derives, a key it never writes, a key named twice, and a key `info_plist` also sets are each refused by name. A key that does not apply to the row (`UIDeviceFamily` on macOS) changes nothing |
+| `graph_info_plist` | From 0.12.0, `true` by default: the Info.plist entries the resolved graph's packages state (see below). `false` reads none |
 | `provisioning_profile` | The device row (`aarch64-ios`) only, and only with `identity`. The profile is embedded as `embedded.mobileprovision`. Its `Entitlements` dictionary signs the bundle unless `entitlements` names a file, with a wildcard `application-identifier` stated as the bundle's own. That identifier must cover the bundle identifier: exactly, `<team>.*`, or `<team>.<prefix>.*`. The plist is read from the profile's bytes, so a plan made on any host checks it; verifying the profile's CMS signature is left to `codesign` and the device |
 
+A library states its Info.plist entries in its own manifest (0.12.0, mcpp
+2026.9.16.1), as a plist of the shape `info_plist` takes, its path relative to
+the library's directory:
+
+```toml
+# the library's mcpp.toml
+[package.metadata.dist-apple]
+info_plist = "apple/Info-fragment.plist"
+```
+
+The entries of every package in the resolved graph other than the application
+are applied in the graph's order, dependencies first, so a package overrides the
+packages it depends on; the application's own `info_plist` is applied last and
+wins every key, and a key the application names in `omit_keys` is left out
+whoever contributes it. A key the member derives is refused in a contribution as
+in `info_plist`, naming the package. Under an older engine there is no graph, and
+nothing is contributed.
+
 On the device row the member supplies the runner named `app`: `devicectl-run`,
 from `xim:apple-device-tools`, which the feature declares with `when = "run"` on
 that row alone. `mcpp run --target aarch64-ios --format app` installs the signed
@@ -770,7 +822,10 @@ status have not been measured on one; `devicectl-run` prints that when it runs.
 CI measures the rest:
 
 - On Linux, the plan: the entries, a refused key, an omitted default on iOS
-  and on macOS and the three refusals of `omit_keys`, the embedded profile, the
+  and on macOS and the three refusals of `omit_keys`, the graph's entries in
+  the graph's order with the application's winning and `graph_info_plist =
+  false`, a contributed derived key refused naming its package, an unreadable
+  graph document refused, the embedded profile, the
   entitlements, a wildcard profile, and the refusals of a profile for another
   identifier, on the simulator row, or without an identity.
 - On `macos-15`: the entries in a real macOS bundle that `plutil` accepts and
diff --git a/dist/apk.cppm b/dist/apk.cppm
index 8c31024..3e7b26b 100644
--- a/dist/apk.cppm
+++ b/dist/apk.cppm
@@ -247,6 +247,26 @@ struct options {
     // does, and the application's own `resources` win over every library.
     std::vector<library> libraries;
 
+    // LIBRARIES THE GRAPH CONTRIBUTES (0.12.0). With mcpp 2026.9.16.1 the root
+    // project's build program receives the resolved graph, and every package in
+    // it other than the application that states `[package.metadata.dist-apk]`
+    // contributes a library of the shape above (`package`, `resources`,
+    // `manifest`, `assets`, `java_sources`, `kotlin_sources`) and archives
+    // (`jars`, `aars`), its paths relative to that package's directory. A
+    // framework's library therefore reaches every application that depends on
+    // it without being listed in the application's build program.
+    //
+    // RANKED BELOW THE APPLICATION'S OWN ENTRIES, and among themselves a package
+    // above the packages it depends on: the graph lists dependencies first, so
+    // contributions are taken in reverse. An application's `libraries` still win
+    // a resource any contribution defines, and a library wins over the framework
+    // beneath it, which is the order a Gradle build gives the same modules.
+    //
+    // `false` reads no contribution, for an application that lists every
+    // library itself. Under an older engine, or in a dependency's own build
+    // program, there is no graph, and nothing is contributed either way.
+    bool graph_libraries = true;
+
     // LOCAL ARCHIVES (0.11.0). A JAR joins the classpath and the dex. An AAR
     // contributes its classes, its resources (under the package its manifest
     // names), its manifest, its native libraries and its assets. Archives
@@ -1032,120 +1052,12 @@ inline bool merge_manifests(std::string& appText, const std::vector<manifest_sou
     return true;
 }
 
-// ─── JSON, as far as coursier's report needs it ───────────────────────────
-
-struct json_value {
-    enum class kind { null, boolean, number, string, array, object };
-    kind                                             type = kind::null;
-    std::string                                      text;    // string, number or boolean spelling
-    std::vector<json_value>                          items;
-    std::vector<std::pair<std::string, json_value>>  members;
-
-    const json_value* get(std::string_view key) const {
-        for (auto const& m : members) if (m.first == key) return &m.second;
-        return nullptr;
-    }
-};
-
-struct json_reader {
-    std::string_view s;
-    std::size_t      i = 0;
-
-    void skip_space() {
-        while (i < s.size() && (s[i] == ' ' || s[i] == '\t' || s[i] == '\n' || s[i] == '\r')) ++i;
-    }
-    bool string(std::string& out) {
-        if (i >= s.size() || s[i] != '"') return false;
-        ++i;
-        while (i < s.size() && s[i] != '"') {
-            if (s[i] != '\\') { out += s[i++]; continue; }
-            if (++i >= s.size()) return false;
-            const char e = s[i++];
-            switch (e) {
-                case 'n': out += '\n'; break;
-                case 't': out += '\t'; break;
-                case 'r': out += '\r'; break;
-                case 'b': out += '\b'; break;
-                case 'f': out += '\f'; break;
-                case 'u': {
-                    if (i + 4 > s.size()) return false;
-                    unsigned cp = 0;
-                    for (int k = 0; k < 4; ++k) {
-                        const char h = s[i++];
-                        cp <<= 4;
-                        if (h >= '0' && h <= '9') cp |= static_cast<unsigned>(h - '0');
-                        else if (h >= 'a' && h <= 'f') cp |= static_cast<unsigned>(h - 'a' + 10);
-                        else if (h >= 'A' && h <= 'F') cp |= static_cast<unsigned>(h - 'A' + 10);
-                        else return false;
-                    }
-                    if (cp < 0x80) out += static_cast<char>(cp);
-                    else if (cp < 0x800) { out += static_cast<char>(0xc0 | (cp >> 6)); out += static_cast<char>(0x80 | (cp & 0x3f)); }
-                    else { out += static_cast<char>(0xe0 | (cp >> 12)); out += static_cast<char>(0x80 | ((cp >> 6) & 0x3f)); out += static_cast<char>(0x80 | (cp & 0x3f)); }
-                    break;
-                }
-                default: out += e;
-            }
-        }
-        if (i >= s.size()) return false;
-        ++i;
-        return true;
-    }
-    bool value(json_value& out) {
-        skip_space();
-        if (i >= s.size()) return false;
-        const char c = s[i];
-        if (c == '"') { out.type = json_value::kind::string; return string(out.text); }
-        if (c == '{') {
-            out.type = json_value::kind::object;
-            ++i;
-            skip_space();
-            if (i < s.size() && s[i] == '}') { ++i; return true; }
-            for (;;) {
-                skip_space();
-                std::string key;
-                if (!string(key)) return false;
-                skip_space();
-                if (i >= s.size() || s[i] != ':') return false;
-                ++i;
-                json_value v;
-                if (!value(v)) return false;
-                out.members.emplace_back(std::move(key), std::move(v));
-                skip_space();
-                if (i < s.size() && s[i] == ',') { ++i; continue; }
-                if (i < s.size() && s[i] == '}') { ++i; return true; }
-                return false;
-            }
-        }
-        if (c == '[') {
-            out.type = json_value::kind::array;
-            ++i;
-            skip_space();
-            if (i < s.size() && s[i] == ']') { ++i; return true; }
-            for (;;) {
-                json_value v;
-                if (!value(v)) return false;
-                out.items.push_back(std::move(v));
-                skip_space();
-                if (i < s.size() && s[i] == ',') { ++i; continue; }
-                if (i < s.size() && s[i] == ']') { ++i; return true; }
-                return false;
-            }
-        }
-        const std::size_t b = i;
-        while (i < s.size() && s[i] != ',' && s[i] != '}' && s[i] != ']' &&
-               s[i] != ' ' && s[i] != '\n' && s[i] != '\r' && s[i] != '\t') ++i;
-        out.text = std::string(s.substr(b, i - b));
-        if (out.text == "null") out.type = json_value::kind::null;
-        else if (out.text == "true" || out.text == "false") out.type = json_value::kind::boolean;
-        else out.type = json_value::kind::number;
-        return !out.text.empty();
-    }
-};
-
-inline bool parse_json(std::string_view text, json_value& out) {
-    json_reader r{text};
-    return r.value(out);
-}
+// ─── JSON ─────────────────────────────────────────────────────────────────
+//
+// coursier's report is read with the collection's shared reader, the one
+// `mcpp::plugins::graph` reads the engine's graph document with.
+using json_value = mcpp::plugins::json::value;
+using mcpp::plugins::json::parse_json;
 
 // ─── The Maven lock ───────────────────────────────────────────────────────
 
@@ -1488,6 +1400,88 @@ inline plan plan_for(options opt = {}) {
         }
     }
 
+    // ── the libraries the graph contributes (0.12.0) ─────────────────────
+    //
+    // Appended after the application's own `libraries`, `jars` and `aars`,
+    // which keeps them highest; the graph's packages are taken requesters first
+    // (the reverse of the document's order). Their paths are made absolute
+    // against each package's directory here, so the manifest-relative
+    // resolution below leaves them as they are. `labels` names each library in
+    // a diagnostic: empty for the application's own.
+    std::vector<std::string> labels(opt.libraries.size());
+    if (opt.graph_libraries) {
+        auto graph = mcpp::plugins::graph::read();
+        if (!graph) {
+            return refuse(p, "unreadable graph document", std::format(
+                "mcpp.dist.apk: {}; the libraries its packages contribute cannot be collected. "
+                "Set options::graph_libraries = false to list every library in options::libraries.",
+                graph.error()));
+        }
+        for (std::size_t k = graph->packages.size(); k-- > 0;) {
+            const auto& pkg = graph->packages[k];
+            if (pkg.root) continue;
+            const json_value* t = mcpp::plugins::graph::table_of(pkg, "dist-apk");
+            if (!t) continue;
+            const std::string who = std::format("the [package.metadata.dist-apk] of {}",
+                                                mcpp::plugins::graph::label_of(pkg));
+            library l;
+            std::vector<std::string> jarList, aarList;
+            for (auto const& [key, v] : t->members) {
+                const bool isString = v.type == json_value::kind::string;
+                const bool isList   = v.type == json_value::kind::array
+                    && std::ranges::all_of(v.items, [](const json_value& e) {
+                           return e.type == json_value::kind::string; });
+                const auto wants = [&](bool ok, const char* shape) -> bool {
+                    if (!ok) {
+                        refuse(p, "malformed graph contribution", std::format(
+                            "mcpp.dist.apk: {} states `{}` as something other than {}.",
+                            who, key, shape));
+                    }
+                    return ok;
+                };
+                const auto strings = [&]() {
+                    std::vector<std::string> out;
+                    for (auto const& e : v.items) out.push_back(mcpp::plugins::graph::resolve(pkg, e.text));
+                    return out;
+                };
+                if (key == "package") {
+                    if (!wants(isString, "a string")) return p;
+                    l.package = v.text;
+                } else if (key == "resources" || key == "manifest" || key == "assets") {
+                    if (!wants(isString, "a path")) return p;
+                    const std::string path = mcpp::plugins::graph::resolve(pkg, v.text);
+                    (key == "resources" ? l.resources : key == "manifest" ? l.manifest : l.assets) = path;
+                } else if (key == "java_sources" || key == "kotlin_sources"
+                           || key == "jars" || key == "aars") {
+                    if (!wants(isList, "a list of paths")) return p;
+                    auto list = strings();
+                    if (key == "java_sources")        l.java_sources   = std::move(list);
+                    else if (key == "kotlin_sources") l.kotlin_sources = std::move(list);
+                    else if (key == "jars")           jarList          = std::move(list);
+                    else                              aarList          = std::move(list);
+                } else {
+                    // Warned, not refused: a package published for a newer
+                    // collection may state a key this one does not read, and
+                    // refusing it would break every application built with this
+                    // version.
+                    mcpp::warning(std::format(
+                        "mcpp.dist.apk: {} states `{}`, which this version of the member does "
+                        "not read; it is ignored.", who, key).c_str());
+                }
+            }
+            const bool isLibrary = !l.package.empty() || !l.resources.empty() || !l.manifest.empty()
+                || !l.assets.empty() || !l.java_sources.empty() || !l.kotlin_sources.empty();
+            if (isLibrary) {
+                opt.libraries.push_back(std::move(l));
+                labels.push_back(std::format("the library {} ({})",
+                    opt.libraries.back().package.empty() ? mcpp::plugins::graph::label_of(pkg)
+                                                         : opt.libraries.back().package, who));
+            }
+            for (auto& j : jarList) opt.jars.push_back(std::move(j));
+            for (auto& a : aarList) opt.aars.push_back(std::move(a));
+        }
+    }
+
     // Every path option, resolved against the manifest once (`resolve_path`).
     opt.resources = resolve_path(opt.resources);
     resolve_paths(opt.java_sources);
@@ -1632,7 +1626,9 @@ inline plan plan_for(options opt = {}) {
     for (std::size_t i = 0; i < opt.libraries.size(); ++i) {
         const auto& l = opt.libraries[i];
         library_input in;
-        in.label   = l.package.empty() ? std::format("options::libraries[{}]", i)
+        in.label   = i < labels.size() && !labels[i].empty()
+                   ? labels[i]
+                   : l.package.empty() ? std::format("options::libraries[{}]", i)
                                        : std::format("the library {}", l.package);
         in.package = l.package;
         if (!l.resources.empty()) {
@@ -1642,9 +1638,14 @@ inline plan plan_for(options opt = {}) {
                     in.label, l.resources));
             }
             if (l.package.empty()) {
-                return refuse(p, "library resources without a package", std::format(
-                    "mcpp.dist.apk: options::libraries[{}] has resources and no package; its "
-                    "R class needs one. Set options::libraries[{}].package.", i, i));
+                return refuse(p, "library resources without a package",
+                    i < labels.size() && !labels[i].empty()
+                    ? std::format(
+                        "mcpp.dist.apk: {} has resources and no package; its R class needs "
+                        "one. Set `package` in that [package.metadata.dist-apk] table.", labels[i])
+                    : std::format(
+                        "mcpp.dist.apk: options::libraries[{}] has resources and no package; its "
+                        "R class needs one. Set options::libraries[{}].package.", i, i));
             }
             in.resources = l.resources;
         }
diff --git a/dist/apple.cppm b/dist/apple.cppm
index 3888f99..d2d468b 100644
--- a/dist/apple.cppm
+++ b/dist/apple.cppm
@@ -304,6 +304,24 @@ struct options {
     // row (`UIDeviceFamily` on macOS) is accepted and changes nothing.
     std::vector<std::string> omit_keys;
 
+    // Info.plist ENTRIES THE GRAPH CONTRIBUTES (0.12.0). With mcpp 2026.9.16.1
+    // the root project's build program receives the resolved graph, and every
+    // package in it other than the application that states
+    // `[package.metadata.dist-apple] info_plist = "<file>"` contributes that
+    // plist's entries, the path relative to the package's directory: a library
+    // that needs a usage description or a background mode states it once, and
+    // every application that depends on it carries it. The entries are applied
+    // in the graph's order, dependencies first, so a package overrides the
+    // packages it depends on, and the application's own `info_plist` is applied
+    // last and wins every key. The keys this member derives are refused in a
+    // contribution as in `info_plist`, naming the package; a key the application
+    // names in `omit_keys` is left out whoever contributes it.
+    //
+    // `false` reads no contribution. Under an older engine, or in a dependency's
+    // own build program, there is no graph, and nothing is contributed either
+    // way.
+    bool graph_info_plist = true;
+
     // AN iOS DEVICE BUNDLE'S PROVISIONING PROFILE (0.11.0), manifest-relative or
     // absolute: embedded as `embedded.mobileprovision`, and, when `entitlements`
     // is empty, the source of the entitlements the bundle is signed with (the
@@ -673,44 +691,52 @@ inline bool dict_entries(const mcpp::plugins::xml::node& dict,
     return true;
 }
 
-// Reads `options::info_plist`: the entries to add, as the plist text
-// `plist_document` inserts, and the defaulted keys they replace.
-inline bool read_info_plist_fragment(const std::string& path, std::string& entries,
-                                     std::vector<std::string>& replaced, std::string& message) {
+// One Info.plist entry a fragment states: its key and the plist text of the
+// `<key>` and its value, as `plist_document` inserts it.
+struct plist_entry {
+    std::string key;
+    std::string text;
+};
+
+// Reads one plist fragment's entries. `who` is how a diagnostic names the
+// fragment (`options::info_plist`, or a package's [package.metadata.dist-apple]).
+inline bool read_plist_entries(const std::string& path, const std::string& who,
+                               std::vector<plist_entry>& out, std::string& message) {
     namespace xml = mcpp::plugins::xml;
     xml::node root;
     std::string err;
     if (!xml::parse(read_text(path), root, err)) {
-        message = std::format("mcpp.dist.apple: `options::info_plist` ({}) cannot be read: {}", path, err);
+        message = std::format("mcpp.dist.apple: {} ({}) cannot be read: {}", who, path, err);
         return false;
     }
     const xml::node* dict = top_dict(root);
     if (!dict) {
-        message = std::format("mcpp.dist.apple: `options::info_plist` ({}) has no top-level <dict>.", path);
+        message = std::format("mcpp.dist.apple: {} ({}) has no top-level <dict>.", who, path);
         return false;
     }
     std::vector<std::pair<std::string, const xml::node*>> pairs;
     if (!dict_entries(*dict, pairs, err)) {
-        message = std::format("mcpp.dist.apple: `options::info_plist` ({}): {}", path, err);
+        message = std::format("mcpp.dist.apple: {} ({}): {}", who, path, err);
         return false;
     }
     std::vector<std::string> seen;
     for (auto const& [key, value] : pairs) {
         if (std::ranges::find(derived_plist_keys(), key) != derived_plist_keys().end()) {
             message = std::format(
-                "mcpp.dist.apple: `options::info_plist` ({}) sets {}, which this member derives "
-                "from its options and the engine; set the option instead.", path, key);
+                "mcpp.dist.apple: {} ({}) sets {}, which this member derives "
+                "from its options and the engine; set the option instead.", who, path, key);
             return false;
         }
         if (std::ranges::find(seen, key) != seen.end()) {
-            message = std::format("mcpp.dist.apple: `options::info_plist` ({}) sets {} twice.", path, key);
+            message = std::format("mcpp.dist.apple: {} ({}) sets {} twice.", who, path, key);
             return false;
         }
         seen.push_back(key);
-        if (std::ranges::find(defaulted_plist_keys(), key) != defaulted_plist_keys().end())
-            replaced.push_back(key);
-        entries += "    <key>" + key + "</key>\n";
-        xml::write(*value, entries, 1);
+        plist_entry e;
+        e.key  = key;
+        e.text = "    <key>" + key + "</key>\n";
+        xml::write(*value, e.text, 1);
+        out.push_back(std::move(e));
     }
     return true;
 }
@@ -949,6 +975,10 @@ inline plan plan_for(options opt = {}) {
     opt.provisioning_profile = resolve_path(opt.provisioning_profile);
     std::string extraEntries;
     std::vector<std::string> replacedKeys;
+    std::vector<std::string> contributedDefaults;
+    // The application's own entries, read first so that their refusals come
+    // before any contribution's; they are applied last.
+    std::vector<plist_entry> ownEntries;
     if (!opt.info_plist.empty()) {
         if (!is_file(opt.info_plist)) {
             return refuse(p, "info_plist not found", std::format(
@@ -956,8 +986,72 @@ inline plan plan_for(options opt = {}) {
         }
         mcpp::rerun_if_changed(opt.info_plist.c_str());
         std::string message;
-        if (!read_info_plist_fragment(opt.info_plist, extraEntries, replacedKeys, message))
+        if (!read_plist_entries(opt.info_plist, "`options::info_plist`", ownEntries, message))
             return refuse(p, "unusable info_plist", message);
+        for (auto const& e : ownEntries)
+            if (std::ranges::find(defaulted_plist_keys(), e.key) != defaulted_plist_keys().end())
+                replacedKeys.push_back(e.key);
+    }
+
+    // The entries the graph's packages contribute, in the graph's order
+    // (dependencies first), each replacing an earlier contribution of the same
+    // key; then the application's own, replacing any contribution.
+    std::vector<plist_entry> merged;
+    const auto apply_entries = [&](const std::vector<plist_entry>& list) {
+        for (auto const& e : list) {
+            auto it = std::ranges::find_if(merged, [&](const plist_entry& m) { return m.key == e.key; });
+            if (it != merged.end()) it->text = e.text;
+            else merged.push_back(e);
+        }
+    };
+    if (opt.graph_info_plist) {
+        auto graph = mcpp::plugins::graph::read();
+        if (!graph) {
+            return refuse(p, "unreadable graph document", std::format(
+                "mcpp.dist.apple: {}; the Info.plist entries its packages contribute cannot be "
+                "collected. Set `options::graph_info_plist = false` to read none.", graph.error()));
+        }
+        for (auto const& pkg : graph->packages) {
+            if (pkg.root) continue;
+            const auto* t = mcpp::plugins::graph::table_of(pkg, "dist-apple");
+            if (!t) continue;
+            const std::string who = std::format("the [package.metadata.dist-apple] of {}",
+                                                mcpp::plugins::graph::label_of(pkg));
+            for (auto const& [key, v] : t->members) {
+                if (key == "info_plist") continue;
+                mcpp::warning(std::format(
+                    "mcpp.dist.apple: {} states `{}`, which this version of the member does not "
+                    "read; it is ignored.", who, key).c_str());
+            }
+            const auto* ip = t->get("info_plist");
+            if (!ip) continue;
+            if (ip->type != mcpp::plugins::json::value::kind::string || ip->text.empty()) {
+                return refuse(p, "malformed graph contribution", std::format(
+                    "mcpp.dist.apple: {} states `info_plist` as something other than a path.", who));
+            }
+            const std::string path = mcpp::plugins::graph::resolve(pkg, ip->text);
+            if (!is_file(path)) {
+                return refuse(p, "contributed info_plist not found", std::format(
+                    "mcpp.dist.apple: {} names the Info.plist fragment {}, which was not found.", who, path));
+            }
+            mcpp::rerun_if_changed(path.c_str());
+            std::vector<plist_entry> list;
+            std::string message;
+            if (!read_plist_entries(path, who, list, message))
+                return refuse(p, "unusable contributed info_plist", message);
+            apply_entries(list);
+        }
+    }
+    // The application's own entries win; a key it omits is left out whoever
+    // contributed it. The omit_keys checks below still see only the
+    // application's own entries in `replacedKeys`.
+    apply_entries(ownEntries);
+    for (auto const& e : merged) {
+        if (std::ranges::find(opt.omit_keys, e.key) != opt.omit_keys.end()) continue;
+        extraEntries += e.text;
+        if (std::ranges::find(defaulted_plist_keys(), e.key) != defaulted_plist_keys().end()
+            && std::ranges::find(replacedKeys, e.key) == replacedKeys.end())
+            contributedDefaults.push_back(e.key);
     }
     for (std::size_t i = 0; i < opt.omit_keys.size(); ++i) {
         const auto& key = opt.omit_keys[i];
@@ -984,8 +1078,10 @@ inline plan plan_for(options opt = {}) {
         }
     }
     // An omitted default is written the way a replaced one is: not at all. The
-    // replaced list is what `plist_document` consults, so the two share it.
+    // replaced list is what `plist_document` consults, so the two share it, and
+    // a defaulted key a contribution states replaces the default the same way.
     for (auto const& key : opt.omit_keys) replacedKeys.push_back(key);
+    for (auto const& key : contributedDefaults) replacedKeys.push_back(key);
     if (!opt.entitlements.empty() && !is_file(opt.entitlements)) {
         return refuse(p, "entitlements not found", std::format(
             "mcpp.dist.apple: the entitlements file {} was not found", opt.entitlements));
diff --git a/src/plugins.cppm b/src/plugins.cppm
index b9e9987..17394eb 100644
--- a/src/plugins.cppm
+++ b/src/plugins.cppm
@@ -263,6 +263,232 @@ inline void set_attr(node& n, const std::string& key, const std::string& value)
 
 } // namespace mcpp::plugins::xml
 
+// mcpp::plugins::json -- the JSON two dist members read.
+//
+// SHARED BECAUSE TWO DOCUMENTS ARE READ WITH IT. `dist-apk` reads coursier's
+// resolution report, and `mcpp::plugins::graph` below reads the engine's graph
+// document for `dist-apk` and `dist-apple`. A second parser for the second
+// document is how two readers come to disagree about one file, so there is one.
+// It reads objects, arrays, strings (with `\u` escapes below U+10000), numbers,
+// `true`, `false` and `null`; a number keeps its spelling in `text`.
+export namespace mcpp::plugins::json {
+
+struct value {
+    enum class kind { null, boolean, number, string, array, object };
+    kind                                             type = kind::null;
+    std::string                                      text;    // string, number or boolean spelling
+    std::vector<value>                               items;
+    std::vector<std::pair<std::string, value>>       members;
+
+    const value* get(std::string_view key) const {
+        for (auto const& m : members) if (m.first == key) return &m.second;
+        return nullptr;
+    }
+};
+
+struct reader {
+    std::string_view s;
+    std::size_t      i = 0;
+
+    void skip_space() {
+        while (i < s.size() && (s[i] == ' ' || s[i] == '\t' || s[i] == '\n' || s[i] == '\r')) ++i;
+    }
+    bool string(std::string& out) {
+        if (i >= s.size() || s[i] != '"') return false;
+        ++i;
+        while (i < s.size() && s[i] != '"') {
+            if (s[i] != '\\') { out += s[i++]; continue; }
+            if (++i >= s.size()) return false;
+            const char e = s[i++];
+            switch (e) {
+                case 'n': out += '\n'; break;
+                case 't': out += '\t'; break;
+                case 'r': out += '\r'; break;
+                case 'b': out += '\b'; break;
+                case 'f': out += '\f'; break;
+                case 'u': {
+                    if (i + 4 > s.size()) return false;
+                    unsigned cp = 0;
+                    for (int k = 0; k < 4; ++k) {
+                        const char h = s[i++];
+                        cp <<= 4;
+                        if (h >= '0' && h <= '9') cp |= static_cast<unsigned>(h - '0');
+                        else if (h >= 'a' && h <= 'f') cp |= static_cast<unsigned>(h - 'a' + 10);
+                        else if (h >= 'A' && h <= 'F') cp |= static_cast<unsigned>(h - 'A' + 10);
+                        else return false;
+                    }
+                    if (cp < 0x80) out += static_cast<char>(cp);
+                    else if (cp < 0x800) { out += static_cast<char>(0xc0 | (cp >> 6)); out += static_cast<char>(0x80 | (cp & 0x3f)); }
+                    else { out += static_cast<char>(0xe0 | (cp >> 12)); out += static_cast<char>(0x80 | ((cp >> 6) & 0x3f)); out += static_cast<char>(0x80 | (cp & 0x3f)); }
+                    break;
+                }
+                default: out += e;
+            }
+        }
+        if (i >= s.size()) return false;
+        ++i;
+        return true;
+    }
+    bool parse_value(value& out) {
+        skip_space();
+        if (i >= s.size()) return false;
+        const char c = s[i];
+        if (c == '"') { out.type = value::kind::string; return string(out.text); }
+        if (c == '{') {
+            out.type = value::kind::object;
+            ++i;
+            skip_space();
+            if (i < s.size() && s[i] == '}') { ++i; return true; }
+            for (;;) {
+                skip_space();
+                std::string key;
+                if (!string(key)) return false;
+                skip_space();
+                if (i >= s.size() || s[i] != ':') return false;
+                ++i;
+                value v;
+                if (!parse_value(v)) return false;
+                out.members.emplace_back(std::move(key), std::move(v));
+                skip_space();
+                if (i < s.size() && s[i] == ',') { ++i; continue; }
+                if (i < s.size() && s[i] == '}') { ++i; return true; }
+                return false;
+            }
+        }
+        if (c == '[') {
+            out.type = value::kind::array;
+            ++i;
+            skip_space();
+            if (i < s.size() && s[i] == ']') { ++i; return true; }
+            for (;;) {
+                value v;
+                if (!parse_value(v)) return false;
+                out.items.push_back(std::move(v));
+                skip_space();
+                if (i < s.size() && s[i] == ',') { ++i; continue; }
+                if (i < s.size() && s[i] == ']') { ++i; return true; }
+                return false;
+            }
+        }
+        const std::size_t b = i;
+        while (i < s.size() && s[i] != ',' && s[i] != '}' && s[i] != ']' &&
+               s[i] != ' ' && s[i] != '\n' && s[i] != '\r' && s[i] != '\t') ++i;
+        out.text = std::string(s.substr(b, i - b));
+        if (out.text == "null") out.type = value::kind::null;
+        else if (out.text == "true" || out.text == "false") out.type = value::kind::boolean;
+        else out.type = value::kind::number;
+        return !out.text.empty();
+    }
+};
+
+// The whole text is one value, with nothing but white space after it.
+inline bool parse_json(std::string_view text, value& out) {
+    reader r{text};
+    if (!r.parse_value(out)) return false;
+    r.skip_space();
+    return r.i == r.s.size();
+}
+
+// A string member of an object, or empty when absent or not a string.
+inline std::string string_of(const value* v) {
+    return v && v->type == value::kind::string ? v->text : std::string();
+}
+
+} // namespace mcpp::plugins::json
+
+// mcpp::plugins::graph -- the resolved dependency graph the engine states.
+//
+// mcpp 2026.9.16.1 gives the ROOT project's build program `MCPP_GRAPH_FILE`
+// (`mcpp::graph_file()`), a document naming every package of the resolved graph,
+// dependencies before their requesters, each with its manifest directory and its
+// `[package.metadata]` verbatim (mcpp docs/30, "Reading the resolved graph"). A
+// member that merges what libraries contribute reads a table of its own out of
+// that metadata: `[package.metadata.dist-apk]`, `[package.metadata.dist-apple]`.
+//
+// READ THROUGH THE ENVIRONMENT, NOT `mcpp::graph_file()`. This unit does not
+// import `mcpp` (see the top of this file), and a member that called the
+// accessor would not compile against an engine older than the one that added it.
+// An unset or empty variable is an older engine, or a dependency's program, and
+// reads as a graph with no packages, which leaves every member's behaviour as it
+// was.
+export namespace mcpp::plugins::graph {
+
+struct package {
+    std::string canonical;      // `namespace.name@version`
+    std::string name;
+    std::string namespace_;
+    std::string version;
+    bool        root = false;
+    std::string manifest_dir;   // absolute
+    json::value metadata;       // the package's [package.metadata], an object
+};
+
+struct document {
+    bool                 present = false;   // MCPP_GRAPH_FILE named a file
+    std::string          path;
+    std::vector<package> packages;          // dependencies before requesters
+};
+
+// The graph this build program was given, or the reason it cannot be read. A
+// variable naming a file that is missing or not a `mcpp.graph` document is an
+// error rather than an empty graph: the engine promised a document, and reading
+// nothing would silently drop every contribution.
+inline std::expected<document, std::string> read() {
+    document d;
+    const char* env = std::getenv("MCPP_GRAPH_FILE");
+    if (!env || !*env) return d;
+    d.present = true;
+    d.path = env;
+    std::ifstream in(d.path, std::ios::binary);
+    if (!in)
+        return std::unexpected(std::format("the graph document {} cannot be read", d.path));
+    const std::string text((std::istreambuf_iterator<char>(in)), std::istreambuf_iterator<char>());
+    json::value doc;
+    if (!json::parse_json(text, doc) || doc.type != json::value::kind::object)
+        return std::unexpected(std::format("the graph document {} is not JSON", d.path));
+    if (json::string_of(doc.get("kind")) != "mcpp.graph")
+        return std::unexpected(std::format("the graph document {} is not a mcpp.graph document", d.path));
+    const json::value* list = doc.get("packages");
+    if (!list || list->type != json::value::kind::array)
+        return std::unexpected(std::format("the graph document {} has no packages array", d.path));
+    for (auto const& entry : list->items) {
+        if (entry.type != json::value::kind::object) continue;
+        package p;
+        if (const json::value* id = entry.get("package")) {
+            p.canonical  = json::string_of(id->get("canonical"));
+            p.name       = json::string_of(id->get("name"));
+            p.namespace_ = json::string_of(id->get("namespace"));
+            p.version    = json::string_of(id->get("version"));
+        }
+        if (const json::value* r = entry.get("root"))
+            p.root = r->type == json::value::kind::boolean && r->text == "true";
+        p.manifest_dir = json::string_of(entry.get("manifest_dir"));
+        if (const json::value* m = entry.get("metadata"); m && m->type == json::value::kind::object)
+            p.metadata = *m;
+        d.packages.push_back(std::move(p));
+    }
+    return d;
+}
+
+// The package's `[package.metadata.<tool>]` table, or null.
+inline const json::value* table_of(const package& p, std::string_view tool) {
+    const json::value* t = p.metadata.get(tool);
+    return t && t->type == json::value::kind::object ? t : nullptr;
+}
+
+// A path a package states, made absolute against its manifest directory.
+inline std::string resolve(const package& p, const std::string& path) {
+    if (path.empty() || std::filesystem::path(path).is_absolute()) return path;
+    return (std::filesystem::path(p.manifest_dir) / path).lexically_normal().string();
+}
+
+// How a diagnostic names a package: its canonical identity, or its name.
+inline std::string label_of(const package& p) {
+    return !p.canonical.empty() ? p.canonical : p.name;
+}
+
+} // namespace mcpp::plugins::graph
+
 // mcpp::plugins::names -- the derivations that turn a path into a C++ name.
 //
 // THESE ARE SHARED BECAUSE THEY WERE COPIED. `common_base_dir` and
diff --git a/tests/apk-consumer-graph/app-res/values/strings.xml b/tests/apk-consumer-graph/app-res/values/strings.xml
new file mode 100644
index 0000000..fe3481d
--- /dev/null
+++ b/tests/apk-consumer-graph/app-res/values/strings.xml
@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!-- An application's own library defining the resource the graph's library
+     defines, for the check that the application's entries rank above the graph's. -->
+<resources>
+    <string name="graph_contribution_marker">from-the-application</string>
+</resources>
diff --git a/tests/apk-consumer-graph/build.mcpp b/tests/apk-consumer-graph/build.mcpp
new file mode 100644
index 0000000..1e10db4
--- /dev/null
+++ b/tests/apk-consumer-graph/build.mcpp
@@ -0,0 +1,26 @@
+// dist-apk 0.12.0's graph contribution, with two configurations selected by the
+// environment check-apk-graph.sh sets:
+//
+//   APK_GRAPH_OFF  non-empty: `options::graph_libraries = false`
+//   APK_GRAPH_OWN  non-empty: an application library defining the same string
+//                  resource the graph's library defines
+import std;
+import mcpp;
+import mcpp.dist.apk;
+
+int main() {
+    for (const char* v : {"APK_GRAPH_OFF", "APK_GRAPH_OWN"}) mcpp::rerun_if_env_changed(v);
+    const auto set = [](const char* v) { const char* x = std::getenv(v); return x && *x; };
+
+    mcpp::dist::apk::options opt;
+    opt.target         = "apk-consumer-graph";
+    opt.application_id = "org.mcpp.apkgraph";
+    if (set("APK_GRAPH_OFF")) opt.graph_libraries = false;
+    if (set("APK_GRAPH_OWN")) {
+        mcpp::dist::apk::library own;
+        own.package   = "org.mcpp.apkgraph.own";
+        own.resources = "app-res";
+        opt.libraries = { own };
+    }
+    return mcpp::dist::apk::generate(opt) ? 0 : 1;
+}
diff --git a/tests/apk-consumer-graph/check-apk-graph.sh b/tests/apk-consumer-graph/check-apk-graph.sh
new file mode 100755
index 0000000..0579d25
--- /dev/null
+++ b/tests/apk-consumer-graph/check-apk-graph.sh
@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+# dist-apk collects library contributions from the resolved graph (0.12.0).
+#
+# `lib/` states `[package.metadata.dist-apk]` with its resources, and the
+# application names it only as a dependency. Criteria, by engine:
+#
+#   mcpp 2026.9.16.1 or newer (the root build program receives the graph):
+#     1. the library's string resource is in the APK with the library's value;
+#     2. `options::graph_libraries = false` packs no contribution;
+#     3. an application library defining the same resource wins it;
+#     4. a malformed contribution is refused, naming the package and the key.
+#   an older engine (no graph):
+#     5. the pack succeeds, and the APK carries no contribution.
+#
+# Usage: MCPP=<mcpp> ./check-apk-graph.sh   (run from this directory)
+set -eu
+
+MCPP="${MCPP:-mcpp}"
+TARGET=x86_64-linux-android
+fail() { echo "FAIL: $1"; shift; for f in "$@"; do echo "--- $f ---"; cat "$f" 2>/dev/null; done; exit 1; }
+packed() { sed -n 's/^ *Packed //p' "$1" | tail -1; }
+
+"$MCPP" self env > graph-env.log
+MCPP_HOME_DIR=$(awk -F'= *' '/^MCPP_HOME/{print $2; exit}' graph-env.log)
+[ -n "$MCPP_HOME_DIR" ] || fail "could not read MCPP_HOME" graph-env.log
+BT=$(find "$MCPP_HOME_DIR/registry/data/xpkgs/xim-x-android-build-tools" -mindepth 1 -maxdepth 1 -type d | head -1)
+AAPT2="$BT/aapt2"
+[ -x "$AAPT2" ] || fail "aapt2 not found under $BT" graph-env.log
+
+# marker_of <apk> : the value of string/graph_contribution_marker, or empty.
+marker_of() {
+    "$AAPT2" dump resources "$1" 2>/dev/null \
+        | awk '/string\/graph_contribution_marker$/ { getline; sub(/^ *\(\) "/, ""); sub(/"$/, ""); print; exit }'
+}
+
+pack() {  # pack <log>
+    rm -rf target
+    "$MCPP" pack --format apk --target "$TARGET" > "$1" 2>&1 || fail "mcpp pack failed" "$1"
+    local apk; apk=$(packed "$1")
+    [ -n "$apk" ] && [ -f "$apk" ] || fail "no APK reported" "$1"
+    echo "$apk"
+}
+
+engine=$("$MCPP" --version | awk '{print $2}')
+unset APK_GRAPH_OFF APK_GRAPH_OWN || true
+
+if [ "$(printf '%s\n%s\n' 2026.9.16.1 "$engine" | sort -V | head -1)" != 2026.9.16.1 ]; then
+    echo "== (5) $engine gives build programs no graph =="
+    apk=$(pack graph-old.log)
+    value=$(marker_of "$apk")
+    [ -z "$value" ] || fail "an engine without a graph packed a contribution ($value)" graph-old.log
+    echo "ok: the pack succeeds under $engine and carries no contribution"
+    rm -rf target graph-*.log
+    echo "PASS: dist-apk's graph contribution, older-engine leg ($engine)"
+    exit 0
+fi
+
+echo "== (1) the library's contribution reaches the APK =="
+apk=$(pack graph-1.log)
+value=$(marker_of "$apk")
+[ "$value" = "from-the-graph" ] || fail "the library's resource is not in the APK (got: '${value}')" graph-1.log
+echo "ok: string/graph_contribution_marker = from-the-graph"
+
+echo "== (2) options::graph_libraries = false =="
+export APK_GRAPH_OFF=1
+apk=$(pack graph-2.log)
+value=$(marker_of "$apk")
+[ -z "$value" ] || fail "graph_libraries = false still packed the contribution ($value)" graph-2.log
+unset APK_GRAPH_OFF
+echo "ok: no contribution is read"
+
+echo "== (3) the application's own library ranks above the graph's =="
+export APK_GRAPH_OWN=1
+apk=$(pack graph-3.log)
+value=$(marker_of "$apk")
+[ "$value" = "from-the-application" ] || fail "the graph's library won a resource the application's library defines (got: '${value}')" graph-3.log
+unset APK_GRAPH_OWN
+echo "ok: string/graph_contribution_marker = from-the-application"
+
+echo "== (4) a malformed contribution is refused, naming the package and the key =="
+COPY="../.apk-consumer-graph-malformed"
+rm -rf "$COPY"
+mkdir -p "$COPY"
+cp -r mcpp.toml build.mcpp src app-res lib "$COPY"/
+sed -i.bak 's/^resources = "res"$/resources = 3/' "$COPY/lib/mcpp.toml"
+grep -q '^resources = 3$' "$COPY/lib/mcpp.toml" || fail "the malformed copy was not written" "$COPY/lib/mcpp.toml"
+if ( cd "$COPY" && "$MCPP" pack --format apk --target "$TARGET" > refuse.log 2>&1 ); then
+    fail "a contribution stating resources = 3 was packed" "$COPY/refuse.log"
+fi
+grep -q 'mcpp.apk-graph-lib@0.1.0 states `resources` as something other than a path' "$COPY/refuse.log" \
+    || fail "the refusal does not name the package and the key" "$COPY/refuse.log"
+rm -rf "$COPY"
+echo "ok: the refusal names mcpp.apk-graph-lib@0.1.0 and resources"
+
+rm -rf target graph-*.log
+echo "PASS: dist-apk collects library contributions from the resolved graph ($engine)"
diff --git a/tests/apk-consumer-graph/lib/mcpp.toml b/tests/apk-consumer-graph/lib/mcpp.toml
new file mode 100644
index 0000000..0a2ea85
--- /dev/null
+++ b/tests/apk-consumer-graph/lib/mcpp.toml
@@ -0,0 +1,22 @@
+# The library of `tests/apk-consumer-graph`: it states what it contributes to an
+# APK in `[package.metadata.dist-apk]`, with paths relative to this directory.
+[package]
+name        = "apk-graph-lib"
+namespace   = "mcpp"
+version     = "0.1.0"
+description = "Fixture: a library that contributes Android resources through the graph"
+license     = "Apache-2.0"
+authors     = ["mcpp-community"]
+
+[package.metadata.dist-apk]
+package   = "org.mcpp.apkgraph.lib"
+resources = "res"
+
+[language]
+standard = "c++23"
+
+[targets.apk-graph-lib]
+kind = "lib"
+
+[build]
+sources = ["src/lib.cpp"]
diff --git a/tests/apk-consumer-graph/lib/res/values/strings.xml b/tests/apk-consumer-graph/lib/res/values/strings.xml
new file mode 100644
index 0000000..c453a7b
--- /dev/null
+++ b/tests/apk-consumer-graph/lib/res/values/strings.xml
@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <string name="graph_contribution_marker">from-the-graph</string>
+</resources>
diff --git a/tests/apk-consumer-graph/lib/src/lib.cpp b/tests/apk-consumer-graph/lib/src/lib.cpp
new file mode 100644
index 0000000..8abd954
--- /dev/null
+++ b/tests/apk-consumer-graph/lib/src/lib.cpp
@@ -0,0 +1 @@
+int apk_graph_lib_answer() { return 42; }
diff --git a/tests/apk-consumer-graph/mcpp.toml b/tests/apk-consumer-graph/mcpp.toml
new file mode 100644
index 0000000..e6df7b1
--- /dev/null
+++ b/tests/apk-consumer-graph/mcpp.toml
@@ -0,0 +1,34 @@
+# Fixture: an Android library that states its contribution in
+# `[package.metadata.dist-apk]`, and an application that names it only as a
+# dependency (dist-apk 0.12.0, mcpp 2026.9.16.1).
+#
+# `lib/` is a path dependency whose manifest names its resources directory. The
+# application's build program lists no library: with an engine that gives the
+# root program the resolved graph, `dist-apk` reads the contribution from it and
+# the library's string resource reaches the APK. With an older engine there is no
+# graph, and the package is built without the contribution, as before.
+[package]
+name        = "apk-consumer-graph"
+version     = "0.1.0"
+description = "Fixture: dist-apk collects a library contribution from the resolved graph"
+license     = "Apache-2.0"
+authors     = ["mcpp-community"]
+
+[language]
+standard = "c++23"
+
+[build-dependencies.mcpp]
+plugins = { path = "../..", features = ["dist-apk"], host-module = true }
+
+[dependencies]
+mcpp.apk-graph-lib = { path = "lib" }
+
+[targets.apk-consumer-graph]
+kind = "app"
+main = "src/main.cpp"
+
+[target.'cfg(env = "android")'.runtime]
+libraries = ["android", "log"]
+
+[target.x86_64-linux-android]
+min_api_level = 24
diff --git a/tests/apk-consumer-graph/src/main.cpp b/tests/apk-consumer-graph/src/main.cpp
new file mode 100644
index 0000000..6e14843
--- /dev/null
+++ b/tests/apk-consumer-graph/src/main.cpp
@@ -0,0 +1,16 @@
+#include <cstdio>
+
+#if defined(__ANDROID__)
+#include <android/native_activity.h>
+#endif
+
+int apk_graph_lib_answer();
+
+int main() { return apk_graph_lib_answer() == 42 ? 0 : 1; }
+
+#if defined(__ANDROID__)
+extern "C" void ANativeActivity_onCreate(ANativeActivity* activity, void*, size_t) {
+    std::printf("apk-consumer-graph %d\n", apk_graph_lib_answer());
+    ANativeActivity_finish(activity);
+}
+#endif
diff --git a/tests/ios-app-consumer/build.mcpp b/tests/ios-app-consumer/build.mcpp
index 8d90ec1..9a71cc7 100644
--- a/tests/ios-app-consumer/build.mcpp
+++ b/tests/ios-app-consumer/build.mcpp
@@ -26,7 +26,8 @@ int main() {
     // leave the options as they are, because the script passes every variable
     // to every row. The macOS runner's real pack names the first one too.
     for (const char* v : {"IOS_APP_CONSUMER_INFO_PLIST", "IOS_APP_CONSUMER_PROFILE",
-                          "IOS_APP_CONSUMER_NO_IDENTITY", "IOS_APP_CONSUMER_OMIT_KEYS"})
+                          "IOS_APP_CONSUMER_NO_IDENTITY", "IOS_APP_CONSUMER_OMIT_KEYS",
+                          "IOS_APP_CONSUMER_NO_GRAPH"})
         mcpp::rerun_if_env_changed(v);
     // 0.12.0: `options::omit_keys`, comma-separated in the variable.
     if (const char* v = std::getenv("IOS_APP_CONSUMER_OMIT_KEYS"); v && *v) {
@@ -42,5 +43,7 @@ int main() {
     if (const char* v = std::getenv("IOS_APP_CONSUMER_INFO_PLIST"); v && *v) opt.info_plist = v;
     if (const char* v = std::getenv("IOS_APP_CONSUMER_PROFILE"); v && *v) opt.provisioning_profile = v;
     if (const char* v = std::getenv("IOS_APP_CONSUMER_NO_IDENTITY"); v && *v) opt.identity.clear();
+    // 0.12.0: `options::graph_info_plist = false`.
+    if (const char* v = std::getenv("IOS_APP_CONSUMER_NO_GRAPH"); v && *v) opt.graph_info_plist = false;
     return mcpp::dist::apple::generate(opt) ? 0 : 1;
 }
diff --git a/tests/ios-app-consumer/check-ios-plan.sh b/tests/ios-app-consumer/check-ios-plan.sh
index 39ef243..d5992cc 100755
--- a/tests/ios-app-consumer/check-ios-plan.sh
+++ b/tests/ios-app-consumer/check-ios-plan.sh
@@ -123,6 +123,8 @@ run_row() {
         IOS_APP_CONSUMER_PROFILE="${IOS_APP_CONSUMER_PROFILE:-}" \
         IOS_APP_CONSUMER_NO_IDENTITY="${IOS_APP_CONSUMER_NO_IDENTITY:-}" \
         IOS_APP_CONSUMER_OMIT_KEYS="${IOS_APP_CONSUMER_OMIT_KEYS:-}" \
+        IOS_APP_CONSUMER_NO_GRAPH="${IOS_APP_CONSUMER_NO_GRAPH:-}" \
+        MCPP_GRAPH_FILE="${IOS_APP_CONSUMER_GRAPH_FILE:-}" \
         "$BIN" > "$log" 2>&1
     echo "$out"
 }
@@ -285,6 +287,95 @@ grep -q 'names UIDeviceFamily, and `options::info_plist`' /tmp/ios-plan-sim-omit
 unset IOS_APP_CONSUMER_OMIT_KEYS IOS_APP_CONSUMER_INFO_PLIST
 echo "ok: omitting a derived key, a key this member does not write, or a key info_plist sets is refused by name"
 
+# ── 0.12.0: Info.plist entries the graph contributes ────────────────────────
+#
+# The document the engine gives the root build program (mcpp 2026.9.16.1,
+# `MCPP_GRAPH_FILE`), written here for three packages below the application:
+# `example.graph-a` states graph-a.plist, `example.graph-b` depends on it and
+# states graph-b.plist, and the application states a table of its own, which the
+# member ignores because the application's entries are its own `info_plist`.
+write_graph() {  # write_graph <file> <path of b's fragment>
+    cat > "$1" <<G
+{"kind":"mcpp.graph","version":1,"packages":[
+ {"package":{"canonical":"example.graph-a@0.1.0","namespace":"example","name":"graph-a","version":"0.1.0","source":"path"},
+  "root":false,"requested_by":[],"manifest_dir":"$PWD/info-plist","features":[],"targets":[],
+  "metadata":{"dist-apple":{"info_plist":"graph-a.plist"}}},
+ {"package":{"canonical":"example.graph-b@0.1.0","namespace":"example","name":"graph-b","version":"0.1.0","source":"path"},
+  "root":false,"requested_by":[],"manifest_dir":"$PWD/info-plist","features":[],"targets":[],
+  "metadata":{"dist-apple":{"info_plist":"$2"}}},
+ {"package":{"canonical":"mcpplibs.ios-app-consumer@0.3.0","namespace":"mcpplibs","name":"ios-app-consumer","version":"0.3.0","source":"path"},
+  "root":true,"requested_by":[],"manifest_dir":"$PWD","features":[],"targets":[],
+  "metadata":{"dist-apple":{"info_plist":"info-plist/derived.plist"}}}
+]}
+G
+}
+GRAPH=$(mktemp)
+export IOS_APP_CONSUMER_GRAPH_FILE="$GRAPH"
+
+echo "== 0.12.0: the graph's Info.plist entries, dependencies first =="
+write_graph "$GRAPH" graph-b.plist
+outdir=$(run_row simgraph ios sim /tmp/ios-plan-sim-graph.log)
+plist="$outdir/IosAppConsumer-Info.plist"
+[ -f "$plist" ] || fail "no Info.plist written with a graph document" /tmp/ios-plan-sim-graph.log
+python3 - "$plist" <<'PY2' || fail "the graph's entries are not merged in the graph's order" "$plist"
+import plistlib, sys
+d = plistlib.load(open(sys.argv[1], "rb"))
+assert d["NSLocationWhenInUseUsageDescription"] == "from A", d
+assert d["NSMicrophoneUsageDescription"] == "from B", d
+assert d["NSCameraUsageDescription"] == "from B", d
+assert d["UIDeviceFamily"] == [2], d["UIDeviceFamily"]
+assert d["CFBundleName"] != "NotTheApplication", d
+PY2
+[ "$(grep -c '<key>UIDeviceFamily</key>' "$plist")" -eq 1 ] || fail "a contributed default is stated more than once" "$plist"
+check_terminal_bundle /tmp/ios-plan-sim-graph.log
+echo "ok: a package's entry overrides the package it depends on, a contributed default replaces the member's, and the application's own table is not read as a contribution"
+
+echo "== 0.12.0: the application's own entries win, and omit_keys applies to contributions =="
+export IOS_APP_CONSUMER_INFO_PLIST="$PWD/info-plist/usage.plist"
+outdir=$(run_row simgraphown ios sim /tmp/ios-plan-sim-graph-own.log)
+plist="$outdir/IosAppConsumer-Info.plist"
+python3 - "$plist" <<'PY2' || fail "the application's own entries do not win over the graph's" "$plist"
+import plistlib, sys
+d = plistlib.load(open(sys.argv[1], "rb"))
+assert d["NSCameraUsageDescription"].startswith("Scans"), d
+assert d["UIDeviceFamily"] == [1], d["UIDeviceFamily"]
+assert d["NSMicrophoneUsageDescription"] == "from B", d
+PY2
+unset IOS_APP_CONSUMER_INFO_PLIST
+export IOS_APP_CONSUMER_OMIT_KEYS="UIDeviceFamily"
+outdir=$(run_row simgraphomit ios sim /tmp/ios-plan-sim-graph-omit.log)
+plist="$outdir/IosAppConsumer-Info.plist"
+[ -f "$plist" ] || fail "omitting a key a contribution states was refused" /tmp/ios-plan-sim-graph-omit.log
+grep -q '<key>UIDeviceFamily</key>' "$plist" && fail "a key the application omits was written from a contribution" "$plist"
+unset IOS_APP_CONSUMER_OMIT_KEYS
+echo "ok: the application's info_plist wins every key, and a key it omits is left out whoever contributes it"
+
+echo "== 0.12.0: options::graph_info_plist = false reads no contribution =="
+export IOS_APP_CONSUMER_NO_GRAPH=1
+outdir=$(run_row simnograph ios sim /tmp/ios-plan-sim-nograph.log)
+plist="$outdir/IosAppConsumer-Info.plist"
+grep -q 'NSLocationWhenInUseUsageDescription' "$plist" && fail "graph_info_plist = false still merged a contribution" "$plist"
+unset IOS_APP_CONSUMER_NO_GRAPH
+echo "ok: no contribution is read"
+
+echo "== 0.12.0: a contribution may not state a derived key, and the refusal names the package =="
+write_graph "$GRAPH" graph-derived.plist
+run_row simgraphderived ios sim /tmp/ios-plan-sim-graph-derived.log > /dev/null
+grep -q 'the \[package.metadata.dist-apple\] of example.graph-b@0.1.0 (.*graph-derived.plist) sets CFBundleName, which this member derives' /tmp/ios-plan-sim-graph-derived.log \
+    || fail "a contributed derived key was not refused naming the package" /tmp/ios-plan-sim-graph-derived.log
+grep -q 'mcpp.dist.apple.layout' /tmp/ios-plan-sim-graph-derived.log \
+    && fail "steps were planned although a contribution was refused" /tmp/ios-plan-sim-graph-derived.log
+echo "ok: the refusal names example.graph-b@0.1.0 and CFBundleName"
+
+echo "== 0.12.0: a graph document that cannot be read is refused =="
+export IOS_APP_CONSUMER_GRAPH_FILE="$GRAPH.missing"
+run_row simgraphmissing ios sim /tmp/ios-plan-sim-graph-missing.log > /dev/null
+grep -q 'cannot be read' /tmp/ios-plan-sim-graph-missing.log \
+    || fail "a graph document that does not exist was not refused" /tmp/ios-plan-sim-graph-missing.log
+unset IOS_APP_CONSUMER_GRAPH_FILE
+rm -f "$GRAPH"
+echo "ok: a named graph document that cannot be read is refused rather than read as no contributions"
+
 # A provisioning profile is a CMS-signed plist; the member reads the plist from
 # between its markers, so a plan needs only those bytes framed by binary data.
 make_profile() {  # make_profile <file> <application-identifier>
diff --git a/tests/ios-app-consumer/info-plist/graph-a.plist b/tests/ios-app-consumer/info-plist/graph-a.plist
new file mode 100644
index 0000000..464c5ee
--- /dev/null
+++ b/tests/ios-app-consumer/info-plist/graph-a.plist
@@ -0,0 +1,16 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <!-- A lower library's contribution (dist-apple 0.12.0): the package that
+         depends on it overrides the microphone description. -->
+    <key>NSLocationWhenInUseUsageDescription</key>
+    <string>from A</string>
+    <key>NSMicrophoneUsageDescription</key>
+    <string>from A</string>
+    <key>UIDeviceFamily</key>
+    <array>
+        <integer>2</integer>
+    </array>
+</dict>
+</plist>
diff --git a/tests/ios-app-consumer/info-plist/graph-b.plist b/tests/ios-app-consumer/info-plist/graph-b.plist
new file mode 100644
index 0000000..6b898b4
--- /dev/null
+++ b/tests/ios-app-consumer/info-plist/graph-b.plist
@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <!-- A library above graph-a.plist's package. -->
+    <key>NSMicrophoneUsageDescription</key>
+    <string>from B</string>
+    <key>NSCameraUsageDescription</key>
+    <string>from B</string>
+</dict>
+</plist>
diff --git a/tests/ios-app-consumer/info-plist/graph-derived.plist b/tests/ios-app-consumer/info-plist/graph-derived.plist
new file mode 100644
index 0000000..d7f8ef9
--- /dev/null
+++ b/tests/ios-app-consumer/info-plist/graph-derived.plist
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <!-- A key dist-apple derives, which no contribution may state. -->
+    <key>CFBundleName</key>
+    <string>NotTheApplication</string>
+</dict>
+</plist>

From 734bf9a02569f2f0367efd8b38ac088c00e82b36 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Wed, 16 Sep 2026 07:06:01 +0800
Subject: [PATCH 07/10] dist-apk packs the libraries the engine staged as
 staged, and says so when keep_debug_symbols cannot restore them (#649 E5)

---
 README.md                                |  2 +-
 dist/apk.cppm                            | 29 ++++++++++++++++---
 tests/apk-consumer/check-apk-features.sh | 36 ++++++++++++++++++------
 3 files changed, 53 insertions(+), 14 deletions(-)

diff --git a/README.md b/README.md
index 6d2b553..d71756f 100644
--- a/README.md
+++ b/README.md
@@ -77,7 +77,7 @@ engine's own module family and is not used here.
 | `dist-wix` | `mcpp.dist.wix` | 2026.9.11.1 | `xim:wix` 5.0.2-1, which this feature declares on the Windows target axis; the .NET 6 runtime the tool needs is a Windows component the payload does not carry, and `wix --version` names it when it is missing. Windows only. `--format msi` renders a `.wxs` and passes the program in as a preprocessor variable, because a bind path that resolves to nothing is silent. From 0.10.0 `--format setup` is a Burn bundle chaining that MSI, with WiX's stock bootstrapper application (`bal:WixStandardBootstrapperApplication`, theme `hyperlinkLicense`, `options::license_url` its link) loaded through the `WixToolset.BootstrapperApplications.wixext` extension the 5.0.2-1 payload carries (`options::extension` names another). The bundle is written as `<product_name>-<arch>.exe` beside the MSI, with an UpgradeCode of its own, and `options::bundle_output` naming `setup.exe` is refused before `wix` runs, because `wix` refuses that name (WIX0388). A project with its own bootstrapper application supplies `options::bundle_wxs`, which receives the MSI as `$(Msi)`. From 0.10.1 the MSI installs the staged tree, not the program alone: every file `mcpp pack` stages beside the program (a deployed file, a resolved DLL) is named file by file in a `StagedFiles` component group written beside the definition -- enumerated while the tree exists, never harvested from a directory -- placed at its staged path under `INSTALLFOLDER`, and declared an input of the action; the generated definition references the group, and a project's own `options::wxs` installs it with `<ComponentGroupRef Id="StagedFiles" />`. `options::inputs` and `options::bundle_inputs` declare the files a project's own definitions name beyond that (an icon, a bootstrapper application and its payloads). CI builds the bundle on `windows-2022` and compares the MSI `wix burn extract` takes out of it with the one the first action wrote, and installs the MSI administratively and compares both the program and a deployed file |
 | `dist-apple` | `mcpp.dist.apple` | 2026.9.14.2 (0.10.0); 2026.9.11.2 (macOS) and 2026.9.12.3 (iOS) before it | the base macOS install (`ditto`, `codesign`, `hdiutil`), and `xim:macapp-run` for `mcpp run` on macOS, which this feature declares with `when = "run"`. macOS: `Contents/`-shaped, as always. iOS (`aarch64-ios-sim`, `aarch64-ios`): a flat bundle at the same call site -- no separate feature, no separate module -- with `MinimumOSVersion` from `mcpp::min_platform_version()` (#622 A11), `CFBundleSupportedPlatforms` read from `env == "sim"`, `UIDeviceFamily`, `LSRequiresIPhoneOS`, and a directory of flat PNGs listed under `CFBundleIcons` in place of macOS's single `.icns` file. Signing is skipped on the simulator row (`options::identity` is ignored, with a `mcpp::warning` naming why), and the device row signs only with an identity. The iOS row is measured end to end on `macos-15`: a real `mcpp build`, `mcpp pack --format app` and `mcpp run` against `aarch64-ios-sim`, through `xim:apple-simulator-tools`' `simctl-run`. **The macOS floor is one release higher than its siblings** and the reason is not this member: under 2026.9.11.1 `mcpp pack` staged before dispatching and let a staging failure fail the command, so on a Mach-O program -- which the built-in closure walk refuses, because it uses `LD_TRACE_LOADED_OBJECTS` and dyld answers that by running the program -- every dispatched format was unreachable, including one that reads no staged tree. 2026.9.11.2 makes staging a service to the provider. From 0.9.2 the staged tree's deployed files (`bin/<to>/...`, which the engine stages for a Mach-O program before the closure walk since the release for mcpp#630) land at the bundle's resource destination -- `Contents/Resources/<to>/...` on macOS, the bundle root on iOS -- and the launcher alone goes to the executable directory, so `CFBundleExecutable` names a file that is where it says. The iOS fixture declares `llvm.libcxx` and `llvm.compiler-rt-builtins` under `cfg(os = "ios")`, which is what an application that imports `std` on those rows declares. From 0.10.0, with mcpp 2026.9.14.2: the dylibs the engine stages beside a Mach-O program, which the stage manifest's `needs` lines name, go to `Contents/Frameworks/` (`Frameworks/` on iOS) and not to the resources; the program is linked with the rpath that finds them there (`@executable_path/../Frameworks`, `@executable_path/Frameworks` on iOS) through `mcpp::link_flag`, so no file is edited after the link; a macOS bundle without `options::identity` is signed ad hoc, frameworks first and the bundle second, which `codesign --verify --deep --strict` requires of a bundle that carries a framework; an incomplete closure is a `mcpp::warning` naming the unresolved libraries; every refusal is a `mcpp::warning` as well, because the engine discards a build program's output when it exits 0. On macOS the member supplies the runner named `app` (`macapp-run`), so `mcpp run --format app` runs the bundle's executable in the foreground and returns its status with no runner in the manifest; a manifest runner of that name wins. `--format dmg` stages the bundle beside an `Applications` link and writes a UDZO image with `hdiutil create` (`options::volume_name`, `options::dmg`); it is refused on iOS. An engine below 2026.9.14.2 stages no `needs` lines, so the bundle carries no framework, anchors the rpath to the package directory, and hands the bundle directory to the kernel under `mcpp run --format app` unless `--runner app` is typed. CI measures the bundle on `macos-15`: the load command, the signature, the program with and without its framework (exit 7, then "Library not loaded"), `mcpp run --format app` with and without `--runner app`, and `hdiutil verify` and an attached image. From 0.11.0: a project's own Info.plist entries (`options::info_plist`), an iOS device bundle's provisioning profile (`options::provisioning_profile`), and `devicectl-run` (`xim:apple-device-tools`) as the device row's runner named `app` -- see [`dist-apple`: a project's Info.plist, and an iOS device](#dist-apple-a-projects-infoplist-and-an-ios-device). From 0.12.0 `options::omit_keys` leaves out a key the member only defaults -- see [`dist-apple`: a project's Info.plist, and an iOS device](#dist-apple-a-projects-infoplist-and-an-ios-device). From 0.12.0 a package in the resolved graph contributes Info.plist entries through `[package.metadata.dist-apple]`, applied before the application's own |
 | `dist-web` | `mcpp.dist.web` | 2026.9.13.1, the release that carries `${mcpp.self}` and `mcpp stage`'s argument shape as an engine contract (`stage --verify content --output <dst> <src>`) -- what lets this member's copy run on every host mcpp does, Windows included, in place of the `cp` this member used through 0.8.0 | nothing beyond mcpp: `wasm32-emscripten` only. Copies `${mcpp.stage_dir}/bin/` -- the `.js` launcher, the implicit `.wasm`, the `.data` when present, and every `mcpp::deploy`'d file, all of which #622 A5 and A4 already stage there -- to `<out_dir>/web/`, dropping the `bin/` prefix a browser has no use for, and writes an `index.html` rendered from a project template or a built-in default that loads the script with a plain `<script src>`. Each staged file and the rendered page are copied with `${mcpp.self} stage --verify content --output <dst> <src>`, the same copier every `stage_file` edge in `build.ninja` already runs -- no host-specific copy tool, no plan-time `create_directories` (`stage` creates the destination's parent), and a second `mcpp pack --format web` with nothing changed copies nothing. From 0.12.0 `options::page` names the page (`index.html` by default), for a project whose other build names it after the target; a name that is not a bare `*.html` file name is refused at plan time |
-| `dist-apk` | `mcpp.dist.apk` | 2026.9.14.2 from 0.10.0, which stages the closure this member reads; before it 2026.9.13.1, raised alongside `dist-web` in the same 0.9.0 release: this member's own manifest-template and Java-array changes ask nothing new of the engine, but this collection publishes one package at one version, and this is the release CI verifies it under from here on | `xim:android-build-tools`, `xim:android-platform` (versioned by API level, read back for `targetSdkVersion`), `xim:jdk-temurin` (`javac`/`jar`/`jarsigner`; `android-build-tools`' own runtime dependency provisions a JDK for its OWN wrappers only), `xim:android-debug-keystore`, `xim:bundletool` (0.10.0, for `--format aab`), all on the `cfg(env = "android")` axis. Generates `AndroidManifest.xml` and signs with the published Android debug key by default. Level 0 needs no Java (`hasCode="false"`, `android.app.NativeActivity`); `options::java_sources` adds `javac` + `d8` and a real `<activity>`. `options::manifest_template` renders a project manifest with six tokens substituted verbatim; `{{application_id}}` and `{{activity}}` are required always and `{{lib_name}}` at level 0, each refused by name at plan time when missing (naming `assets/mcpp-run.json`, which `adb-run` reads them from too) or when the template names an unknown token; empty renders 0.8.0's manifest byte-identically. From 0.9.3 the manifest template gains `{{version_name}}` / `{{version_code}}` (the package version, and `major * 1000000 + minor * 1000 + patch`). `options::resources` is a project's own `res/`, linked as the application's base resources from 0.9.1 (0.9.0 linked it as an aapt2 overlay, which refuses every resource the base does not already define -- a launcher icon could not be supplied). `options::java_sources` is an array: one `javac` over every root's `.java` files and one `d8` over the result, so a project's own sources and a path dependency's join without being merged into one directory first, and `rerun_if_changed_glob` is declared only for a root under `mcpp::manifest_dir()` -- a dependency root's files are already inputs of the `javac` action and its version is already in the build's fingerprint. Android only -- an `app` target is a shared object on this row (#622 A3). From 0.10.0, with mcpp 2026.9.14.2, the member reads the native closure the engine stages -- the application object, the graph's shared libraries and `libc++_shared.so` under `lib/` for one `--target`, `lib/<abi>/` for several -- and packs every ABI the tree carries into one APK; its own `NEEDED` walk and the stamp that lost a dependency's library on a second pack are gone. A stage manifest without `needs` lines comes from an engine below 2026.9.14.2 and is refused naming that floor, as is an incomplete closure, naming the unresolved libraries; every refusal is also a `mcpp::warning`, because the engine discards a build program's output when it exits 0. `--format aab` shares every step but the last three: `aapt2 link --proto-format` (with `--version-code` / `--version-name`, which bundletool requires), a base module in the layout bundletool reads, `bundletool build-bundle` from `xim:bundletool` (declared on the same axis), and `jarsigner` with the same keystore. CI packages both level 0 and level 1 and checks the archive (`mcpp::deploy`'d files under `assets/`), and on `tests/apk-consumer-shared` two packs in a row, a two-ABI APK (`aapt2` reports both, `apksigner` verifies it), an App Bundle (`bundletool validate`, `jarsigner -verify`, a universal APK from `bundletool build-apks`), a refusal's reason in `mcpp pack`'s output, and the floor refusal; the runner has no emulator or device, so the two rows that actually run were measured locally on 2026-09-12, through `adb-run`, against a KVM-accelerated x86_64 emulator and a physical arm64-v8a phone, both printing `1-2-3` and exiting 0. From 0.11.0: Kotlin sources (`dist-apk-kotlin`, which declares `xim:kotlin`), R classes, Android libraries from source, local AARs and JARs, a Maven graph through a lock file (`dist-apk-maven`, which declares `xim:coursier`), a manifest merge, and an unsigned package -- see [`dist-apk`: Kotlin, libraries and a Maven graph](#dist-apk-kotlin-libraries-and-a-maven-graph). From 0.11.1 the native libraries are packed as the Android Gradle plugin packs them: each is stripped with the build's own `llvm-strip --strip-unneeded` (the NDK's, beside the compiler `mcpp::toolchain_dir()` reports; `options::keep_debug_symbols` packs them as staged), and a manifest stating `android:extractNativeLibs="false"` gets them stored uncompressed on a 16 KB page, which loading them from the APK in place requires; CI checks both, and the symbol table `keep_debug_symbols` keeps. From 0.12.0 the engine's strip decision governs these libraries as well: under mcpp 2026.9.16.1, which publishes it to build programs as `MCPP_PACK_STRIP` and `MCPP_PACK_DEBUG_SYMBOLS_DIR`, `mcpp pack --no-strip` packs them as staged and `--debug-symbols <dir>` separates each library's debug information into `<dir>/<abi>/<library>.debug` with `llvm-objcopy` before stripping it and linking the packed copy to that file (`.gnu_debuglink`); a library is stripped unless either `keep_debug_symbols` or the engine says to keep it, and under an older engine, which publishes neither variable, the member strips as before. From 0.12.0 a library in the resolved graph contributes libraries and archives through `[package.metadata.dist-apk]`, ranked below the application's own -- see [A library states its contribution](#a-library-states-its-contribution-packagemetadatadist-apk) |
+| `dist-apk` | `mcpp.dist.apk` | 2026.9.14.2 from 0.10.0, which stages the closure this member reads; before it 2026.9.13.1, raised alongside `dist-web` in the same 0.9.0 release: this member's own manifest-template and Java-array changes ask nothing new of the engine, but this collection publishes one package at one version, and this is the release CI verifies it under from here on | `xim:android-build-tools`, `xim:android-platform` (versioned by API level, read back for `targetSdkVersion`), `xim:jdk-temurin` (`javac`/`jar`/`jarsigner`; `android-build-tools`' own runtime dependency provisions a JDK for its OWN wrappers only), `xim:android-debug-keystore`, `xim:bundletool` (0.10.0, for `--format aab`), all on the `cfg(env = "android")` axis. Generates `AndroidManifest.xml` and signs with the published Android debug key by default. Level 0 needs no Java (`hasCode="false"`, `android.app.NativeActivity`); `options::java_sources` adds `javac` + `d8` and a real `<activity>`. `options::manifest_template` renders a project manifest with six tokens substituted verbatim; `{{application_id}}` and `{{activity}}` are required always and `{{lib_name}}` at level 0, each refused by name at plan time when missing (naming `assets/mcpp-run.json`, which `adb-run` reads them from too) or when the template names an unknown token; empty renders 0.8.0's manifest byte-identically. From 0.9.3 the manifest template gains `{{version_name}}` / `{{version_code}}` (the package version, and `major * 1000000 + minor * 1000 + patch`). `options::resources` is a project's own `res/`, linked as the application's base resources from 0.9.1 (0.9.0 linked it as an aapt2 overlay, which refuses every resource the base does not already define -- a launcher icon could not be supplied). `options::java_sources` is an array: one `javac` over every root's `.java` files and one `d8` over the result, so a project's own sources and a path dependency's join without being merged into one directory first, and `rerun_if_changed_glob` is declared only for a root under `mcpp::manifest_dir()` -- a dependency root's files are already inputs of the `javac` action and its version is already in the build's fingerprint. Android only -- an `app` target is a shared object on this row (#622 A3). From 0.10.0, with mcpp 2026.9.14.2, the member reads the native closure the engine stages -- the application object, the graph's shared libraries and `libc++_shared.so` under `lib/` for one `--target`, `lib/<abi>/` for several -- and packs every ABI the tree carries into one APK; its own `NEEDED` walk and the stamp that lost a dependency's library on a second pack are gone. A stage manifest without `needs` lines comes from an engine below 2026.9.14.2 and is refused naming that floor, as is an incomplete closure, naming the unresolved libraries; every refusal is also a `mcpp::warning`, because the engine discards a build program's output when it exits 0. `--format aab` shares every step but the last three: `aapt2 link --proto-format` (with `--version-code` / `--version-name`, which bundletool requires), a base module in the layout bundletool reads, `bundletool build-bundle` from `xim:bundletool` (declared on the same axis), and `jarsigner` with the same keystore. CI packages both level 0 and level 1 and checks the archive (`mcpp::deploy`'d files under `assets/`), and on `tests/apk-consumer-shared` two packs in a row, a two-ABI APK (`aapt2` reports both, `apksigner` verifies it), an App Bundle (`bundletool validate`, `jarsigner -verify`, a universal APK from `bundletool build-apks`), a refusal's reason in `mcpp pack`'s output, and the floor refusal; the runner has no emulator or device, so the two rows that actually run were measured locally on 2026-09-12, through `adb-run`, against a KVM-accelerated x86_64 emulator and a physical arm64-v8a phone, both printing `1-2-3` and exiting 0. From 0.11.0: Kotlin sources (`dist-apk-kotlin`, which declares `xim:kotlin`), R classes, Android libraries from source, local AARs and JARs, a Maven graph through a lock file (`dist-apk-maven`, which declares `xim:coursier`), a manifest merge, and an unsigned package -- see [`dist-apk`: Kotlin, libraries and a Maven graph](#dist-apk-kotlin-libraries-and-a-maven-graph). From 0.11.1 the native libraries are packed as the Android Gradle plugin packs them: each is stripped with the build's own `llvm-strip --strip-unneeded` (the NDK's, beside the compiler `mcpp::toolchain_dir()` reports; `options::keep_debug_symbols` packs them as staged), and a manifest stating `android:extractNativeLibs="false"` gets them stored uncompressed on a 16 KB page, which loading them from the APK in place requires; CI checks both, and the symbol table `keep_debug_symbols` keeps. From 0.12.0 the engine's strip decision governs these libraries as well: under mcpp 2026.9.16.1, which publishes it to build programs as `MCPP_PACK_STRIP` and `MCPP_PACK_DEBUG_SYMBOLS_DIR`, that engine strips and separates the libraries it stages itself and the member packs them as staged, while the libraries the engine did not stage -- an archive's `jni/` libraries -- follow the same decision inside the member: `--no-strip` packs them as they are, and `--debug-symbols <dir>` separates each one's debug information into `<dir>/<abi>/<library>.debug` with `llvm-objcopy` before stripping it and linking the packed copy to that file (`.gnu_debuglink`). A library is stripped unless either `keep_debug_symbols` or the engine says to keep it, and under an older engine, which publishes neither variable, the member strips every library as before. Because that engine strips before the member reads the tree, `keep_debug_symbols` keeps only the member's own strip off and `--no-strip` is what ships the symbols of the libraries the graph built; the member warns when the option is set and the engine stripped. From 0.12.0 a library in the resolved graph contributes libraries and archives through `[package.metadata.dist-apk]`, ranked below the application's own -- see [A library states its contribution](#a-library-states-its-contribution-packagemetadatadist-apk) |
 
 ### Each rule brings its own environment
 
diff --git a/dist/apk.cppm b/dist/apk.cppm
index 3e7b26b..9e26706 100644
--- a/dist/apk.cppm
+++ b/dist/apk.cppm
@@ -231,6 +231,12 @@ struct options {
     // reach the ones the engine stages. A library is stripped unless either
     // this option or the engine says to keep it. An older engine publishes
     // neither variable, and the member strips as before.
+    //
+    // THE ENGINE STRIPS FIRST. That engine strips the libraries the graph built
+    // when it stages them, before this member reads the tree, so this option
+    // keeps this member's own strip off and cannot restore what the engine
+    // removed: `mcpp pack --no-strip` is what ships the symbols. With this
+    // option set and the engine stripping, the member says so.
     bool keep_debug_symbols = false;
 
     // LEVEL 1, KOTLIN (0.11.0). One or more directories of `.kt` sources,
@@ -2015,6 +2021,11 @@ inline plan plan_for(options opt = {}) {
     // `options::keep_debug_symbols`.
     const char* engineStrip = std::getenv("MCPP_PACK_STRIP");
     const bool engineKeeps = engineStrip && std::string_view(engineStrip) == "0";
+    if (opt.keep_debug_symbols && engineStrip && std::string_view(engineStrip) == "1") {
+        mcpp::warning("mcpp.dist.apk: options::keep_debug_symbols is set, and the engine stripped "
+                      "the libraries it staged before this member read them; pass "
+                      "`mcpp pack --no-strip` to ship their symbols.");
+    }
     const char* engineDebugDir = std::getenv("MCPP_PACK_DEBUG_SYMBOLS_DIR");
     const std::string debugDir = engineDebugDir ? engineDebugDir : "";
 
@@ -2069,9 +2080,19 @@ inline plan plan_for(options opt = {}) {
         char magic[4] = {};
         return in.read(magic, 4) && magic[0] == 0x7f && magic[1] == 'E' && magic[2] == 'L' && magic[3] == 'F';
     };
-    const auto place_library = [&](const std::string& so, const std::string& abi) {
+    // A LIBRARY THE ENGINE STAGED IS ALREADY WHAT THE ENGINE DECIDED. An engine
+    // that publishes its strip decision (`MCPP_PACK_STRIP` is set) has stripped
+    // those libraries, and separated their debug information into
+    // `--debug-symbols`, before this member reads the tree; stripping them again
+    // finds no debug information, writes an empty `.debug` file and points the
+    // packed copy at it (measured with mcpp 2026.9.16.1). They are packed as
+    // staged. The member's own strip applies to what the engine did not stage --
+    // an archive's native libraries -- and to every library under an older
+    // engine, which decides nothing.
+    const bool engineDecided = engineStrip && *engineStrip;
+    const auto place_library = [&](const std::string& so, const std::string& abi, bool staged) {
         const fs::path dst = work / "lib" / abi / fs::path(so).filename();
-        if (llvmStrip.empty()) {
+        if (llvmStrip.empty() || (staged && engineDecided)) {
             collect_tree(so, dst, libInputs);
             return;
         }
@@ -2123,7 +2144,7 @@ inline plan plan_for(options opt = {}) {
     };
     for (auto const& leg : legs)
         for (auto const& so : leg.libraries)
-            place_library(so, leg.abi);
+            place_library(so, leg.abi, /*staged=*/true);
 
     // An AAR's native libraries, for every ABI this package carries.
     for (auto const& c : contributions) {
@@ -2137,7 +2158,7 @@ inline plan plan_for(options opt = {}) {
                 continue;
             }
             for (auto const& so : shared_objects_in(abiDir))
-                place_library(so, leg.abi);
+                place_library(so, leg.abi, /*staged=*/false);
         }
     }
 
diff --git a/tests/apk-consumer/check-apk-features.sh b/tests/apk-consumer/check-apk-features.sh
index 86f718b..b87eabd 100755
--- a/tests/apk-consumer/check-apk-features.sh
+++ b/tests/apk-consumer/check-apk-features.sh
@@ -297,9 +297,24 @@ unset APK_CONSUMER_TEMPLATE
 echo "ok: the library is stripped, compressed by default, and stored on a 16 KB page when loaded in place"
 
 echo "== (l) keep_debug_symbols =="
+# From mcpp 2026.9.16.1 the engine strips the staged libraries before this member
+# reads them, so the symbols reach the package only with `--no-strip`; the
+# member warns when the option is set and the engine stripped. An older engine
+# stages the library as linked, and the option alone keeps its symbols.
+engine_version=$("$MCPP" --version | awk '{print $2}')
+engine_strips=no
+[ "$(printf '%s\n%s\n' 2026.9.16.1 "$engine_version" | sort -V | head -1)" = 2026.9.16.1 ] && engine_strips=yes
 rm -rf target k
 export APK_CONSUMER_KEEP_DEBUG_SYMBOLS=1
-"$MCPP" pack --format apk --target "$TARGET" > pack-l.log 2>&1 || fail "pack failed" pack-l.log
+if [ "$engine_strips" = yes ]; then
+    "$MCPP" pack --format apk --target "$TARGET" > pack-l0.log 2>&1 || fail "pack failed" pack-l0.log
+    grep -q 'keep_debug_symbols is set, and the engine stripped' pack-l0.log \
+        || fail "keep_debug_symbols under a stripping engine did not say the engine stripped" pack-l0.log
+    rm -rf target
+    "$MCPP" pack --format apk --target "$TARGET" --no-strip > pack-l.log 2>&1 || fail "pack failed" pack-l.log
+else
+    "$MCPP" pack --format apk --target "$TARGET" > pack-l.log 2>&1 || fail "pack failed" pack-l.log
+fi
 APK=$(find target -name 'apk-consumer.apk' | head -1)
 [ -n "$APK" ] || fail "no apk-consumer.apk" pack-l.log
 mkdir -p k && unzip -q -o "$APK" "$LIB" -d k
@@ -311,16 +326,18 @@ echo "ok: keep_debug_symbols packs the library with its symbol table"
 
 # ── (m),(n) 0.12.0: the engine's strip decision reaches the packed libraries ─
 #
-# An engine that strips what the graph built (mcpp 2026.9.16.1) publishes its
-# decision to the build program, so (m) `mcpp pack --no-strip` packs the library
-# with its symbol table, and (n) `--debug-symbols <dir>` separates its debug
-# information into `<dir>/<abi>/<library>.debug` and leaves a `.gnu_debuglink`
-# in the packed copy. An older engine publishes nothing, so these legs are
-# skipped there; (k) is the behaviour that engine keeps.
+# An engine that strips what the graph built (mcpp 2026.9.16.1) strips the
+# staged library itself and publishes its decision to the build program, which
+# packs that library as staged: (m) `mcpp pack --no-strip` packs it with its
+# symbol table, and (n) `--debug-symbols <dir>` gives a packed copy with no debug
+# information whose `.gnu_debuglink` names the file the engine wrote,
+# `<dir>/<library>.debug`, which carries it. An older engine publishes nothing,
+# so these legs are skipped there; (k) is the behaviour that engine keeps.
 engine_version=$("$MCPP" --version | awk '{print $2}')
 if [ "$(printf '%s\n%s\n' 2026.9.16.1 "$engine_version" | sort -V | head -1)" = 2026.9.16.1 ]; then
     echo "== (m) mcpp pack --no-strip =="
     rm -rf target k
+    unset APK_CONSUMER_KEEP_DEBUG_SYMBOLS || true
     "$MCPP" pack --format apk --target "$TARGET" --no-strip > pack-m.log 2>&1 || fail "pack --no-strip failed" pack-m.log
     APK=$(find target -name 'apk-consumer.apk' | head -1)
     [ -n "$APK" ] || fail "no apk-consumer.apk" pack-m.log
@@ -341,12 +358,13 @@ if [ "$(printf '%s\n%s\n' 2026.9.16.1 "$engine_version" | sort -V | head -1)" =
     readelf -S "k/$LIB" > sections-n.log
     if grep -qE '\.symtab|\.debug_' sections-n.log; then fail "the packed library keeps its symbol table or debug information" sections-n.log; fi
     grep -q '\.gnu_debuglink' sections-n.log || fail "the packed library does not name its debug file" sections-n.log
-    DEBUG_FILE="$DEBUG_DIR/x86_64/libapk-consumer.so.debug"
+    DEBUG_FILE="$DEBUG_DIR/libapk-consumer.so.debug"
     [ -f "$DEBUG_FILE" ] || fail "no $DEBUG_FILE" pack-n.log
     readelf -S "$DEBUG_FILE" > sections-n-debug.log
     grep -q '\.debug_' sections-n-debug.log || fail "the separated file carries no debug sections" sections-n-debug.log
+    [ ! -e "$DEBUG_DIR/x86_64" ] || fail "the member separated a library the engine had already stripped" pack-n.log
     rm -rf k debug-n
-    echo "ok: --debug-symbols separates the library's debug information and links the packed copy to it"
+    echo "ok: --debug-symbols: the packed library is the engine's stripped copy, linked to the engine's debug file, and the member separated nothing again"
 else
     echo "skip: (m),(n) need an engine that publishes MCPP_PACK_STRIP (2026.9.16.1+); this is $engine_version"
 fi

From b2d5fe0760a9bcef1dd510c4b4bc3b5e17de71d2 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Wed, 16 Sep 2026 07:29:14 +0800
Subject: [PATCH 08/10] rules-swift: the module's compilation declares its
 dependency file

The repository requires every rule to pass one: swiftc writes the same
Makefile-style file clang does, and without it a bridged header could change
with no rebuild.
---
 rules/swift.cppm | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/rules/swift.cppm b/rules/swift.cppm
index 717e822..15eee2e 100644
--- a/rules/swift.cppm
+++ b/rules/swift.cppm
@@ -308,12 +308,25 @@ inline bool compile(std::span<const std::string> sources, options opt = {}) {
     const std::string object = (gen / (module + ".o")).string();
     {
         const std::string id   = "swift-object:" + module;
+        const std::string dep  = (gen / (module + ".d")).string();
         const std::string desc = "SWIFTC " + module;
         mcpp::action o;
         o.id          = id.c_str();
         o.role        = "object";     // joins the link of every image of the package
         o.description = desc.c_str();
         common(o);
+        // WHAT THE MODULE READS BESIDES ITS OWN SOURCES, which only the
+        // compiler knows: a bridging header's own includes, and any header the
+        // module imports through it. swiftc writes the same Makefile-style
+        // dependency file clang does, so the engine's depfile handling reads it
+        // unchanged. Without it a bridged header could change with no rebuild,
+        // which is what this repository's "every rule declares a depfile"
+        // check exists to prevent.
+        // The DRIVER's spelling. `-emit-dependencies-path` is a frontend flag
+        // and `swiftc` refuses it; `-emit-dependencies` writes the file beside
+        // the output named by `-o`, which is `dep` below.
+        o.arg("-emit-dependencies");
+        o.depfile = dep.c_str();
         o.arg("-wmo").arg("-emit-object").arg("-o").arg(object.c_str());
         o.output(object.c_str());
         o.submit();

From 85a3c68bd3bdc73bdc50a9cf980f1ac7c38543e5 Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Wed, 16 Sep 2026 08:22:13 +0800
Subject: [PATCH 09/10] Two contributors naming one file: the closer one
 decides it, and one destination has one claimant

Review of the 0.12.0 branch before merge found the graph-contribution merge
inconsistent with the precedence its own documentation states.

`contributions` is ordered highest priority first: the application's own
libraries, then the graph's packages requesters first. The resources merge walks
it backwards, so a higher-priority contributor's resource overrides a lower
one's through `aapt2 -R`. The assets merge walked it forwards into
`collect_tree`, which copies with `overwrite_existing`, so the LAST write won
and the deepest dependency decided a file two packages name. Measured on the
fixture below: `assets/graph-asset.txt` held `from-the-deeper-library` where the
documented order gives `from-the-requester`. The walk is now backwards, for the
same reason the resources walk is.

`lib/<abi>/` is flat, so the application's own library, an archive's native
library of the same name, and a second archive's copy of it all address one
file. Each went through `place_library`, which emits a step whose id and output
are derived from the ABI and the leaf name: two claimants produced two steps
with one id writing one path. One destination now has one claimant, the first in
the priority order, and a later claim is reported by name rather than written.

`mcpp::plugins::json` decoded each `\u` escape on its own, so a code point above
U+FFFF -- which reaches JSON as a surrogate PAIR -- became two three-byte
sequences holding unpaired surrogates: not UTF-8, and silently wrong in whatever
`AndroidManifest.xml` or `Info.plist` the value was written into. Pairs are now
combined, and a surrogate that is not half of one is refused. mcpp's own writer
escapes only characters below 0x20 and passes UTF-8 through, so no producer
reaches this path today, which is why nothing reported it; the reader is shared
by `dist-apk` and `dist-apple` and should not corrupt what it cannot represent.

Criterion: `tests/apk-consumer-graph` gains `lib2/`, which `lib/` depends on, so
the two contribute one asset name at two distances. Leg (6) reads the packed
`assets/graph-asset.txt`. With the walk reverted it fails with
`from-the-deeper-library`; with it in place the five legs pass on 2026.9.16.1.
---
 dist/apk.cppm                                 | 34 ++++++++++---
 src/plugins.cppm                              | 51 +++++++++++++++----
 tests/apk-consumer-graph/check-apk-graph.sh   | 20 +++++++-
 .../lib/assets/graph-asset.txt                |  1 +
 tests/apk-consumer-graph/lib/mcpp.toml        |  4 ++
 .../lib2/assets/graph-asset.txt               |  1 +
 tests/apk-consumer-graph/lib2/mcpp.toml       | 24 +++++++++
 tests/apk-consumer-graph/lib2/src/lib2.cpp    |  1 +
 8 files changed, 118 insertions(+), 18 deletions(-)
 create mode 100644 tests/apk-consumer-graph/lib/assets/graph-asset.txt
 create mode 100644 tests/apk-consumer-graph/lib2/assets/graph-asset.txt
 create mode 100644 tests/apk-consumer-graph/lib2/mcpp.toml
 create mode 100644 tests/apk-consumer-graph/lib2/src/lib2.cpp

diff --git a/dist/apk.cppm b/dist/apk.cppm
index 9e26706..ce359ad 100644
--- a/dist/apk.cppm
+++ b/dist/apk.cppm
@@ -2090,7 +2090,25 @@ inline plan plan_for(options opt = {}) {
     // an archive's native libraries -- and to every library under an older
     // engine, which decides nothing.
     const bool engineDecided = engineStrip && *engineStrip;
-    const auto place_library = [&](const std::string& so, const std::string& abi, bool staged) {
+    // ONE DESTINATION HAS ONE CLAIMANT, AND THE FIRST CLAIM WINS. `lib/<abi>/`
+    // is flat, so the application's own library and an archive's native library
+    // of the same name address one file; so do two archives that carry it. Both
+    // loops below walk highest priority first -- the application's staged
+    // libraries, then `contributions`, which is ordered application first and
+    // each package above the packages it depends on -- so the first claim is the
+    // one the priority order names, and a later one is reported rather than
+    // written. Writing it would place two steps with one id and one output.
+    std::map<std::string, std::string> claimed;   // "<abi>/<leaf>" -> claimant
+    const auto place_library = [&](const std::string& so, const std::string& abi,
+                                   bool staged, std::string_view claimant) {
+        const std::string leafKey = abi + "/" + fs::path(so).filename().string();
+        if (auto [it, fresh] = claimed.try_emplace(leafKey, std::string(claimant)); !fresh) {
+            mcpp::warning(std::format(
+                "mcpp.dist.apk: {} and {} both carry lib/{}; {} is packed, because it comes "
+                "first in the priority order, and {} is left out.",
+                it->second, claimant, leafKey, it->second, claimant).c_str());
+            return;
+        }
         const fs::path dst = work / "lib" / abi / fs::path(so).filename();
         if (llvmStrip.empty() || (staged && engineDecided)) {
             collect_tree(so, dst, libInputs);
@@ -2144,7 +2162,7 @@ inline plan plan_for(options opt = {}) {
     };
     for (auto const& leg : legs)
         for (auto const& so : leg.libraries)
-            place_library(so, leg.abi, /*staged=*/true);
+            place_library(so, leg.abi, /*staged=*/true, "the application");
 
     // An AAR's native libraries, for every ABI this package carries.
     for (auto const& c : contributions) {
@@ -2158,16 +2176,20 @@ inline plan plan_for(options opt = {}) {
                 continue;
             }
             for (auto const& so : shared_objects_in(abiDir))
-                place_library(so, leg.abi, /*staged=*/false);
+                place_library(so, leg.abi, /*staged=*/false, c.label);
         }
     }
 
     const fs::path assetsDir = work / "assets";
     std::vector<std::string> assetInputs;
     // Library and archive assets first, so a file the build program deploys
-    // under the same name replaces theirs.
-    for (auto const& c : contributions)
-        if (!c.assets.empty()) collect_tree(c.assets, assetsDir, assetInputs);
+    // under the same name replaces theirs. `collect_tree` overwrites, so the
+    // last write wins; `contributions` is highest priority first, and is walked
+    // backwards here for the same reason the resources below are -- a package
+    // above the packages it depends on decides the file they share.
+    for (std::size_t k = contributions.size(); k-- > 0;)
+        if (!contributions[k].assets.empty())
+            collect_tree(contributions[k].assets, assetsDir, assetInputs);
     { // every deploy'd file, `<stage>/bin/<rel>` -> `assets/<rel>`: the engine
       // stages `mcpp::deploy`'s destinations under `bin/` on this row as on
       // every other.
diff --git a/src/plugins.cppm b/src/plugins.cppm
index 17394eb..5841616 100644
--- a/src/plugins.cppm
+++ b/src/plugins.cppm
@@ -269,7 +269,8 @@ inline void set_attr(node& n, const std::string& key, const std::string& value)
 // resolution report, and `mcpp::plugins::graph` below reads the engine's graph
 // document for `dist-apk` and `dist-apple`. A second parser for the second
 // document is how two readers come to disagree about one file, so there is one.
-// It reads objects, arrays, strings (with `\u` escapes below U+10000), numbers,
+// It reads objects, arrays, strings (with `\u` escapes, surrogate pairs
+// included, and a refusal for a surrogate that is not part of one), numbers,
 // `true`, `false` and `null`; a number keeps its spelling in `text`.
 export namespace mcpp::plugins::json {
 
@@ -293,6 +294,20 @@ struct reader {
     void skip_space() {
         while (i < s.size() && (s[i] == ' ' || s[i] == '\t' || s[i] == '\n' || s[i] == '\r')) ++i;
     }
+    // The four hexadecimal digits of one `\u` escape, `i` already past the `u`.
+    bool hex4(unsigned& cp) {
+        if (i + 4 > s.size()) return false;
+        cp = 0;
+        for (int k = 0; k < 4; ++k) {
+            const char h = s[i++];
+            cp <<= 4;
+            if (h >= '0' && h <= '9') cp |= static_cast<unsigned>(h - '0');
+            else if (h >= 'a' && h <= 'f') cp |= static_cast<unsigned>(h - 'a' + 10);
+            else if (h >= 'A' && h <= 'F') cp |= static_cast<unsigned>(h - 'A' + 10);
+            else return false;
+        }
+        return true;
+    }
     bool string(std::string& out) {
         if (i >= s.size() || s[i] != '"') return false;
         ++i;
@@ -307,19 +322,35 @@ struct reader {
                 case 'b': out += '\b'; break;
                 case 'f': out += '\f'; break;
                 case 'u': {
-                    if (i + 4 > s.size()) return false;
+                    // A code point above U+FFFF reaches JSON as a surrogate
+                    // PAIR, which is two `\u` escapes. Encoding each half on its
+                    // own produces two three-byte sequences holding unpaired
+                    // surrogates -- not UTF-8, and accepted by nothing that
+                    // reads the manifest this value is written into. The pair is
+                    // combined here, and a surrogate that is not part of one is
+                    // refused, so a malformed document is a refusal rather than
+                    // a silently corrupted string.
                     unsigned cp = 0;
-                    for (int k = 0; k < 4; ++k) {
-                        const char h = s[i++];
-                        cp <<= 4;
-                        if (h >= '0' && h <= '9') cp |= static_cast<unsigned>(h - '0');
-                        else if (h >= 'a' && h <= 'f') cp |= static_cast<unsigned>(h - 'a' + 10);
-                        else if (h >= 'A' && h <= 'F') cp |= static_cast<unsigned>(h - 'A' + 10);
-                        else return false;
+                    if (!hex4(cp)) return false;
+                    if (cp >= 0xd800 && cp <= 0xdbff) {
+                        if (i + 6 > s.size() || s[i] != '\\' || s[i + 1] != 'u') return false;
+                        i += 2;
+                        unsigned lo = 0;
+                        if (!hex4(lo)) return false;
+                        if (lo < 0xdc00 || lo > 0xdfff) return false;
+                        cp = 0x10000 + ((cp - 0xd800) << 10) + (lo - 0xdc00);
+                    } else if (cp >= 0xdc00 && cp <= 0xdfff) {
+                        return false;   // a low surrogate with no high half
                     }
                     if (cp < 0x80) out += static_cast<char>(cp);
                     else if (cp < 0x800) { out += static_cast<char>(0xc0 | (cp >> 6)); out += static_cast<char>(0x80 | (cp & 0x3f)); }
-                    else { out += static_cast<char>(0xe0 | (cp >> 12)); out += static_cast<char>(0x80 | ((cp >> 6) & 0x3f)); out += static_cast<char>(0x80 | (cp & 0x3f)); }
+                    else if (cp < 0x10000) { out += static_cast<char>(0xe0 | (cp >> 12)); out += static_cast<char>(0x80 | ((cp >> 6) & 0x3f)); out += static_cast<char>(0x80 | (cp & 0x3f)); }
+                    else {
+                        out += static_cast<char>(0xf0 | (cp >> 18));
+                        out += static_cast<char>(0x80 | ((cp >> 12) & 0x3f));
+                        out += static_cast<char>(0x80 | ((cp >> 6) & 0x3f));
+                        out += static_cast<char>(0x80 | (cp & 0x3f));
+                    }
                     break;
                 }
                 default: out += e;
diff --git a/tests/apk-consumer-graph/check-apk-graph.sh b/tests/apk-consumer-graph/check-apk-graph.sh
index 0579d25..cdb7342 100755
--- a/tests/apk-consumer-graph/check-apk-graph.sh
+++ b/tests/apk-consumer-graph/check-apk-graph.sh
@@ -8,7 +8,9 @@
 #     1. the library's string resource is in the APK with the library's value;
 #     2. `options::graph_libraries = false` packs no contribution;
 #     3. an application library defining the same resource wins it;
-#     4. a malformed contribution is refused, naming the package and the key.
+#     4. a malformed contribution is refused, naming the package and the key;
+#     6. of two contributors naming one asset, the one closer to the
+#        application decides it -- `lib/` over the `lib2/` it depends on.
 #   an older engine (no graph):
 #     5. the pack succeeds, and the APK carries no contribution.
 #
@@ -81,7 +83,7 @@ echo "== (4) a malformed contribution is refused, naming the package and the key
 COPY="../.apk-consumer-graph-malformed"
 rm -rf "$COPY"
 mkdir -p "$COPY"
-cp -r mcpp.toml build.mcpp src app-res lib "$COPY"/
+cp -r mcpp.toml build.mcpp src app-res lib lib2 "$COPY"/
 sed -i.bak 's/^resources = "res"$/resources = 3/' "$COPY/lib/mcpp.toml"
 grep -q '^resources = 3$' "$COPY/lib/mcpp.toml" || fail "the malformed copy was not written" "$COPY/lib/mcpp.toml"
 if ( cd "$COPY" && "$MCPP" pack --format apk --target "$TARGET" > refuse.log 2>&1 ); then
@@ -92,5 +94,19 @@ grep -q 'mcpp.apk-graph-lib@0.1.0 states `resources` as something other than a p
 rm -rf "$COPY"
 echo "ok: the refusal names mcpp.apk-graph-lib@0.1.0 and resources"
 
+echo "== (6) of two contributors naming one asset, the closer one decides it =="
+# `contributions` is highest priority first, and `collect_tree` overwrites, so a
+# forward walk would let the DEEPEST contributor win. lib/ requests lib2/, so
+# lib/ is closer to the application and its asset is the one that must survive.
+apk=$(pack graph-6.log)
+rm -rf graph-assets && mkdir -p graph-assets
+unzip -q -o "$apk" "assets/graph-asset.txt" -d graph-assets \
+    || fail "assets/graph-asset.txt is not in the APK" graph-6.log
+value=$(tr -d '\r\n' < graph-assets/assets/graph-asset.txt)
+[ "$value" = "from-the-requester" ] \
+    || fail "the deeper library won an asset the closer one names (got: '${value}')" graph-6.log
+rm -rf graph-assets
+echo "ok: assets/graph-asset.txt = from-the-requester"
+
 rm -rf target graph-*.log
 echo "PASS: dist-apk collects library contributions from the resolved graph ($engine)"
diff --git a/tests/apk-consumer-graph/lib/assets/graph-asset.txt b/tests/apk-consumer-graph/lib/assets/graph-asset.txt
new file mode 100644
index 0000000..4037f7a
--- /dev/null
+++ b/tests/apk-consumer-graph/lib/assets/graph-asset.txt
@@ -0,0 +1 @@
+from-the-requester
diff --git a/tests/apk-consumer-graph/lib/mcpp.toml b/tests/apk-consumer-graph/lib/mcpp.toml
index 0a2ea85..78f9394 100644
--- a/tests/apk-consumer-graph/lib/mcpp.toml
+++ b/tests/apk-consumer-graph/lib/mcpp.toml
@@ -11,10 +11,14 @@ authors     = ["mcpp-community"]
 [package.metadata.dist-apk]
 package   = "org.mcpp.apkgraph.lib"
 resources = "res"
+assets    = "assets"
 
 [language]
 standard = "c++23"
 
+[dependencies]
+mcpp.apk-graph-lib2 = { path = "../lib2" }
+
 [targets.apk-graph-lib]
 kind = "lib"
 
diff --git a/tests/apk-consumer-graph/lib2/assets/graph-asset.txt b/tests/apk-consumer-graph/lib2/assets/graph-asset.txt
new file mode 100644
index 0000000..2710900
--- /dev/null
+++ b/tests/apk-consumer-graph/lib2/assets/graph-asset.txt
@@ -0,0 +1 @@
+from-the-deeper-library
diff --git a/tests/apk-consumer-graph/lib2/mcpp.toml b/tests/apk-consumer-graph/lib2/mcpp.toml
new file mode 100644
index 0000000..78361be
--- /dev/null
+++ b/tests/apk-consumer-graph/lib2/mcpp.toml
@@ -0,0 +1,24 @@
+# The deeper library of `tests/apk-consumer-graph`: `lib/` depends on it, so it
+# is further from the application than `lib/` is. Both contribute an asset of
+# the same name, which is how the precedence between two contributors is
+# measured: the one closer to the application decides the file they share.
+[package]
+name        = "apk-graph-lib2"
+namespace   = "mcpp"
+version     = "0.1.0"
+description = "Fixture: the deeper of two libraries contributing an asset of one name"
+license     = "Apache-2.0"
+authors     = ["mcpp-community"]
+
+[package.metadata.dist-apk]
+package = "org.mcpp.apkgraph.lib2"
+assets  = "assets"
+
+[language]
+standard = "c++23"
+
+[targets.apk-graph-lib2]
+kind = "lib"
+
+[build]
+sources = ["src/lib2.cpp"]
diff --git a/tests/apk-consumer-graph/lib2/src/lib2.cpp b/tests/apk-consumer-graph/lib2/src/lib2.cpp
new file mode 100644
index 0000000..e72bd52
--- /dev/null
+++ b/tests/apk-consumer-graph/lib2/src/lib2.cpp
@@ -0,0 +1 @@
+int apk_graph_lib2_answer() { return 43; }

From b8b352523d8428e416d49b19e8b705096e80deaf Mon Sep 17 00:00:00 2001
From: sunrisepeak <speakshen@163.com>
Date: Wed, 16 Sep 2026 10:03:00 +0800
Subject: [PATCH 10/10] CI builds against the released 2026.9.16.1, so the
 strip-decision legs run

`MCPP_VERSION` moves 2026.9.14.2 -> 2026.9.16.1, the release this collection's
0.12.0 members are written against.

The pin is what decides whether a leg runs or reports itself skipped.
`tests/apk-consumer` legs (m) and (n) -- `mcpp pack --no-strip` and
`--debug-symbols <dir>` reaching the packed libraries -- are gated inside the
script on an engine that publishes `MCPP_PACK_STRIP`, so under the old pin they
printed `skip: (m),(n) need an engine that publishes MCPP_PACK_STRIP` and the
member's central 0.12.0 change had no CI reading at all. It has one now.

The step's own comment carried a deferral that had already retired: it said the
Android packaging step was not yet green under the pinned version because
`kind = "app"` and `mcpp::min_platform_version()` are #622 engine additions.
The pin has been above that release since 2026.9.14.2. The note now states what
is true, and what the new pin adds.
---
 .github/workflows/ci.yml | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index de3c4e6..a2663fd 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -44,7 +44,7 @@ env:
   # through the runner named after its format, which is how `mcpp run --format
   # app` reaches `macapp-run`. An engine below it stages no `needs` lines, and
   # `dist-apk` refuses its tree naming this release.
-  MCPP_VERSION: 2026.9.14.2
+  MCPP_VERSION: 2026.9.16.1
   # AN ENGINE BUILT FROM SOURCE, WHEN A DISPATCH NAMES ONE.
   #
   # Empty on every push and pull request, so the steps run the release above.
@@ -1249,11 +1249,12 @@ jobs:
       # does; `dist-apk` provisions the four payloads on its own
       # `feature-xlings.dist-apk` table (`xim:android-build-tools`, `xim:
       # android-platform`, `xim:jdk-temurin`, `xim:android-debug-keystore`).
-      # NOT YET GREEN under this job's pinned `MCPP_VERSION`: `kind = "app"`
-      # and `mcpp::min_platform_version()` are #622 engine additions, and
-      # this step needs the release that carries them (see this repository's
-      # README, `dist-apk`'s own row) -- raising the pin is P5's own change,
-      # together with the rest of this collection's release.
+      # `kind = "app"` and `mcpp::min_platform_version()` are #622 engine
+      # additions, and this step needed the release that carries them; the pin
+      # has been above it since 2026.9.14.2 and the step is green. From
+      # 2026.9.16.1 the pin also carries the engine's strip decision
+      # (`MCPP_PACK_STRIP`, `MCPP_PACK_DEBUG_SYMBOLS_DIR`), which is what lets
+      # legs (m) and (n) below run rather than report themselves skipped.
       #
       # THIS STEP ASSERTS PACKAGING ONLY, DELIBERATELY, NOT `mcpp run
       # --format apk`. This fixture's own `main.cpp` and `mcpp.toml` DO wire