dist-apple: the bundle directory is the terminal artifact

mcpp run --format <fmt> hands the runner the request's terminal artifact:
the output of an introduced action no other introduced action consumes.
dist-apple's plan submits info-plist, layout, icon and codesign as
parallel steps -- each writes a file inside the bundle and none consumes
another's output -- so a plan with more than one of them has that many
terminal artifacts and mcpp run has no single operand. This is the
iOS-row failure: "produced 4 distributables ... needs exactly one".

The distributable of --format app is the bundle directory itself, not any
one file inside it. Added a final step, id mcpp.dist.apple.bundle, whose
inputs are every previous step's own output (codesign's stamp included,
so the bundle is not the terminal until signing has happened) and whose
single output is the bundle directory, produced by /usr/bin/touch -- a
directory is an acceptable action output (the engine accepts
is_regular_file || is_directory), and touch's refreshed mtime is what
lets ninja record the edge as run. The same plan_for code path serves
both the Contents/-shaped macOS layout and the flat iOS one, so both rows
get the fix together.

tests/ios-app-consumer/check-ios-plan.sh now asserts the property, not
just the step's presence: for every row (simulator, simulator with an
empty stage dir, device, macOS), every other planned step's output must
be named among the bundle step's own inputs, and the bundle step's own
output must be named in no step's inputs anywhere in the plan -- the
property that makes it the plan's sole terminal. The check reads only the
declared "inputs" field, not the whole action line, because ditto's own
argv legitimately names the bundle directory as a copy destination on
every row and that is not a graph dependency. Also asserts no bundle step
is planned on the icon-refused path, where no steps are submitted at all.
tests/app-consumer carries no separate plan-check script; its CI step
execs the bundle directly rather than going through mcpp run --format,
so it was not exposed to this failure.

Verified against the released engine (2026.9.12.3): reverting the
dist/apple.cppm change makes the updated script fail with "no bundle
step planned" on every row; with the change, all five checks pass.

Author: Sunrisepeak

dist/apple.cppm

@@ -43,22 +43,34 @@
 // and no `options::tool` the way `wix` does in `dist/wix.cppm` -- there is
 // exactly one `ditto`, at a fixed path, on every Mac this can run on.
 //
-// HOW MANY ACTIONS, AND WHY EACH IS SEPARATE. Up to four:
+// HOW MANY ACTIONS, AND WHY EACH IS SEPARATE. Up to five:
 //
 //   1. install `Info.plist`         (always)
 //   2. lay out the staged tree      (always)
 //   3. install the icon             (only when `options::icon` is set)
 //   4. codesign the bundle          (only when `options::identity` is set)
+//   5. the bundle itself            (always, last)
 //
 // 1 and 3 are separate from 2 because they have different INPUTS: `Info.plist`
 // is regenerated whenever package metadata changes, the icon only when the
 // project's icon file changes, and the staged tree only when the program or
 // its closure changes. One action for all three would make every one of those
-// changes re-run the multi-hundred-megabyte copy. 4 is last and depends on
-// the OUTPUTS of whichever of 1 to 3 actually ran, because a code signature
-// covers the bundle's content at signing time -- signing before the content
-// is in place is either a failure (an incomplete bundle) or a signature that
-// the next file added invalidates.
+// changes re-run the multi-hundred-megabyte copy. 4 is last of the CONTENT
+// steps and depends on the OUTPUTS of whichever of 1 to 3 actually ran,
+// because a code signature covers the bundle's content at signing time --
+// signing before the content is in place is either a failure (an incomplete
+// bundle) or a signature that the next file added invalidates.
+//
+// 5 EXISTS BECAUSE 1 THROUGH 4 ARE PARALLEL, AND `mcpp run` NEEDS ONE
+// OPERAND. Each of them writes a file inside the bundle and consumes none of
+// the others' outputs, so a request that submits only this plan has as many
+// terminal artifacts (outputs nothing else consumes) as steps actually ran --
+// up to four, never one. `mcpp run --format app` resolves to THE terminal
+// artifact, so a plan with more than one has none it can hand the runner.
+// Step 5's output is the bundle DIRECTORY -- the actual distributable of this
+// format -- and its inputs are every other step's output, so it is always
+// the plan's sole terminal, in both the `Contents/`-shaped and flat-iOS
+// layouts.
 //
 // `Info.plist` IS WRITTEN AT PLAN TIME, BUT NOT DIRECTLY TO ITS FINAL PATH,
 // AND THE DIFFERENCE MATTERS. It is configuration, so `write_if_different`
@@ -772,8 +784,39 @@ inline plan plan_for(options opt = {}) {
         // something measured here -- codesign does not run on Linux.
         sign.outputs = { (isIos ? bundlePath : bundlePath + "/Contents") + "/_CodeSignature/CodeResources" };
         p.steps.push_back(sign);
+        assembled.push_back(sign.outputs.front());
     }
 
