fix(pack): the distributable is what the request introduced, not what names the staged tree

`mcpp pack --format <name>` reported as the distributable only those artifact
actions that named `${mcpp.stage_dir}`, on the assumption that a distributable
consumes the staged closure. NOT EVERY FORMAT DOES, and the one that does not is
the one the guidance recommends.

An `.msi` built from ONE NAMED PROGRAM takes `${mcpp.target_file:<name>}` and
never looks at the tree. That is `docs/31`'s "name the input, do not harvest a
directory", written after a bind path that resolved to nothing produced a
valid, empty, 52 KB installer with no diagnostic. So a member following that
guidance failed the check, and `mcpp pack --format msi` reported

    no action claimed --format 'msi'

after a `wix build` that had succeeded. The workaround available to the member
was to declare the placeholder as an extra, otherwise-unused input purely to
satisfy the engine -- which also gave it a dependency on a tree its one `File`
row never reads.

The property actually wanted is presence in the dispatch pass. An artifact
action present whether or not a format was asked for -- a codesign stamp, a
size budget -- existed before anyone asked, and reporting one as the package
would be a wrong answer that looks like a right one. So the first pass's
artifact actions are collected, and the dispatch reports the difference.
Identity is (package, id): an id is unique within the package that declared it
and nothing more.

`consumesStageDir` keeps its one real job -- the implicit dependency on the
staged tree's manifest, so an action that reads the tree is dirty when the
staged SET changes and not only when a link output does. Its comment now says
what it is not.

`638_pack_format_dispatch.sh` gains the case that pins this from both sides: a
fixture submitting an UNGATED artifact stamp and a GATED action that names no
staged tree at all. The gated one must be reported and the stamp must not, and
the stamp must still have been built -- it was simply not the answer. Verified
load-bearing by removing the guard, which reports `size.stamp` as the package
and fails the test.

Found while porting `mcpp.dist.wix`, which is to say by writing the second
member. The first one consumed the staged tree and agreed with the check by
accident.

Author: speak-agent

docs/30-build-mcpp.md

@@ -625,6 +625,14 @@ is that format's knowledge and not the engine's.
 `mcpp pack --format dir` writes the same tree to a path and stops, which is how
 a person inspects what a member will be handed.
 
+**`mcpp pack` reports the artifact actions the request introduced.** An action
+present whether or not a format was asked for — a codesign stamp, a size budget
+— is not the distributable, and naming one would be a wrong answer that looks
+like a right one. Nothing about the criterion is a property of the member: a
+format that packages one named program and never reads the staged tree is
+recognised exactly as one that consumes the whole closure. A format nothing
+submitted for is refused by name.
+
 **An action that names `${mcpp.stage_dir}` gains a dependency on the tree's
 manifest.** mcpp writes `<staged tree>.stage-manifest` — a sibling, never a
 member, so it does not travel inside anyone's installer — listing each staged

docs/zh/30-build-mcpp.md

@@ -534,6 +534,12 @@ pass 和那次暂存已经回答过的。
 `mcpp pack --format dir` 把同一棵树写到一个路径上就停下,这是人去查看一个成员将会拿到
 什么的方式。
 
+**`mcpp pack` 报告的是这次请求**引入**的那些 artifact action。** 一条无论有没有人
+要格式都在场的 action —— 一个签名 stamp、一次 size budget —— 不是可分发物,点名它会
+是一个看起来像对的错答案。这个判据里没有任何一项是成员的性质:一个只打包一个具名程序、
+从不读暂存树的格式,与一个消费整个闭包的格式被同等识别。对一个谁都没为之提交的格式,
+会被点名拒绝。
+
 **写了 `${mcpp.stage_dir}` 的 action 会自动获得一条对这棵树的 manifest 的依赖。**
 mcpp 会写出 `<暂存树>.stage-manifest` —— 一个兄弟文件,永不是成员,所以它不会跑进任何
 人的安装包里 —— 逐条列出每个已暂存文件的大小与相对路径。这条依赖由引擎添加,因为「用

modules/manifest/src/types.cppm

