2026.10.16.1: the provider port, indices in mcpp's home, upstreams, the system home, filesystems and long paths

.agents/docs/README.md

@@ -18,7 +18,7 @@ superseded_by: 2026-09-07-....md  # when status is superseded
 ---
 ```
 
-331 records.
+332 records.
 
 ## By subject
 
@@ -121,10 +121,15 @@ Records that declare one. Everything else is listed by date below.
 - [The engine gaps left open after the SDK batch](2026-09-12-engine-gaps-after-the-sdk-batch.md) — landed
 - [Six open issues: what each one actually is, and what would answer it](2026-09-11-six-open-issues-analysis.md) — active
 
+### xlings
+
+- [mcpp 对 xlings 的依赖：Provider 端口、归属与位置、上游复用、系统级安装、payload 不可变、文件系统能力与长路径（#809）](2026-10-16-xlings-provider-port-and-shared-store-design.md) — active
+
 ## By date
 
 ### 2026-10
 
+- [mcpp 对 xlings 的依赖：Provider 端口、归属与位置、上游复用、系统级安装、payload 不可变、文件系统能力与长路径（#809）](2026-10-16-xlings-provider-port-and-shared-store-design.md) — active
 - [构建依赖的一条管线：配置与产物两轴、包的实例、库接口、兼容系统与工作空间收尾（#797）](2026-10-11-build-dependencies-one-pipeline-design.md) — active
 - [一处来源，一种含义：工作空间的传递语义、生成输出、模块角色与首次运行（#786、#785、#778、#790）](2026-10-10-one-source-one-meaning-design.md) — landed
 - [LLVM 23.1.3 Part 2：Linux aarch64 默认工具链与 glibc 生态闭环](2026-10-08-llvm-2313-linux-aarch64-ecosystem-part2-design.md) — active

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

@@ -21,7 +21,7 @@ inputs:
   xlings-version:
     description: xlings release to bootstrap from
     required: false
-    # Must equal `pinned::kXlingsVersion` in src/xlings/xlings.cppm — enforced by
+    # Must equal `pinned::kXlingsVersion` in src/provider/xlings/xlings.cppm — enforced by
     # .github/tools/check_version_pins.sh, not by this comment. (The previous
     # comment here listed the files to keep in lock-step, and that list was
     # already incomplete; that is why the check exists.)
@@ -33,7 +33,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.10.10.2'
+    default: '2026.10.16.1'
 
 outputs:
   sandbox-key:

.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.10.10.2'
+    default: '2026.10.16.1'
   image:
     description: >
       The runner label the job runs on (macos-15, xcode-27). It is part of the

.github/tools/check_provider_boundary.py

@@ -0,0 +1,109 @@
+#!/usr/bin/env python3
+"""The provider boundary (.agents/docs/2026-10-16-xlings-provider-port-and-shared-store-design.md §4.3).
+
+mcpp speaks the port's words (mcpp.provider): what xlings' commands, its
+protocol, its home layout and its store naming are is the adapter's
+(src/provider/xlings/), and only the composition root (src/provider/select.cppm)
+names the adapter. Outside them, in src/:
+
+  - no `import mcpp.provider.xlings*`;
+  - none of the layout's spellings in code: "xpkgs", "-x-", "xim-x-",
+    ".xlings.json", "subos", "xim-index-repos", ".mcpp_ok";
+  - a payload path is used as the provider answered it: no canonical /
+    weakly_canonical / remove_all applied to one.
+
+Comments are prose and may name anything; string literals and identifiers
+in code may not. An exception names its reason on the line:
+`// provider-boundary-ok: <why>`.
+
+Exit 0 clean, 1 with the findings listed.
+"""
+from __future__ import annotations
+
+import argparse
+import pathlib
+import re
+import sys
+
+LITERALS = ['"xpkgs"', '/xpkgs', 'xpkgs/', '-x-', 'xim-x-', '.xlings.json', '"subos"', '/subos', 'subos/',
+            'xim-index-repos', '.mcpp_ok', '.mcpp-fixup.json']
+IMPORT = re.compile(r'^\s*(export\s+)?import\s+mcpp\.provider\.xlings\b')
+PAYLOAD_FS = re.compile(r'\b(canonical|weakly_canonical|remove_all)\s*\([^)]*[pP]ayload')
+
+
+def strip_comments(text: str) -> list[str]:
+    """Each line with // and /* */ comments blanked, string literals kept."""
+    out, in_block = [], False
+    for line in text.split("\n"):
+        res, i, in_str = [], 0, None
+        while i < len(line):
+            c = line[i]
+            if in_block:
+                if line.startswith("*/", i):
+                    in_block = False
+                    i += 2
+                    continue
+                i += 1
+                continue
+            if in_str:
+                res.append(c)
+                if c == "\\" and i + 1 < len(line):
+                    res.append(line[i + 1])
+                    i += 2
+                    continue
+                if c == in_str:
+                    in_str = None
+                i += 1
+                continue
+            if line.startswith("//", i):
+                break
+            if line.startswith("/*", i):
+                in_block = True
+                i += 2
+                continue
+            if c in "\"'":
+                in_str = c
+            res.append(c)
+            i += 1
+        out.append("".join(res))
+    return out
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+    ap.add_argument("--root", type=pathlib.Path, default=pathlib.Path(__file__).resolve().parents[2])
+    ROOT = ap.parse_args().root.resolve()
+    SRC = ROOT / "src"
+    ADAPTER = SRC / "provider" / "xlings"
+    ROOT_MODULE = SRC / "provider" / "select.cppm"
+    findings = []
+    for path in sorted(SRC.rglob("*")):
+        if path.suffix not in (".cppm", ".cpp", ".hpp", ".h") or not path.is_file():
+            continue
+        if ADAPTER in path.parents:
+            continue
+        raw = path.read_text(encoding="utf-8", errors="replace").split("\n")
+        code = strip_comments("\n".join(raw))
+        for n, (line, original) in enumerate(zip(code, raw), 1):
+            if "provider-boundary-ok:" in original:
+                continue
+            rel = path.relative_to(ROOT)
+            if IMPORT.match(line) and path != ROOT_MODULE:
+                findings.append(f"{rel}:{n}: imports the adapter; import mcpp.provider.select")
+            for lit in LITERALS:
+                if lit in line:
+                    findings.append(f"{rel}:{n}: names the provider's layout ({lit}): {original.strip()}")
+                    break
+            if PAYLOAD_FS.search(line):
+                findings.append(f"{rel}:{n}: canonicalises or removes a payload: {original.strip()}")
+    if findings:
+        print("provider boundary: " + str(len(findings)) + " finding(s)")
+        for f in findings:
+            print("  " + f)
+        return 1
+    print("provider boundary: clean")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/tools/check_version_pins.sh