+    // THE BUNDLE DIRECTORY IS THIS PLAN'S OWN TERMINAL ARTIFACT.
+    //
+    // `mcpp run --format <fmt>` hands the runner the request's TERMINAL
+    // ARTIFACT -- the output of an introduced action no other introduced
+    // action consumes. Every step above writes a file INSIDE the bundle
+    // (`Info.plist`, the executable, an icon, codesign's own stamp), and
+    // none of those files is an input of any of the others in a chain that
+    // ends in one: `info`, `layout`, `icon` and `sign` are four parallel
+    // steps, so without this one the plan has four terminals and `mcpp run`
+    // has no single operand to pass on -- exactly the failure `dist-apple`'s
+    // iOS row hit (#622: "produced 4 distributables ... needs exactly one").
+    //
+    // The distributable of `--format app` is the BUNDLE, not any one file in
+    // it, so this step's own output is the bundle directory itself, and its
+    // inputs are every other step's output declared so far -- codesign's
+    // stamp included, when it ran, so the bundle is not the terminal until
+    // signing (the last thing that can still fail) has happened. A directory
+    // is an acceptable action output (the engine verifies `is_regular_file
+    // || is_directory`); `touch` has nothing to write, only a mtime to
+    // refresh, and refreshing it is what makes ninja record the edge as run
+    // rather than replay a stale one.
+    step bundle;
+    bundle.id          = "mcpp.dist.apple.bundle";
+    bundle.role        = "artifact";
+    bundle.description = "APP BUNDLE";
+    bundle.argv         = { "/usr/bin/touch", bundlePath };
+    bundle.inputs        = assembled;
+    bundle.outputs       = { bundlePath };
+    p.steps.push_back(bundle);
+
     p.applies = true;
     return p;
 }

tests/ios-app-consumer/check-ios-plan.sh

@@ -18,6 +18,67 @@ set -e
 MCPP="${MCPP:-mcpp}"
 fail() { echo "FAIL: $1"; shift; for f in "$@"; do echo "--- $f ---"; cat "$f" 2>/dev/null; done; exit 1; }
 
+# THE BUNDLE STEP IS THE PLAN'S SOLE TERMINAL ARTIFACT (#622: "mcpp run
+# --format app produced 4 distributables ... needs exactly one"). `info`,
+# `layout`, `icon` and `codesign` are parallel -- none consumes another's
+# output -- so without a step naming the bundle directory itself as ITS
+# output, `mcpp run --format app` has as many terminal artifacts as steps ran
+# and no single operand to hand the runner. This checks the property, not
+# just the id's presence: every OTHER planned step's own output must be named
+# among `bundle`'s own inputs, and `bundle`'s own output (the `.app`
+# directory) must be named in no step's inputs anywhere in the plan -- the
+# one thing left that nothing consumes.
+# Both restricted to the named FIELD, never the whole JSON line: `command`
+# (ditto's own argv) legitimately names the bundle directory as a
+# destination on every row, and matching against the whole line would read
+# that as "consumes", which it is not -- only `inputs` decides the graph's
+# edges.
+quoted_outputs() { # $1 = one action's JSON line
+    echo "$1" | grep -oP '(?<="outputs":\[)[^]]*' | grep -oP '"[^"]*"'
+}
+quoted_inputs() { # $1 = one action's JSON line
+    echo "$1" | grep -oP '(?<="inputs":\[)[^]]*' | grep -oP '"[^"]*"'
+}
+check_terminal_bundle() {
+    local log="$1" bundle_line bundle_out other_id other_line q found_any=0
+    bundle_line=$(grep -o '"id":"mcpp\.dist\.apple\.bundle"[^}]*}' "$log") \
+        || fail "no bundle step planned" "$log"
+    [ -n "$bundle_line" ] || fail "no bundle step planned" "$log"
+    bundle_out=$(quoted_outputs "$bundle_line")
+    [ "$(echo "$bundle_out" | wc -l)" -eq 1 ] \
+        || fail "the bundle step does not declare exactly one output" "$log"
+    echo "$bundle_out" | grep -q '\.app"$' \
+        || fail "the bundle step's own output is not the .app directory" "$log"
+    local bundle_inputs
+    bundle_inputs=$(quoted_inputs "$bundle_line")
+    for other_id in mcpp.dist.apple.info-plist mcpp.dist.apple.layout \
+                    mcpp.dist.apple.icon mcpp.dist.apple.codesign; do
+        other_line=$(grep -o "\"id\":\"$other_id\"[^}]*}" "$log") || true
+        [ -n "$other_line" ] || continue
+        found_any=1
+        while IFS= read -r q; do
+            [ -n "$q" ] || continue
+            grep -qF "$q" <<<"$bundle_inputs" \
+                || fail "the bundle step does not depend on $other_id's own output ($q)" "$log"
+        done <<<"$(quoted_outputs "$other_line")"
+        # And the reverse: no OTHER step may already name the bundle
+        # directory among its OWN inputs -- that would make it, not
+        # `bundle`, the one this plan's earlier steps are ordered against.
+        grep -qF "$bundle_out" <<<"$(quoted_inputs "$other_line")" \
+            && fail "$other_id names the bundle directory among its own inputs" "$log"
+    done
+    [ "$found_any" -eq 1 ] || fail "no content step (info/layout/icon/codesign) was planned to check against" "$log"
+    # Nothing anywhere in the plan consumes the bundle step's own output (as
+    # an INPUT, never as an argv destination) -- the property that makes it
+    # the sole terminal artifact.
+    while IFS= read -r other_line; do
+        [ -n "$other_line" ] || continue
+        grep -qF "$bundle_out" <<<"$(quoted_inputs "$other_line")" \
+            && fail "something in the plan still consumes the bundle directory as an input; it is not the sole terminal" "$log"
+    done <<<"$(grep -o '"id":"mcpp\.dist\.apple\.[a-z-]*"[^}]*}' "$log" | grep -v '"id":"mcpp\.dist\.apple\.bundle"')"
+    echo "ok: mcpp.dist.apple.bundle is the plan's sole terminal artifact ($bundle_out)"
+}
+
 rm -rf target
 "$MCPP" build > build.log 2>&1 || fail "the host build failed to compile build.mcpp" build.log
 BIN=target/.build-mcpp/build.mcpp.bin
