2026.9.28.1: eight reports (#717, #718, #720, #722-#726), one download progress, and an index floor that is a tip

.agents/docs/2026-09-27-eight-reports-implementation-plan.md

@@ -0,0 +1,115 @@
+---
+subject: plan
+status: active
+---
+
+# Eight reports after 2026.9.27.1: implementation plan
+
+This record implements `2026-09-27-eight-reports-by-home-and-one-optimisation-plan.md`
+(the design, revision 3, all decisions settled). The design fixes what is built. This
+record fixes the following:
+
+- the order;
+- which files each task owns;
+- the repositories involved and the order of their releases;
+- how each step is verified.
+
+## 1. Readings that shaped the plan
+
+- **xlings emits no progress events for an index sync (measured).** The command is
+  `xlings interface update_packages --args '{}'` (xlings 2026.9.27.1).
+  - It emits heartbeats and one result, and no progress event.
+  - It also writes its terminal progress text (`[1/7] awesome::xim.lua` followed by
+    an erase sequence) onto the NDJSON stream. That text is not JSON, and the
+    xlings interface protocol (`docs/spec/interface-ndjson-v1.md`) does not allow
+    it.
+  - W11 therefore needs an xlings change and an xlings release before the mcpp
+    release.
+- **mcpp-language-server.** speak-agent has read access only, so its S1 change is
+  proposed from a fork.
+- **The next e2e number is 805.** Unit tests live in `tests/unit/`.
+
+## 2. Repositories and their order
+
+| Order | Repository | Pull request | Content | Release |
+|---|---|---|---|---|
+| 1 | openxlings/xlings | one | interface mode emits `progress` events for an index sync and keeps terminal text off the NDJSON stream | yes; the date version of the day |
+| 2 | Sunrisepeak/mcpp-language-server | one, from a fork | S1: the generated-output record (design §4.4, D6) | no, a specification only |
+| 3 | mcpp-community/mcpp | one: #727, which also carries #726's fix (W13) | W1 to W13, docs, specs, CHANGELOG, version, xlings pin | yes |
+| 4 | openxlings/xim-pkgindex | the bot's bump pull request | mcpp's new version | merged by a maintainer account |
+| 5 | mcpplibs/mcpp-index | one, if its CI pin or `latest_mcpp` must move | index consumer pins | no release; the index publishes on merge |
+
+The mcpp pull request pins the xlings release of row 1 (`kXlingsVersion`), and the
+release pull request carries that pin.
+
+## 3. Tasks, owners and dependencies
+
+The work uses one integration branch, `feat/eight-reports`, in the worktree
+`mcpp-eight`. Each task has its own worktree, branched from the integration
+branch, and is merged back when its criteria pass.
+
+| Task | Steps | Files owned (smallest hunks elsewhere) | Depends on |
+|---|---|---|---|
+| T1 | W1 | `src/build/prepare/manifest.cpp`, `src/project.cppm` (member resolution), `src/cli.cppm` (`-p` help), `docs/07` (en, zh), SPEC-004 §9, `tests/unit/test_workspace_inheritance.cpp`, e2e 805 and 806 | none |
+| T2 | W2 | `src/build/prepare/features.cpp` (host-module unit order), e2e 807 | none |
+| T3 | W3, W4, W5 | `src/build/plan.cppm` (the unit loop only), `src/build/prepare/target_side.cpp` (the device-source check), `src/build/prepare/driver.cpp`, `src/build/prepare/xlings.cpp` (the project index file), `src/cli/cmd_build.cppm` (the emit failure path), SPEC-005, e2e 688 extended, e2e 808 and 809 | none |
+| T4 | W6 | `src/build/plan.cppm` (`add_deploy` only), `src/build/stage.cppm`, `src/cli/cmd_build.cppm` (`cmd_stage` only), `src/build/ninja_backend.cppm` (the stage and `place_dlls` edges), `src/pack/pack.cppm` (`place_runtime_dlls`), SPEC-007 R4.2 and R4.3, e2e 810 and 811 | none |
+| T5 | W12 | `src/pm/package_fetcher.cppm`, `src/pm/index_contract.cppm`, `src/xlings/xlings.cppm` (`update_index` reporting), `src/ui.cppm` (closing notices), `src/doctor.cppm`, `docs/09` and `docs/50`, e2e 185 updated, e2e 812 | none |
+| T6 | W7 | `src/build/prepare/*.cpp` (phase functions), `.github/tools/` (the size gate), `tests/unit/test_prepare_helpers.cpp` | every other task merged (the last step; see the design, §11) |
+| T7 | W8 | `modules/manifest/src/toml.cppm`, `modules/manifest/src/types.cppm`, `src/build/prepare/scan.cpp` and `target_side.cpp` (dialect resolution), `src/build/prepare_inputs.cppm`, SPEC-004 §3.1 and §9, e2e 813 | T1 to T5 merged |
+| T8 | W9 | `modules/toolchain-model/src/dialect.cppm`, `src/build/flags.cppm`, `src/build/prepare/scan.cpp` (std-module CRT), `src/build/distribution.cppm`, the toolchain redistributable field (`src/toolchain/msvc.cppm`, the LLVM row's sysroot resolution), `src/pack/pack.cppm` (contract), `docs/20` and `docs/04`, unit tests, e2e 814 (Windows) | T1 to T5 merged; its free-form word rule reads T7's list at merge |
+| T9 | W10 | `src/build/build_database.cppm`, SPEC-005 §3, e2e 815 | T3; the S1 text (Sunrisepeak/mcpp-language-server#28) |
+| T10 | W11 | `src/ui.cppm` (terminal and non-terminal rendering), `src/xlings/xlings.cppm` (index refresh through the interface), the git fetch in `src/build/prepare/fetch.cpp` and `graph.cpp`, the sandbox bootstrap, `docs/09`, unit tests, e2e 816 | T5; the xlings change (X1), with its release before mcpp's |
+| X1 | xlings | `openxlings/xlings`: the interface event stream for `update_packages` | none |
+| L1 | mcppls | `docs/specs` S1 addition | none |
+
+T1 to T5, X1 and L1 have no dependency on one another. At most three subagents run
+at once. The author takes T2 and the merges, and runs the integration build and
+the full test suites.
+
+**Rules for parallel work.** These come from the 2026-09-12 and 2026-09-26 records.
+
+- **No global configuration change.** No task changes `~/.mcpp/config.toml` or any
+  other global configuration. A toolchain is selected per fixture or per command.
+- **No broad `pkill -f`.** No task kills processes by a broad `pkill -f` pattern.
+- **One build per worktree.** No two builds run in one worktree at once.
+- **Clean up after merging.** A merged task's `target/` is removed.
+
+## 4. Verification
+
+**Per task.**
+
+- The fresh binary passes `mcpp test` and the task's own e2e scripts.
+- Each new criterion is also run with the fix removed, and must then fail.
+
+**Integration.**
+
+- A full `mcpp test`.
+- The e2e suite on Linux, through `tests/e2e/run_all.sh` with the fresh binary.
+- The golden fixtures of the #719 decomposition.
+- CI on every platform through the one pull request.
+
+**After the release.**
+
+- **A sandbox.** `xlings subos new eight`, then `xlings subos use eight --sandbox
+  --cmd ...`, with both mcpp and xlings on the CN mirror. The sandbox installs the
+  released mcpp by its release path and runs one probe per step. The probe is
+  passed in as base64, and each probe directory is removed at the start of its
+  section.
+- **A control.** The same script runs against 2026.9.27.1, where exactly the fixed
+  criteria must fail.
+- **The index ecosystem.** mcpp-index's validation sweep runs against the new
+  release.
+
+## 5. Release
+
+The version is the date version of the release day. The xlings pin moves to the
+xlings release of row 1.
+
+1. After the release workflow starts, every archive and its sidecar are uploaded
+   to GitCode with the local `gtc` as soon as each appears on the GitHub release.
+2. Each GitCode asset is verified by a GET with a byte comparison.
+3. The xim-pkgindex bump pull request is merged with the maintainer account, and
+   its state is read back afterwards.
+4. The release is complete when `pkgs/m/mcpp.lua` on the index's `main` has
+   `latest` pointing at the release.

.agents/docs/README.md

@@ -18,7 +18,7 @@ superseded_by: 2026-09-07-....md  # when status is superseded
 ---
 ```
 
-311 records.
+313 records.
 
 ## By subject
 
@@ -56,6 +56,7 @@ Records that declare one. Everything else is listed by date below.
 
 ### plan
 
+- [Eight reports after 2026.9.27.1: implementation plan](2026-09-27-eight-reports-implementation-plan.md) — active
 - [#690: implementation plan](2026-09-25-issue-690-implementation-plan.md) — landed
 - [工具链选择与载荷可信度：实施计划](2026-09-24-toolchain-selection-implementation-plan.md) — landed
 - [openkal 生态：完整性收尾与验收方案](2026-09-21-openkal-ecosystem-completion-and-acceptance.md) — active
@@ -82,6 +83,7 @@ Records that declare one. Everything else is listed by date below.
 
 ### triage
 
+- [Eight reports after 2026.9.27.1: what each one is, where it belongs, and one optimisation plan](2026-09-27-eight-reports-by-home-and-one-optimisation-plan.md) — active
 - [#685、#687 与 Windows clang 的 MSVC STL：三个问题的归属，以及工具链载荷的规范化](2026-09-24-685-687-msvc-stl-and-toolchain-payloads.md) — landed
 - [运行时绑定方案 v3:让 mcpp 真正安装它所声明的运行时](2026-09-17-runtime-binding-multi-repo-plan.md) — landed
 - [#662:目标侧由依赖图提供时，编译器的隐式头文件搜索仍指向宿主](2026-09-17-issue-662-graph-target-header-isolation-plan.md) — active
@@ -102,6 +104,8 @@ Records that declare one. Everything else is listed by date below.
 
 ### 2026-09
 
+- [Eight reports after 2026.9.27.1: implementation plan](2026-09-27-eight-reports-implementation-plan.md) — active
+- [Eight reports after 2026.9.27.1: what each one is, where it belongs, and one optimisation plan](2026-09-27-eight-reports-by-home-and-one-optimisation-plan.md) — active
 - [The compile database, `emit build-database`, and #701/#702: triage against the specifications, and one design](2026-09-26-compile-database-and-issue-699-design.md) — landed
 - [Issues #693 to #696: triage against mcpp's contracts, and one repair plan](2026-09-25-issues-693-696-triage-and-repair-plan.md) — landed
 - [Workspace inheritance, flag scoping and the published form: a unified repair plan (#690)](2026-09-25-issue-690-workspace-build-inheritance-consistency.md) — landed

.github/actions/bootstrap-mcpp/action.yml

@@ -25,7 +25,7 @@ inputs:
     # `package.name`, so one of the two was simply unreachable — and which one
     # depended on the machine, which is why CI failed on `compat:lua` on
     # Windows and `mcpplibs.capi:lua` on Linux. Never pin below that.
-    default: '2026.9.27.1'
+    default: '2026.9.28.1'
   cache-target:
     description: also restore/save target/ (build artifacts + BMIs)
     required: false

.github/actions/setup-macos-llvm/action.yml

@@ -15,7 +15,7 @@ inputs:
     # Floor imposed by the index, not a routine bump — see
     # .github/actions/bootstrap-mcpp/action.yml for why 0.4.69 is required
     # (two packages named `lua` in one repo need openxlings/xlings#381).
-    default: '2026.9.27.1'
+    default: '2026.9.28.1'
   image:
     description: >
       The runner label the job runs on (macos-15, xcode-27). It is part of the

.github/tools/check_function_sizes.sh

@@ -0,0 +1,184 @@
+#!/usr/bin/env bash
+#
+# Guard: no function under the prepare.cppm decomposition grows past ~400
+# lines (mcpp-community/mcpp#722, T6 of the 2026-09-27 round).
+#
+# WHY
+#
+# check_file_lengths.sh caps each FILE at 2,500 lines. It says nothing about
+# a single FUNCTION inside a file that stays under the cap while one phase
+# function alone climbs back past a thousand lines and closes back over the
+# ~180-local shape prepare.cppm was split to remove in the first place (see
+# that script's own header, and the layout comment atop src/build/prepare.cppm).
+# #722 split the seven functions that had grown past ~400 lines into
+# sub-steps named after the sections their own banners already used; this
+# gate is what keeps a phase function from quietly growing back into one.
+#
+# THE RULE
+#
+# Every function defined in a file directly under src/build/prepare/ (or in
+# src/build/prepare.cppm itself) stays at or under LINE_THRESHOLD lines, as
+# clang-tidy's readability-function-size check counts them (its own count,
+# not a text-heuristic line counter -- a brace-counting or regex-based
+# stand-in cannot tell a function's extent from a `{`/`}` pair inside a
+# string literal or a designated initializer, both common in this codebase's
+# std::format calls and manifest structs; see .agents/docs/
+# 2026-09-27-eight-reports-by-home-and-one-optimisation-plan.md §8).
+#
+# WHAT THIS NEEDS
+#
+# A compile database that names BMIs explicitly (-fmodule-file=...), which
+# only a build actually produces: `mcpp build --toolchain llvm@22.1.8` writes
+# compile_commands.json at the project root. This script does not build it:
+# the caller runs that build first. check_file_lengths.sh needs no such
+# division because it reads the tree.
+#
+# NOT IN CI YET. The only CI job that builds mcpp with clang (ci-linux.yml,
+# "toolchain: musl + llvm", llvm@20.1.7) does not produce a complete build:
+# libc++ 20's `std` module does not make directory_iterator's comparison
+# visible, and that step reads the resolution line rather than the build's
+# exit status. Over the partial database clang-tidy crashes. The gate is wired
+# in once a CI job builds mcpp with clang (mcpp-community/mcpp#729); until
+# then it is run by hand after `mcpp build --toolchain llvm@22.1.8`.
+#
+# clang-tidy itself is not part of the plain xim:llvm payload mcpp resolves
+# for `--toolchain llvm@...` (measured: xim-x-llvm/22.1.8/bin has clang,
+# clang-scan-deps and the LLVM binutils, no clang-tidy). It ships in the
+# sibling package `xim:llvm-tools` at the same version -- resolved and
+# searched for under the xlings package store; install it with
+# `xlings install xim:llvm-tools@<version that matches your llvm toolchain>`
+# if this script cannot find it.
+#
+# Usage: bash .github/tools/check_function_sizes.sh [repo_dir]
+
+set -uo pipefail
+
+REPO_DIR="${1:-$(pwd)}"
+cd "$REPO_DIR" || { echo "FAIL: cannot cd to $REPO_DIR" >&2; exit 1; }
+
+LINE_THRESHOLD=400
+DIR="src/build/prepare"
+PRIMARY="src/build/prepare.cppm"
+CDB="compile_commands.json"
+
+[ -d "$DIR" ] || { echo "FAIL: $DIR does not exist -- this guard has gone stale" >&2; exit 1; }
+
+if [ ! -f "$CDB" ]; then
+    cat >&2 <<EOF
+FAIL: $CDB does not exist.
+  This check reads clang-tidy's own function boundaries, which needs a
+  compile database that names every imported module's BMI explicitly.
+  Produce one first:
+      mcpp build --toolchain llvm@22.1.8
+  (any installed LLVM row works; the database is written at the project
+  root regardless of the row's exact version).
+EOF
+    exit 1
+fi
+
+# Locate clang-tidy. It is not in the plain xim:llvm payload (see the header
+# comment); it is the sibling xim:llvm-tools payload, and it must be the
+# version of the clang that wrote compile_commands.json, because it reads the
+# BMIs that clang wrote. `CLANG_TIDY` may name it explicitly; otherwise
+# the version is read from the compiler path the database names
+# (`.../xim-x-llvm/<version>/bin/clang++`) and looked up in either xlings store.
+cdb_llvm_version() {
+    grep -o 'xim-x-llvm/[0-9][0-9.]*/bin/clang' "$CDB" 2>/dev/null | head -1 \
+        | sed 's|xim-x-llvm/\([0-9.]*\)/bin/clang|\1|'
+}
+find_clang_tidy() {   # $1 = the llvm version
+    local root
+    for root in "${MCPP_HOME:-$HOME/.mcpp}/registry/data/xpkgs" "$HOME/.xlings/data/xpkgs"; do
+        [ -x "$root/xim-x-llvm-tools/$1/bin/clang-tidy" ] \
+            && { echo "$root/xim-x-llvm-tools/$1/bin/clang-tidy"; return 0; }
+    done
+    return 1
+}
+
+if [ -n "${CLANG_TIDY:-}" ]; then
+    [ -x "$CLANG_TIDY" ] || { echo "FAIL: CLANG_TIDY=$CLANG_TIDY is not executable" >&2; exit 1; }
+else
+    LLVM_VERSION="$(cdb_llvm_version)"
+    CLANG_TIDY="$( [ -n "$LLVM_VERSION" ] && find_clang_tidy "$LLVM_VERSION" )" || {
+        cat >&2 <<EOF
+FAIL: no clang-tidy of the llvm version that wrote $CDB (${LLVM_VERSION:-unknown})
+      was found under an xlings package store. Install that toolchain's sibling:
+          xlings install xim:llvm-tools@${LLVM_VERSION:-<version>}
+EOF
+        exit 1
+    }
+fi
+
+# The files this database actually has entries for, restricted to the
+# decomposition's own directory (plus the primary interface, if it is ever
+# given its own compiled entry point -- it has none today, since it defines
+# only declarations and inline exports; the loop below tolerates that).
+mapfile -t FILES < <(python3 - "$CDB" "$DIR" "$PRIMARY" <<'PYEOF'
+import json, sys
+cdb_path, dirname, primary = sys.argv[1], sys.argv[2], sys.argv[3]
+with open(cdb_path) as f:
+    entries = json.load(f)
+seen = set()
+for e in entries:
+    path = e["file"]
+    if f"/{dirname}/" in path or path.endswith(f"/{primary}"):
+        seen.add(path)
+for p in sorted(seen):
+    print(p)
+PYEOF
+)
+
+if [ "${#FILES[@]}" -eq 0 ]; then
+    echo "FAIL: $CDB has no entry under $DIR -- was it built with a matching source tree?" >&2
+    exit 1
+fi
+
+echo "checking ${#FILES[@]} file(s) with $CLANG_TIDY (LineThreshold=$LINE_THRESHOLD)..."
+
+OUT="$(mktemp)"
+trap 'rm -f "$OUT"' EXIT
+
+# No --warnings-as-errors: the only check enabled is readability-function-size
+# itself, and a finding in json.hpp (bundled third-party, reached through one
+# of these files' imports) would then make clang-tidy exit non-zero on every
+# run regardless of this decomposition's own state -- exactly the ambiguity
+# the "diagnostic tool problem" branch below exists to catch, and it cannot
+# tell the two apart from an exit code alone. The `relevant` filter is the
+# sole pass/fail signal; clang-tidy's own exit code is read only as a sign
+# that the tool itself failed to run (a bad compile command, a crash), which
+# a plain warning never produces.
+"$CLANG_TIDY" \
+    --checks='-*,readability-function-size' \
+    --config="{CheckOptions: {readability-function-size.LineThreshold: '$LINE_THRESHOLD'}}" \
+    -p "$REPO_DIR" \
+    "${FILES[@]}" > "$OUT" 2>&1
+rc=$?
+
+# Only findings inside the decomposition's own directory gate the build: a
+# bundled third-party header (e.g. modules/libs/src/json/json.hpp) reached
+# through one of these files' imports is not this decomposition's to fix.
+# A finding is a diagnostic line, which ends with the bracketed check name; a
+# crash dump also names the check (in its program arguments) together with
+# every file path, and must not read as a finding.
+relevant=$(grep -E '\[readability-function-size\]$' "$OUT" | grep -F -e "/$DIR/" -e "/$(basename "$PRIMARY")" || true)
+
+if [ -n "$relevant" ]; then
+    echo "$relevant" >&2
+    echo >&2
+    echo "FAIL: function(s) over $LINE_THRESHOLD lines under $DIR -- see above." >&2
+    echo "  Split at the sub-section boundaries its own banners already name" >&2
+    echo "  (mcpp-community/mcpp#722's own method), the way phase13_finish," >&2
+    echo "  phase4b_graph_worklist, phase6_features_and_host_tools and" >&2
+    echo "  phase9_target_side were split." >&2
+    exit 1
+fi
+
+if [ "$rc" -ne 0 ]; then
+    echo "FAIL: clang-tidy exited $rc with no readability-function-size finding under $DIR" >&2
+    echo "  (a diagnostic tool problem, not a function-size one -- see the log):" >&2
+    cat "$OUT" >&2
+    exit 1
+fi
+
+echo "ok: no function under $DIR (or $PRIMARY) exceeds $LINE_THRESHOLD lines"
+exit 0

.github/workflows/bootstrap-macos.yml

@@ -17,7 +17,7 @@ jobs:
       # Dormant (workflow_dispatch only), but kept in step with the rest —
       # check_version_pins.sh holds it there. Floor: 0.4.69, below which the
       # index cannot resolve two packages that share a short name.
-      XLINGS_VERSION: '2026.9.27.1'
+      XLINGS_VERSION: '2026.9.28.1'
     steps:
       - uses: actions/checkout@v4