@@ -5,13 +5,13 @@
 # Two invariants that used to live only in a comment:
 #
 #   1. Every xlings version pinned anywhere in .github/ equals
-#      `pinned::kXlingsVersion` in src/xlings/xlings.cppm — which is the version
+#      `pinned::kXlingsVersion` in src/provider/xlings/xlings.cppm — which is the version
 #      `mcpp self env` reports and the one release.yml bundles into the
 #      tarball as <install>/registry/bin/xlings.
 #
 #   2. mcpp's own version is identical in all four places that carry it.
 #
-# Why this exists: src/xlings/xlings.cppm used to say "keep in lock-step with the
+# Why this exists: src/provider/xlings/xlings.cppm used to say "keep in lock-step with the
 # XLINGS_VERSION pins in release.yml / cross-build-test.yml / ci-linux-e2e.yml"
 # and that list was ALREADY incomplete — it omitted both composite actions,
 # which sat on 0.4.30 while everything else moved to 0.4.69. CI's sandbox
@@ -38,12 +38,12 @@ strip_comments() { sed 's/#.*//'; }
 
 # ── 1. xlings pins ────────────────────────────────────────────────────────
 
-XLINGS_EXPECTED=$(grep -oE 'kXlingsVersion[[:space:]]*=[[:space:]]*"[^"]+"' src/xlings/xlings.cppm \
+XLINGS_EXPECTED=$(grep -oE 'kXlingsVersion[[:space:]]*=[[:space:]]*"[^"]+"' src/provider/xlings/xlings.cppm \
                   | grep -oE '"[^"]+"' | tr -d '"' | head -1)
 [ -n "$XLINGS_EXPECTED" ] || {
-  echo "FAIL: could not read kXlingsVersion from src/xlings/xlings.cppm" >&2; exit 1; }
+  echo "FAIL: could not read kXlingsVersion from src/provider/xlings/xlings.cppm" >&2; exit 1; }
 