@@ -89,6 +150,7 @@ grep 'mcpp.dist.apple.layout' "$log" | grep -q '\${mcpp\.stage_dir}' \
 grep -q 'holds only' "$log" \
     && fail "a non-empty staged tree still produced the 0-byte staged-tree warning" "$log"
 echo "ok: flat layout, no codesign, a named warning, and every iOS-only plist key"
+check_terminal_bundle "$log"
 
 echo "== iOS Simulator row, an empty pack_stage_dir (#622 B2 defect 1) =="
 run_row simnostage ios sim /tmp/ios-plan-sim-nostage.log EMPTY > /dev/null
@@ -101,6 +163,7 @@ grep 'mcpp.dist.apple.layout' "$log" | grep -q '\${mcpp\.stage_dir}' \
 grep -q 'holds only' "$log" \
     && fail "an empty pack_stage_dir produced the misleading 0-byte staged-tree warning" "$log"
 echo "ok: an empty pack_stage_dir takes the single-binary path, named through \${mcpp.target_file:...}, with no staged-tree warning"
+check_terminal_bundle "$log"
 
 echo "== iOS Simulator row, a manifest directory with no ios-icons/ (#622 B2 defect 2) =="
 badmanifest=$(mktemp -d)
@@ -111,6 +174,8 @@ grep -qF "$badmanifest/ios-icons" "$log" \
     || fail "the missing-icon refusal did not resolve options::icon against MCPP_MANIFEST_DIR" "$log"
 grep -q 'mcpp.dist.apple.layout' "$log" \
     && fail "a layout step was planned even though the icon directory was refused" "$log"
+grep -q 'mcpp.dist.apple.bundle' "$log" \
+    && fail "a bundle step was planned even though the icon directory was refused" "$log"
 echo "ok: a relative options::icon resolves against MCPP_MANIFEST_DIR, and a missing directory is refused at plan time, naming options::icon and the path"
 
 echo "== iOS device row =="
@@ -123,6 +188,7 @@ grep -q 'is ignored on the iOS Simulator row' "$log" \
 grep -A2 '<key>CFBundleSupportedPlatforms</key>' "$plist" | grep -q 'iPhoneOS' \
     || fail "CFBundleSupportedPlatforms does not name iPhoneOS on the device row" "$plist"
 echo "ok: codesign is planned, and CFBundleSupportedPlatforms names iPhoneOS"
+check_terminal_bundle "$log"
 
 echo "== macOS row is unaffected =="
 outdir=$(run_row macos macos "" /tmp/ios-plan-macos.log)
@@ -137,5 +203,6 @@ for key in CFBundleSupportedPlatforms UIDeviceFamily LSRequiresIPhoneOS MinimumO
 done
 grep -q '<key>NSHighResolutionCapable</key>' "$plist" || fail "the macOS plist lost NSHighResolutionCapable" "$plist"
 echo "ok: the macOS row's steps and plist are unchanged by the iOS branch"
+check_terminal_bundle "$log"
 
 echo "PASS: dist-apple's iOS row, at the plan level"