@@ -388,12 +388,19 @@ struct BuildAction {
     // Set by the engine, never by the build program: this action's command or
     // inputs named `${mcpp.stage_dir}`.
     //
-    // It is what makes the distributable ATTRIBUTABLE. `mcpp pack --format
-    // <name>` reports the file the pass produced, and the alternative -- taking
-    // every artifact action's output -- would name a codesign stamp or a size
-    // budget alongside it. It is also the flag the dispatch checks to refuse a
-    // member that declared a format and then submitted nothing for it, which
-    // would otherwise be a pack that succeeds and produces no package.
+    // ITS ONE JOB IS THE IMPLICIT DEPENDENCY. An action that names the staged
+    // tree gains an edge to that tree's manifest, so it is dirty when the
+    // staged SET changes and not only when a link output does. The dependency
+    // is implied by the use, so a member author cannot forget it.
+    //
+    // IT IS NOT HOW `mcpp pack --format <name>` DECIDES WHICH ACTION IS THE
+    // DISTRIBUTABLE, and briefly was. Not every format consumes the closure: an
+    // `.msi` built from ONE NAMED PROGRAM takes `${mcpp.target_file:<name>}`
+    // and never looks at the tree -- which is the shape the guidance
+    // recommends, after a bind path that resolved to nothing produced a valid,
+    // empty, 52 KB installer. So the member that followed the guidance was the
+    // member that check refused. The dispatch asks instead which artifact
+    // actions the REQUEST INTRODUCED; see mcpp.pack.pipeline.
     bool                               consumesStageDir = false;
     std::vector<std::string>           inputs;    // absolute or package-relative
     std::vector<std::string>           outputs;   // ditto; declared, see INV-D

src/pack/pipeline.cppm

@@ -17,6 +17,7 @@ import mcpp.build.ninja;
 import mcpp.build.plan;
 import mcpp.config;
 import mcpp.fetcher.progress;
+import mcpp.manifest;
 import mcpp.pack;
 import mcpp.pack.stage_tree;
 import mcpp.pack.strip;
@@ -318,18 +319,44 @@ export int build_and_pack(Options opts, bool modeFromUser,
     // host triple, say -- is the shape where two derivations of one value agree
     // on every machine the author has and disagree on one they do not.
     if (opts.format == mcpp::pack::Format::Dispatched) {
+        // WHICH ARTIFACT ACTIONS THIS BUILD ALREADY HAD, before a format was
+        // requested. The dispatch below reports what the REQUEST introduced,
+        // and this is the other half of that subtraction.
+        std::set<std::pair<std::string, std::string>> preexistingArtifacts;
+        for (auto const& a : ctx->plan.actions)
+            if (a.role == mcpp::manifest::BuildAction::Role::Artifact)
+                preexistingArtifacts.emplace(a.packageName, a.id);
+
         ov.pack_format    = opts.formatName;
         ov.pack_stage_dir = plan->stagingRoot;
         auto distCtx = mcpp::build::prepare_build(false, false, {}, ov);
         if (!distCtx) { mcpp::ui::error(distCtx.error()); return 2; }
 
-        // WHICH ACTIONS ARE THE DISTRIBUTABLE. Only those that named
-        // `${mcpp.stage_dir}`: a codesign stamp or a size budget is also an
-        // artifact action, and reporting one as the package would be a wrong
-        // answer that looks like a right one.
+        // WHICH ACTIONS ARE THE DISTRIBUTABLE: the artifact actions the REQUEST
+        // INTRODUCED. An action present in both passes existed before anyone
+        // asked for a format -- a codesign stamp, a size budget -- and
+        // reporting one as the package would be a wrong answer that looks like
+        // a right one.
+        //
+        // THE FIRST VERSION ASKED A NARROWER QUESTION AND GOT IT WRONG. It
+        // collected only actions naming `${mcpp.stage_dir}`, on the assumption
+        // that a distributable consumes the staged closure. Not every format
+        // does: an `.msi` built from ONE named program takes
+        // `${mcpp.target_file:<name>}` and never looks at the tree, which is
+        // the shape section 6 of the design record recommends -- "name the
+        // input, do not harvest a directory", after a bind path that resolved
+        // to nothing produced a valid, empty, 52 KB installer. So the member
+        // that followed the guidance was the member the check refused, and the
+        // workaround was to name the placeholder as an unused input purely to
+        // satisfy it. Presence-in-this-pass is the property actually wanted,
+        // and it needs nothing of the member.
+        //
+        // Identity is (package, id): an id is unique within the package that
+        // declared it and nothing more.
         std::vector<std::string> distOutputs;
         for (auto const& a : distCtx->plan.actions) {
-            if (!a.consumesStageDir) continue;
+            if (a.role != mcpp::manifest::BuildAction::Role::Artifact) continue;
+            if (preexistingArtifacts.contains({a.packageName, a.id})) continue;
             for (auto const& o : a.outputs) distOutputs.push_back(o);
         }
         // DECLARED AND THEN SUBMITTED NOTHING. The half of the contract a
@@ -340,9 +367,8 @@ export int build_and_pack(Options opts, bool modeFromUser,
             mcpp::ui::error(std::format(
                 "no action claimed --format '{}'.\n"
                 "  A package declared it provides this format, and no build "
-                "program submitted an\n"
-                "  artifact action referencing ${{mcpp.stage_dir}} when it was "
-                "asked for.\n"
+                "program submitted a new\n"
+                "  `role = \"artifact\"` action when it was asked for.\n"
                 "  The provider must gate on the request and not on anything "
                 "else:\n"
                 "      mcpp::provides_pack_format(\"{}\");                     "

tests/e2e/638_pack_format_dispatch.sh

@@ -256,4 +256,57 @@ set -e
 grep -q "no action claimed --format 'zap'" b7.log \
   || { cat b7.log; echo "FAIL: the refusal does not name the unclaimed format"; exit 1; }
 
+# ── 8. an artifact action that predates the request is not the package ─────
+# THE CRITERION IS "WHAT THE REQUEST INTRODUCED", and this is what distinguishes
+# it from "any artifact action". A codesign stamp or a size budget is also an
+# artifact action and is present whether or not a format was asked for; naming
+# one as the distributable would be a wrong answer that looks like a right one.
+#
+# It is also what an earlier revision got wrong from the other side: the check
+# collected only actions naming ${mcpp.stage_dir}, which refused a member that
+# packages ONE NAMED PROGRAM and never reads the tree -- the shape the design
+# record recommends, after a bind path that resolved to nothing produced a
+# valid, empty, 52 KB installer. So this fixture submits both shapes: an
+# ungated stamp that must be ignored, and a gated action that names no staged
+# tree at all and must still be reported.
+cd "$TMP"
+cp -r app twoshapes
+cd twoshapes
+cat > build.mcpp <<'EOF'
+import mcpp;
+#include <string>
+#include <string_view>
+int main() {
+    mcpp::provides_pack_format("zap");
+    const std::string root = mcpp::manifest_dir();
+
+    // Ungated: present in both passes, so it is not the distributable.
+    const std::string stamp = std::string(mcpp::out_dir()) + "/size.stamp";
+    mcpp::action s;
+    s.id = "size-budget"; s.role = "artifact";
+    s.arg((root + "/dist.sh").c_str()).arg("stamp").arg(root.c_str()).arg(stamp.c_str())
+     .input("${mcpp.target_file:app}").output(stamp.c_str());
+    s.submit();
+
+    if (std::string_view(mcpp::pack_format()) != "zap") return 0;
+    // Gated, and it names NO staged tree: the program arrives through
+    // ${mcpp.target_file:...} exactly as an MSI's one File row does.
+    const std::string out = std::string(mcpp::out_dir()) + "/app.zap";
+    mcpp::action a;
+    a.id = "zap"; a.role = "artifact";
+    a.arg((root + "/dist.sh").c_str()).arg("named").arg(root.c_str()).arg(out.c_str())
+     .input("${mcpp.target_file:app}").output(out.c_str());
+    a.submit();
+    return 0;
+}
+EOF
+"$MCPP" pack --format zap > b8.log 2>&1 || { cat b8.log; echo "FAIL: a member that reads no staged tree was refused"; exit 1; }
+grep -q "app.zap" b8.log \
+  || { cat b8.log; echo "FAIL: the gated action was not reported as the package"; exit 1; }
+grep -q "size.stamp" b8.log \
+  && { cat b8.log; echo "FAIL: an action predating the request was reported as the package"; exit 1; }
+# Both files exist -- the stamp was built, it was simply not the answer.
+[ -n "$(find target -name 'size.stamp' 2>/dev/null)" ] \
+  || { echo "FAIL: the ungated artifact action did not run at all"; exit 1; }
+
 echo "PASS: 638_pack_format_dispatch"