-note "expected xlings pin: $XLINGS_EXPECTED  (src/xlings/xlings.cppm)"
+note "expected xlings pin: $XLINGS_EXPECTED  (src/provider/xlings/xlings.cppm)"
 
 # Anchored patterns only — a bare "version-looking number on a line mentioning
 # xlings" would also match `xlings install llvm@20.1.7`, which pins LLVM, not

.github/tools/run_published_arm64_cn.sh

@@ -12,7 +12,7 @@ base=${XLINGS_HOME:?cold isolated home required}
 mkdir -p "$base/bootstrap" "$base/probes" "$base/reports"
 cd "$base"
 # Derive the client version from the repository's existing single pin.
-xl_version=$(python3 - "$repo/src/xlings/xlings.cppm" <<'PY'
+xl_version=$(python3 - "$repo/src/provider/xlings/xlings.cppm" <<'PY'
 import pathlib,re,sys
 s=pathlib.Path(sys.argv[1]).read_text()
 m=re.search(r'kXlingsVersion\s*=\s*"([0-9.]+)"',s)

.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.10.10.2'
+      XLINGS_VERSION: '2026.10.16.1'
     steps:
       - uses: actions/checkout@v4
 

.github/workflows/ci-bootstrap.yml

@@ -41,7 +41,7 @@ jobs:
         os: [ubuntu-24.04, macos-15, windows-2025]
     env:
       XLINGS_NON_INTERACTIVE: '1'
-      XLINGS_VERSION: '2026.10.10.2'
+      XLINGS_VERSION: '2026.10.16.1'
     steps:
       - uses: actions/checkout@v4
 
@@ -50,7 +50,7 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.10.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.16.1
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
           echo "$HOME/.xlings/bin" >> "$GITHUB_PATH"
 
@@ -124,7 +124,7 @@ jobs:
         shell: bash
         run: |
           set -euo pipefail
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.10.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.16.1
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
 
       - name: Install the newest release and build the tree with it (mcpp build --strict)

.github/workflows/ci-fresh-install.yml

@@ -152,7 +152,7 @@ jobs:
         env:
           XLINGS_NON_INTERACTIVE: '1'
         run: |
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.10.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.16.1
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
 
       - name: Install mcpp and config mirror
@@ -315,7 +315,7 @@ jobs:
 
       - name: Install xlings + mcpp
         run: |
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.10.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.16.1
           # Deliberately NOT writing to $GITHUB_PATH here. On container
           # images that declare no PATH in their config (opensuse/
           # tumbleweed), appending a single dir to GITHUB_PATH makes the
@@ -464,7 +464,7 @@ jobs:
           #             (older ones carry minos=15 and refuse to start).
           #   v0.4.51+: in-process sha256 — this image has no sha256sum
           #             binary, so pinned fetches failed before it.
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.10.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.16.1
           echo "$HOME/.xlings/subos/current/bin" >> "$GITHUB_PATH"
 
       - name: Install mcpp and config mirror

.github/workflows/ci-linux-e2e.yml

@@ -107,6 +107,55 @@ jobs:
           if-no-files-found: warn
           retention-days: 7
 
+  # An MCPP_HOME and a project on NFSv3 (docs/25 §6, #809): the filesystem
+  # whose rename refuses RENAME_NOREPLACE with EINVAL, where `mcpp new` once
+  # failed. mcpp measures what the filesystem does and publishes by it.
+  nfs:
+    name: e2e nfs (NFSv3 home and project)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ./.github/actions/bootstrap-mcpp
+
+      - uses: ./.github/actions/use-built-mcpp
+        with:
+          host: linux-x86_64
+
+      - name: An NFSv3 export of this machine, mounted
+        run: |
+          set -euo pipefail
+          sudo apt-get update -q
+          sudo apt-get install -y --no-install-recommends nfs-kernel-server nfs-common
+          sudo mkdir -p /srv/nfs /mnt/nfs
+          sudo chown "$(id -u):$(id -g)" /srv/nfs
+          echo "/srv/nfs 127.0.0.1(rw,sync,no_subtree_check,no_root_squash)" | sudo tee /etc/exports
+          sudo exportfs -ra
+          sudo systemctl restart nfs-kernel-server
+          sudo mount -t nfs -o vers=3,nolock 127.0.0.1:/srv/nfs /mnt/nfs
+          test "$(stat -f -c %T /mnt/nfs)" = nfs
+
+      - name: A toolchain, a new project, its build and run, all on NFSv3
+        run: |
+          set -euo pipefail
+          export MCPP_HOME=/mnt/nfs/mcpp-home
+          "$MCPP" toolchain install gcc 16.1.0
+          cd /mnt/nfs
+          "$MCPP" new hello
+          cd hello
+          "$MCPP" build
+          "$MCPP" run > "$RUNNER_TEMP/run.log"
+          grep -q 'Hello from hello' "$RUNNER_TEMP/run.log"
+
+      - name: Doctor names the home's filesystem
+        run: |
+          set -euo pipefail
+          export MCPP_HOME=/mnt/nfs/mcpp-home
+          # doctor's exit status reports the machine's health, not this line.
+          "$MCPP" self doctor > "$RUNNER_TEMP/doctor.log" 2>&1 || true
+          grep -q '/mnt/nfs/mcpp-home on nfs' "$RUNNER_TEMP/doctor.log"
+
   # ──────────────────────────────────────────────────────────────────
   # Bare metal: the one chain the sharded suite above cannot be trusted
   # to exercise.
@@ -365,7 +414,7 @@ jobs:
 
       - name: Bootstrap xlings + released mcpp
         run: |
-          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.10.2
+          curl -fsSL https://raw.githubusercontent.com/openxlings/xlings/main/tools/other/quick_install.sh | bash -s v2026.10.16.1
           export PATH="$HOME/.xlings/subos/current/bin:$PATH"
           xlings update
           xlings install mcpp -y -g

.github/workflows/ci.yml

@@ -143,11 +143,15 @@ jobs:
       - name: Reason tokens agree with the engine, and with the mirror
         run: bash .github/tools/check_reason_tokens.sh
 
+      - name: Only the adapter and the composition root name the provider
+        run: python3 .github/tools/check_provider_boundary.py
+
       - name: The tools of the CI stages pass their fixtures
         run: |
           python3 tests/scripts/test_classify_changes.py
           python3 tests/scripts/test_check_e2e_coverage.py
           python3 tests/scripts/test_check_default_toolchain_docs.py
+          python3 tests/scripts/test_check_provider_boundary.py
           python3 tests/scripts/test_native_candidate_admission.py
           python3 -m unittest discover -s tests/scripts -p test_toolchain_env.py
 

.github/workflows/cross-build-test.yml

@@ -115,7 +115,7 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          # Must equal `pinned::kXlingsVersion` (src/xlings/xlings.cppm) and the
+          # Must equal `pinned::kXlingsVersion` (src/provider/xlings/xlings.cppm) and the
           # xlings the release bundles — enforced by
           # .github/tools/check_version_pins.sh.
           #
@@ -131,7 +131,7 @@ jobs:
           # release assets were uploaded in a broken state (records present,
           # blobs missing → 404 on GET); re-uploaded clean. The stale-INDEX
           # half is handled by the marker-clear below.
-          XLINGS_VERSION: '2026.10.10.2'
+          XLINGS_VERSION: '2026.10.16.1'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           bash "$GITHUB_WORKSPACE/.github/tools/fetch_release.sh" \
@@ -323,7 +323,7 @@ jobs:
       - name: Bootstrap mcpp via xlings
         env:
           XLINGS_NON_INTERACTIVE: '1'
-          XLINGS_VERSION: '2026.10.10.2'
+          XLINGS_VERSION: '2026.10.16.1'
         run: |
           tarball="xlings-${XLINGS_VERSION}-linux-x86_64.tar.gz"
           bash "$GITHUB_WORKSPACE/.github/tools/fetch_release.sh" \