docs(packaging): add the 6.0.0 release entry

The release of this push and of everything on master since 5.0.0: lldb,
the Khronos validation layer and the SPIRV-Tools programs in the
Flatpak, --die-with-parent in the README's alias, and the release
.flatpakref with the repository's key in it. Its Breaking item, the end
of beta and of the rolling release, makes it a major.

.forgejo/workflows/ci.yaml

@@ -1,37 +1,52 @@
 name: Flatpak
 
-# One job, three outcomes:
+# One job, two outcomes:
-#   pull request  -> build the Flatpak and run the suite inside it
+#   pull request, manual run -> build the Flatpak and run the suite inside it
-#   push master   -> also publish the result as the `beta` branch of the
+#   pushed tag X.Y.Z         -> also release the build: publish it as the
-#                    Catcrafts repo and refresh the rolling `latest` release
+#                               `stable` branch of the Catcrafts repo and
-#   tag X.Y.Z     -> publish as `stable` and create release X.Y.Z
+#                               create release X.Y.Z
+#
+# A release is a tag that the owner makes and signs locally and pushes with
+# the master it releases; a push to master without one runs nothing. The tag
+# names the version, and the metainfo's newest <release> entry has to be that
+# version: its description is the release notes.
 #
 # The `crafter-flatpak` runner label is the privileged runner on the Hetzner
 # box (bubblewrap needs it) with four volumes allowed: the Sdk install, the
 # flatpak-builder state (ccache and the LLVM module, so only crafter-build
 # itself rebuilds on a normal run), the published repo's web root, and the
 # repo signing key, which lives on the runner host and never in the forge.
-# No other runner carries that label. Plain `flatpak` also matches the
+# No other runner carries that label. Plain `flatpak` is the label of the
-# organisation's runner, which mounts none of those volumes; a job it picks
+# organisation's runner, which serves every Catcrafts repository and also
-# up fails before building anything.
+# mounts the web root and the key, for Crafter.Review's publish job, so any
+# job it runs can mount them (AGENTS.template.md, CI and publishing).
 on:
   pull_request:
     branches: [master]
   push:
-    branches: [master]
     # Bare semver tags. Spelled with globs so it means the same whether the
-    # forge reads it as a workflow pattern or as a plain glob; `latest`, the
+    # forge reads it as a workflow pattern or as a plain glob.
-    # rolling tag this workflow moves itself, does not start with a digit.
     tags: ['[0-9]*.[0-9]*.[0-9]*']
   workflow_dispatch:
 
+# Pushes are tags only, so every release run is in one group, and a release
+# starts only once the one before it has finished. A pull request's group
+# also holds its number, which only a pull request's event carries, so a
+# new push to it cancels its own outdated run and no other.
+concurrency:
+  group: flatpak-${{ github.event_name }}-${{ github.event.pull_request.number }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
 env:
   APP_ID: net.catcrafts.CrafterBuild
+  BRANCH: stable
   MANIFEST: packaging/flatpak/net.catcrafts.CrafterBuild.yaml
   CI_MANIFEST: packaging/flatpak/ci-manifest.yaml
   RUNTIME: org.freedesktop.Sdk//26.08
   REPO_DIR: /srv/flatpak/repo
   WEB_DIR: /srv/flatpak
+  # A release tag carries a signature Forgejo verifies for this address.
+  RELEASE_SIGNER: jorijnvdgraaf@catcrafts.net
 
 jobs:
   flatpak:
@@ -45,11 +60,12 @@ jobs:
         -v /etc/crafter-flatpak:/run/crafter-flatpak:ro
     steps:
       - name: Install tools
+        # util-linux: flock, for the Publish step.
         run: |
           pacman-key --init
           pacman-key --populate archlinux
           pacman -Sy --noconfirm --needed archlinux-keyring
-          pacman -Syu --noconfirm --needed flatpak flatpak-builder ccache git nodejs jq gnupg go-yq ostree python
+          pacman -Syu --noconfirm --needed flatpak flatpak-builder ccache git nodejs jq gnupg go-yq ostree python util-linux
           git config --global --add safe.directory '*'
 
       - name: Sdk
@@ -60,40 +76,137 @@ jobs:
           flatpak update -y --noninteractive
 
       - name: Checkout
+        # Every branch and tag, for git describe and the release checks; no
+        # step pushes, so the token is not kept in the checkout.
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          persist-credentials: true
+          persist-credentials: false
 
-      - name: Version and channel
+      - name: Version
         id: meta
         run: |
           set -eu
-          if [ "${GITHUB_REF_TYPE}" = tag ]; then
+          # The metainfo's newest entry is its first <release> element, the
-            version="$GITHUB_REF_NAME"
+          # one parse that gives both its version and the release notes,
-            branch=stable
+          # before anything is built: a comment or another attribute order
-            # The metainfo's newest release is the release notes and must be
+          # would mislead a text search, and an entry whose notes render
-            # the version being tagged.
+          # empty stops the run here. The notes go to release-notes.md, for
-            top=$(grep -m1 -oP '<release version="\K[^"]+' packaging/flatpak/net.catcrafts.CrafterBuild.metainfo.xml)
+          # the release page, as Markdown. AppStream has no headings, so a
-            if [ "$top" != "$version" ]; then
+          # paragraph that introduces a list is one: <p>New</p><ul>...</ul>
-              echo "metainfo lists $top as the newest release, but the tag is $version" >&2
+          # comes out as "## New" over its items, the shape the notes take
+          # since 3.0.0. A paragraph on its own stays a paragraph, as the
+          # older entries are written. <em> and <code> get their Markdown
+          # spelling; a code span also keeps text such as lib/<triple>/eh
+          # from being read as an HTML tag by the forge.
+          newest=$(python3 - <<'EOF'
+          import sys
+          import xml.etree.ElementTree as ET
+
+          release = ET.parse("packaging/flatpak/net.catcrafts.CrafterBuild.metainfo.xml").getroot().find("releases/release")
+          desc = None if release is None else release.find("description")
+
+          def text(el):
+              parts = [el.text or ""]
+              for child in el:
+                  inner = text(child)
+                  parts.append({"em": f"*{inner}*", "code": f"`{inner}`"}.get(child.tag, inner))
+                  parts.append(child.tail or "")
+              return " ".join("".join(parts).split())
+
+          blocks = [] if desc is None else list(desc)
+          out = []
+          for i, el in enumerate(blocks):
+              heads_list = i + 1 < len(blocks) and blocks[i + 1].tag in ("ul", "ol")
+              if el.tag == "p":
+                  out.append(f"## {text(el)}" if heads_list else text(el))
+              elif el.tag == "ul":
+                  out.append("\n".join(f"- {text(li)}" for li in el))
+              elif el.tag == "ol":
+                  out.append("\n".join(f"{n}. {text(li)}" for n, li in enumerate(el, 1)))
+          notes = "\n\n".join(out)
+          if not notes.strip():
+              sys.exit("the metainfo needs a <release> at the top of <releases> whose <description> renders release notes")
+          with open("release-notes.md", "w") as f:
+              print(notes, file=f)
+          print(release.get("version", ""))
+          EOF
+          )
+          if [ "$GITHUB_EVENT_NAME" = push ]; then
+            # A release: the only pushes this workflow runs for are tags.
+            # The tag is the version; it has to be annotated, signed by the
+            # owner as Forgejo verifies it against the keys its users added,
+            # on master, newer than every published release, and the version
+            # of the metainfo's newest entry. The tag itself is read from the
+            # forge: the checkout fetches a pushed tag again as a plain ref
+            # to its commit, so the local one is never the annotated tag.
+            version=$GITHUB_REF_NAME
+            if ! printf '%s\n' "$version" | grep -qxE '[0-9]+\.[0-9]+\.[0-9]+'; then
+              echo "the tag $version is not a version of the form X.Y.Z" >&2
+              exit 1
+            fi
+            api="$GITHUB_SERVER_URL/api/v1/repos/$GITHUB_REPOSITORY"
+            tag=$(curl -sSf "$api/tags/$version")
+            object=$(printf '%s' "$tag" | jq -r .id)
+            commit=$(printf '%s' "$tag" | jq -r .commit.sha)
+            if [ "$commit" != "$GITHUB_SHA" ]; then
+              echo "the forge has the tag $version on $commit, not on this run's commit $GITHUB_SHA" >&2
+              exit 1
+            fi
+            if [ "$object" = "$commit" ]; then
+              echo "$version is a lightweight tag; a release tag is annotated and signed: git tag -s $version -m 'crafter-build $version'" >&2
+              exit 1
+            fi
+            # Forgejo verifies a signed tag's own signature, and for an
+            # unsigned one falls back to its commit's, so the verdict also
+            # has to cover the tag's payload, not the commit's.
+            signed=$(curl -sSf "$api/git/tags/$object" |
+              jq -r --arg c "$commit" --arg v "$version" '"\(.verification.verified) \(.verification.signer.email // "") \(.verification.payload // "" | startswith("object \($c)\ntype commit\ntag \($v)\n"))"')
+            if [ "$signed" != "true $RELEASE_SIGNER true" ]; then
+              echo "Forgejo does not verify the tag $version itself as signed by $RELEASE_SIGNER (verified, signer, over the tag's payload: $signed)" >&2
+              exit 1
+            fi
+            if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/master; then
+              echo "the tag $version is on $(git rev-parse --short "$GITHUB_SHA"), which is not on master: push the tag with the master it releases" >&2
+              exit 1
+            fi
+            # Newer than every release the forge has published, its own
+            # included, and not every tag: a later tag whose run still
+            # queues behind this one has no release yet, and a tag that is
+            # no X.Y.Z version never gets one.
+            for t in $(git tag --list | awk '/^[0-9]+\.[0-9]+\.[0-9]+$/' | sort -V); do
+              [ "$(printf '%s\n%s\n' "$t" "$version" | sort -V | tail -n 1)" = "$t" ] || continue
+              code=$(curl -s -o /dev/null -w '%{http_code}' "$api/releases/tags/$t")
+              case "$code" in
+                404) ;;
+                200)
+                  if [ "$t" = "$version" ]; then
+                    echo "$version is released already; to re-run after a release left half made, delete that release first" >&2
+                  else
+                    echo "$version is not newer than the release $t" >&2
+                  fi
+                  exit 1 ;;
+                *) echo "the forge answered $code when asked whether $t is released" >&2; exit 1 ;;
+              esac
+            done
+            if [ "$newest" != "$version" ]; then
+              echo "the metainfo's newest release is \"$newest\", but the tag is $version: the tagged commit needs the <release> entry for $version at the top of packaging/flatpak/net.catcrafts.CrafterBuild.metainfo.xml" >&2
               exit 1
             fi
           else
-            # A master build names itself after the release it follows, the
+            # Nothing is published. The build names itself after the
-            # way a local checkout does: 2.0.0-3-g21746b1 is three commits
+            # release it follows, the way a local checkout does:
-            # past 2.0.0. Before the first tag there is nothing to describe
+            # 5.0.0-3-g21746b1 is three commits past 5.0.0. Before the first
-            # from and the bare hash gets a placeholder in front.
+            # tag there is nothing to describe from and the bare hash gets a
-            described=$(git describe --tags --always --exclude=latest)
+            # placeholder in front.
+            described=$(git describe --tags --always)
             case "$described" in
               [0-9]*.[0-9]*.[0-9]*) version="$described" ;;
               *) version="0.0.0-dev+$described" ;;
             esac
-            branch=beta
           fi
           echo "version=$version" >> "$GITHUB_OUTPUT"
-          echo "branch=$branch" >> "$GITHUB_OUTPUT"
+          echo "version $version"
-          echo "version $version, flatpak branch $branch"
 
       - name: Build
         # The manifest is rewritten beside the original so its relative
@@ -106,7 +219,7 @@ jobs:
           grep -n 'CRAFTER_BUILD_VERSION' "$CI_MANIFEST"
           flatpak-builder --force-clean --ccache --disable-rofiles-fuse \
             --state-dir=/root/.cache/flatpak-builder \
-            --repo=repo --default-branch="${{ steps.meta.outputs.branch }}" \
+            --repo=repo --default-branch="$BRANCH" \
             build-dir "$CI_MANIFEST"
 
       - name: Smoke test
@@ -114,18 +227,16 @@ jobs:
           flatpak-builder --run build-dir "$CI_MANIFEST" crafter-build --version
           flatpak-builder --run build-dir "$CI_MANIFEST" sh -c 'cd examples/hello-world && crafter-build && ls bin/*/hello*'
 
-      # Everything below publishes and only runs on master and on tags.
+      # Everything below releases the build and runs only for a pushed tag.
       - name: Bundle
-        if: github.event_name != 'pull_request'
+        if: github.event_name == 'push'
         run: |
           mkdir -p dist
-          flatpak build-bundle repo "dist/crafter-build-${{ steps.meta.outputs.version }}.flatpak" "$APP_ID" "${{ steps.meta.outputs.branch }}"
+          flatpak build-bundle repo "dist/crafter-build-${{ steps.meta.outputs.version }}.flatpak" "$APP_ID" "$BRANCH"
-          cp packaging/flatpak/net.catcrafts.CrafterBuild.flatpakref dist/
-          (cd dist && sha256sum * > SHA256SUMS)
           ls -la dist
 
       - name: Upload bundle
-        if: github.event_name != 'pull_request'
+        if: github.event_name == 'push'
         uses: actions/upload-artifact@v3
         with:
           name: crafter-build-${{ steps.meta.outputs.version }}
@@ -133,7 +244,7 @@ jobs:
           if-no-files-found: error
 
       - name: Publish to the Catcrafts repo
-        if: github.event_name != 'pull_request'
+        if: github.event_name == 'push'
         run: |
           set -eu
           # The signing key is generated once on the runner host
@@ -146,6 +257,11 @@ jobs:
           export GNUPGHOME=$(mktemp -d)
           gpg --batch --quiet --import /run/crafter-flatpak/signing-key.asc
           FLATPAK_GPG_KEY_ID=$(cat /run/crafter-flatpak/key-id)
+          # Crafter.Review's workflow publishes into the same repo and holds
+          # this lock while it does, so a commit and the summary update of
+          # one workflow never interleave with the other's.
+          exec 9> "$WEB_DIR/.publish.lock"
+          flock 9
           # The live repo is the canonical copy; builds are promoted into it,
           # never built into it.
           # Keyed on the repo's config file, not the directory: the web root
@@ -153,80 +269,49 @@ jobs:
           [ -f "$REPO_DIR/config" ] || ostree init --repo="$REPO_DIR" --mode=archive
           flatpak build-commit-from --src-repo=repo \
             --gpg-sign="$FLATPAK_GPG_KEY_ID" --gpg-homedir="$GNUPGHOME" \
-            "$REPO_DIR" "app/$APP_ID/x86_64/${{ steps.meta.outputs.branch }}"
+            "$REPO_DIR" "app/$APP_ID/x86_64/$BRANCH"
+          # Every push to master used to be published as `beta`. Its last
+          # build is marked end-of-life, once, so that the next
+          # `flatpak update` of a beta installation says why nothing follows.
+          # The reason names the branch: with --noninteractive, flatpak's
+          # message names only the app.
+          beta="app/$APP_ID/x86_64/beta"
+          if ostree rev-parse --repo="$REPO_DIR" "$beta" >/dev/null 2>&1 &&
+             ! ostree show --repo="$REPO_DIR" --print-metadata-key=ostree.endoflife "$beta" >/dev/null 2>&1; then
+            flatpak build-commit-from --src-ref="$beta" \
+              --end-of-life="The beta branch gets no more updates: every change now comes as a release on the stable branch. Install stable with flatpak install catcrafts net.catcrafts.CrafterBuild//stable, then remove beta with flatpak uninstall net.catcrafts.CrafterBuild//beta." \
+              --gpg-sign="$FLATPAK_GPG_KEY_ID" --gpg-homedir="$GNUPGHOME" \
+              "$REPO_DIR" "$beta"
+          fi
           flatpak build-update-repo --gpg-sign="$FLATPAK_GPG_KEY_ID" --gpg-homedir="$GNUPGHOME" \
             --generate-static-deltas --prune "$REPO_DIR"
           # The repo description and the app ref carry the public key.
           key=$(gpg --export "$FLATPAK_GPG_KEY_ID" | base64 --wrap=0)
           sed "s|GPGKey=.*|GPGKey=$key|" packaging/flatpak/catcrafts.flatpakrepo > "$WEB_DIR/catcrafts.flatpakrepo"
           sed "s|GPGKey=.*|GPGKey=$key|" packaging/flatpak/net.catcrafts.CrafterBuild.flatpakref > "$WEB_DIR/net.catcrafts.CrafterBuild.flatpakref"
+          flock -u 9
+          # The release attaches this .flatpakref, not the one in the
+          # checkout: that one has a placeholder where the key goes, and
+          # flatpak cannot install from it.
+          cp "$WEB_DIR/net.catcrafts.CrafterBuild.flatpakref" dist/
+          (cd dist && sha256sum * > SHA256SUMS)
+          ls -la dist
 
-      - name: Rolling 'latest' release
-        if: github.event_name != 'pull_request' && github.ref_type != 'tag'
-        run: |
-          git config user.email "ci@catcrafts.net"
-          git config user.name "Crafter Build CI"
-          git tag -f latest
-          git push origin latest --force
-      - name: Publish rolling 'latest' release
-        if: github.event_name != 'pull_request' && github.ref_type != 'tag'
-        uses: https://code.forgejo.org/actions/forgejo-release@v2
-        with:
-          direction: upload
-          url: ${{ github.server_url }}
-          repo: ${{ github.repository }}
-          tag: latest
-          title: Latest master build
-          prerelease: true
-          override: true
-          release-dir: dist
-          token: ${{ secrets.GITHUB_TOKEN }}
-
-      - name: Release notes
-        if: github.ref_type == 'tag'
-        run: |
-          # The newest <release> block's description as Markdown, for the
-          # release page. AppStream has no headings, so a paragraph that
-          # introduces a list is one: <p>New</p><ul>...</ul> comes out as
-          # "## New" over its items, the shape the notes take since 3.0.0.
-          # A paragraph on its own stays a paragraph, as the older entries
-          # are written. <em> and <code> get their Markdown spelling; a code
-          # span also keeps text such as lib/<triple>/eh from being read as
-          # an HTML tag by the forge.
-          python3 - > release-notes.md <<'EOF'
-          import xml.etree.ElementTree as ET
-
-          desc = ET.parse("packaging/flatpak/net.catcrafts.CrafterBuild.metainfo.xml").getroot().find("releases/release/description")
-
-          def text(el):
-              parts = [el.text or ""]
-              for child in el:
-                  inner = text(child)
-                  parts.append({"em": f"*{inner}*", "code": f"`{inner}`"}.get(child.tag, inner))
-                  parts.append(child.tail or "")
-              return " ".join("".join(parts).split())
-
-          blocks = list(desc)
-          out = []
-          for i, el in enumerate(blocks):
-              heads_list = i + 1 < len(blocks) and blocks[i + 1].tag in ("ul", "ol")
-              if el.tag == "p":
-                  out.append(f"## {text(el)}" if heads_list else text(el))
-              elif el.tag == "ul":
-                  out.append("\n".join(f"- {text(li)}" for li in el))
-              elif el.tag == "ol":
-                  out.append("\n".join(f"{n}. {text(li)}" for n, li in enumerate(el, 1)))
-          print("\n\n".join(out))
-          EOF
       - name: Publish release
-        if: github.ref_type == 'tag'
+        if: github.event_name == 'push'
+        # The notes are release-notes.md, which the Version step wrote. No
+        # `override`: it would delete a tag that has moved off this commit
+        # since the Version step and tag the old commit instead. Without it
+        # the action refuses such a tag, and a release that an earlier
+        # attempt left half made, such as a draft whose upload failed, has
+        # to be deleted before a re-run.
         uses: https://code.forgejo.org/actions/forgejo-release@v2
         with:
           direction: upload
           url: ${{ github.server_url }}
           repo: ${{ github.repository }}
-          tag: ${{ github.ref_name }}
+          tag: ${{ steps.meta.outputs.version }}
-          title: crafter-build ${{ github.ref_name }}
+          title: crafter-build ${{ steps.meta.outputs.version }}
           release-notes-file: release-notes.md
           release-dir: dist
           token: ${{ secrets.GITHUB_TOKEN }}

.gitignore

@@ -7,3 +7,5 @@ share/crafter-build/
 packaging/flatpak/ci-manifest.yaml
 # written by every build and test run from AGENTS.template.md
 /AGENTS.md
+.review-gates/push/
+.review-gates/trees/

.review-gates/config.json

@@ -0,0 +1,38 @@
+{
+  "base": "origin/master",
+  "rangeFrom": "upstream",
+  "authors": [
+    "jorijnvdgraaf@catcrafts.net"
+  ],
+  "aiTrailers": "forbid",
+  "requireSigned": true,
+  "lenses": {
+    "repo-better-solution": {
+      "section": ".review-gates/lenses/repo-better-solution.md"
+    },
+    "repo-bug-prover": {
+      "section": ".review-gates/lenses/repo-bug-prover.md"
+    },
+    "repo-facts": {
+      "section": ".review-gates/lenses/repo-facts.md"
+    }
+  },
+  "modes": {
+    "commits": {
+      "kind": "commits",
+      "lenses": [
+        "repo-better-solution",
+        "repo-bug-prover",
+        "repo-facts"
+      ],
+      "effort": "xhigh"
+    }
+  },
+  "gate0": [
+    "./build.sh",
+    "./bin/crafter-build",
+    "./bin/crafter-build test",
+    "./bin/crafter-build format --check",
+    "./bin/crafter-build lint"
+  ]
+}

.review-gates/lenses/repo-better-solution.md

@@ -0,0 +1,42 @@
+## This repository: Crafter.Build
+
+A C++26 modules build system that builds itself. The stated design is
+`README.md` (the manual) and `AGENTS.template.md` (the contributor guide;
+`AGENTS.md` is written from it by a crafter-build build or test run, not
+by `build.sh`, and is not in the tree).
+Its "Design rules" and "Security considerations" are the owner's
+decisions: a range that departs from one without saying so is a finding;
+whether one should change is the owner's call, not a defect of the range.
+Among them, for CI, which holds the workflow's token and the signing key
+its runner mounts: no secret is added to the workflow, and the
+environment is never echoed in it.
+
+The layers: the library (`interfaces/`, `implementations/`), which the
+executable wraps and every `project.cpp` is compiled against; this
+repository's own `project.cpp`; `build.sh`, the bootstrap that builds the
+tool without the tool; the Flatpak (`packaging/flatpak/`), which bundles
+the LLVM users build with; CI (`.forgejo/workflows/ci.yaml`). A target
+difference branches on `cfg.target` at run time, never on the host; an
+output path goes through `BinDir()`, `BuildDir()` or `PcmDir()`; whatever
+changes what gets compiled or bundled reaches `VariantId()`.
+
+Search first: the partitions' own helpers (`RunBuildCommand`,
+`RunCommandChecked`, `Progress::Diagnostic`, `ApplyStandardArgs`,
+`HostTarget`, `GitProject`, `LocalProject`); the Crafter.* libraries the
+tree already uses, cloned under `~/.cache/crafter.build/external/`; libc++
+and clang as the host installs them (`/run/host/usr/include/c++/v1`,
+`/run/host/usr/lib/clang/`); git, cmake and flatpak-builder.
+
+Commit shape here: a fix, its test and its README change are separate
+commits when each stands on its own, in that order, and a bug fix ships
+with a test that fails before it. That split is not a later commit
+repairing an earlier one.
+
+Compatibility: the `project.cpp` of every sibling repository beside this
+checkout (`../Crafter.*/project.cpp`) and of every user compiles against
+what `interfaces/` exports and is loaded by the binary; the CLI, the
+`CRAFTER_BUILD_*` variables, the cache an older version left under
+`~/.cache/crafter.build/` and the `bin/` layout CI globs are contracts too.
+Users get master through releases on the Flatpak's `stable` branch. A
+change an existing `project.cpp` does not survive is a
+finding unless the range documents, in the README, what users must change.

.review-gates/lenses/repo-bug-prover.md

@@ -0,0 +1,46 @@
+## This repository: Crafter.Build
+
+The execution contexts to enumerate, beside the charter's:
+- `project.cpp` is compiled to a shared object and loaded into the running
+  crafter-build, resolving `Crafter::` symbols from the executable
+  (`--export-dynamic`); its static initialisers run at load. Its sibling
+  projects (`GitProject`, `LocalProject`) load the same way into the same
+  process, and its `#pragma crafter dependency` targets are built for the
+  host first, on every load.
+- The clang++, clang and llvm-ar the tool spawns, and the git and cmake it
+  runs, are shell commands (`popen`, `std::system` in `:Platform`), many in
+  parallel; such a step fails on its exit code, never because it printed.
+  Running a test or a built artifact is a shell command too (`:Test`,
+  `:Clang`). A path, file name or flag that reaches one with a space or a
+  shell metacharacter in it is an input to attack. Other steps run inside
+  the process, among them glslang's shader compiles, on a thread of their
+  own per stale shader (`:Shader`), and lint's parse through the libclang
+  the linter dlopens (`:Lint`).
+- Several crafter-build processes share `~/.cache/crafter.build/` at once:
+  the std and Crafter.Build PCMs per target and march (the
+  `ConcurrentCacheRace` test), and the external clones with their `.lock`
+  files.
+- Three builds of the tool: the bootstrap from `build.sh` (without
+  `CRAFTER_BUILD_HAS_ASSET`), the self-hosted binary on the host's LLVM, and
+  the Flatpak on its own LLVM under `/app`, in a sandbox whose `/usr` is the
+  Freedesktop SDK's. Their toolchains can be a release apart.
+- Targets: the host triple, a sysroot (aarch64, musl), `x86_64-w64-mingw32`
+  under wine, `wasm32-wasi*` under wasmtime (or wasmer for `-r`), and
+  browser builds through the runtime in `wasi-runtime/`.
+- Incremental builds: a first build, a rebuild after an edit, a rebuild
+  after a toolchain or flag change and a build after `clean` start from
+  different states; whatever changes what gets compiled has to reach
+  `VariantId()`, or a stale artifact is reused.
+- Tests: each its own subprocess, in parallel, with a 60 s timeout. A test
+  that edits or touches files stages a copy under
+  `fs::temp_directory_path()`; one that only builds its fixture builds it in
+  place, into the fixture's own `bin/` and `build/` in the checkout.
+
+Semantics to read on disk rather than recall: libc++ and clang as the host
+installs them (`/run/host/usr/include/c++/v1`,
+`/run/host/usr/share/libc++/v1/std.cppm`,
+`/run/host/usr/lib/clang/<major>/include`), the dependencies as cloned
+(`~/.cache/crafter.build/external/<Name>-<hash>/`), the vendored
+`lib/DirStackFileIncluder.h`. The Flatpak's own LLVM is not readable from
+here: a semantic that may differ between LLVM releases is unverified for
+the Flatpak build.

.review-gates/lenses/repo-facts.md

@@ -0,0 +1,18 @@
+## This repository: Crafter.Build
+
+- A claim that a tree passes `build.sh`, the self-host build, the test
+  suite, `format --check` or `lint` traces to the Gate 0 log among the
+  evidence paths INPUTS names: each command with its exit code and the sha
+  it ran at. A claim of a run anywhere else (the Flatpak through
+  `run flatpak`, CI, wine, qemu, node, a browser) traces to a capture of
+  that run that names the commit, or is unverifiable.
+- A test a message names exists as a `cfg.AddTest("<Name>")` line in
+  `project.cpp` and a `tests/<Name>/main.cpp` whose checks pin what the
+  message says.
+- `AGENTS.md` is generated from `AGENTS.template.md` and the dependencies'
+  `AGENTS.consumer.md` and is not in the tree: a claim about it is checked
+  against those sources.
+- A `<release>` entry in
+  `packaging/flatpak/net.catcrafts.CrafterBuild.metainfo.xml` is the
+  release notes users read: every sentence in it is a claim about the code
+  since the previous tag.

AGENTS.template.md

@@ -19,6 +19,7 @@ crafter-build is a C++26 modules build system. A project is described by a `proj
 | `lib/` | Vendored third-party headers (nlohmann/json, glslang's DirStackFileIncluder). Do not edit. |
 | `share/crafter-build/`, `bin/`, `build/`, `lib/*.a` | Generated and gitignored. |
 | `packaging/flatpak/`, `.forgejo/workflows/ci.yaml` | The Flatpak manifest with its metainfo, repo and ref files, and the Forgejo Actions CI that builds and publishes it. |
+| `.review-gates/` | The pre-push review's `config.json` and this repository's lens sections (`lenses/`), read by Crafter.Review. Its `push/` and `trees/` are generated and gitignored. |
 
 Partitions and what they own:
 
@@ -50,7 +51,7 @@ Three things to know about this loop:
 - Changes under `implementations/` are picked up by the self-host build and by the tests, which link the local library. Changes under `interfaces/` are not: the harness compiles against the copies in `share/crafter-build/` and the PCM cache built from them, so a new or changed declaration is invisible until you run `./build.sh` again. The symptom is `use of undeclared identifier` for the symbol you just added. A changed default member initialiser has no symptom at all: `project.cpp` compiles against the old one and quietly gets the old default, as `project.cpp`'s sibling loads do with a harness that predates `GitProjectSpec::args = ProjectArgs()`.
 - A new exported symbol that a `project.cpp` reaches on its default path also needs `./build.sh`: the old binary does not export it, and `LoadProject` fails with an undefined symbol.
 
-`./build.sh` clones and builds glslang on first run and takes several minutes; later runs are faster. `./bin/crafter-build clean` deletes `bin/` and `build/` without loading `project.cpp`. That takes `bin/crafter-build` itself with it, and `build/flatpak`, the state of the local Flatpak build (see "CI and publishing"): about 2 GB, and the next `run flatpak` rebuilds LLVM. Set `CRAFTER_BUILD_HOME` only when running a binary from outside this tree; `CRAFTER_BUILD_MARCH` and `CRAFTER_BUILD_MTUNE` default to `native`.
+`./build.sh` clones and builds glslang on first run and takes several minutes; later runs are faster. `./bin/crafter-build clean` deletes `bin/` and `build/` without loading `project.cpp`. That takes `bin/crafter-build` itself with it, and `build/flatpak`, the state of the local Flatpak build (see "CI and publishing"): about 4 GB after a first run, and the next `run flatpak` rebuilds LLVM. Set `CRAFTER_BUILD_HOME` only when running a binary from outside this tree; `CRAFTER_BUILD_MARCH` and `CRAFTER_BUILD_MTUNE` default to `native`.
 
 ## Build, test and style commands
 
@@ -68,7 +69,7 @@ Three things to know about this loop:
 ./bin/crafter-build clean
 ```
 
-Before you call a change done, all three must exit 0: `format` (then re-read your diff), `lint`, `test`. CI runs `./build.sh` and `crafter-build test` on every PR; its lint step is currently commented out, so lint is enforced only by you. Failed, crashed and timed-out tests leave their output in `build/test-logs/<name>.log`.
+Before you call a change done, all three must exit 0: `format` (then re-read your diff), `lint`, `test`. CI runs `./build.sh` and `crafter-build test` for every release tag, every pull request into `master` and every manual run, and has no lint step, so lint is enforced only by you. Failed, crashed and timed-out tests leave their output in `build/test-logs/<name>.log`.
 
 ## Testing instructions
 
@@ -131,17 +132,20 @@ These were decided deliberately. Do not undo them without the maintainer's say-s
 5. **Convention over configuration.** Lead with the zero-config path. Env var, then CLI flag, then full `project.cpp` are the escalation, not the entry point.
 6. **One skip mechanism** (runner probe plus exit 77) and **one `TestRunner` shape** (template fields with `{bin}`, `{bundle}` and similar placeholders; `Cmd(...)` covers any wrapper). Do not add a special-case runner class or a hardcoded "skip on this OS" branch.
 7. **The house-style rules stay in their own repo.** They are not library API of crafter-build and are not forced on downstream projects.
-8. **Fix warts inline; do not stack workarounds.** The previous version of this tool died of accumulated hacks. If a change needs a shortcut, say so in the PR rather than hiding it.
+8. **Fix warts inline; do not stack workarounds.** The previous version of this tool died of accumulated hacks. If a change needs a shortcut, say so in its commit message rather than hiding it.
 9. **`project.cpp` keeps the library/executable split.** `crafter.build-lib` owns the sources, dependencies and glslang; `crafter.build-exe` is `main.cpp` plus link flags.
 10. **Host-tooling builds** (the target of a `#pragma crafter dependency`) get `-fPIC` and the host triple scoped to that build. Keep it scoped.
 
-## Commit and PR guidelines
+## Commit and push guidelines
 
-- Branch from `master` and open the PR against `master` on the project's Forgejo at `forgejo.catcrafts.net/Catcrafts/Crafter.Build`. Issue work uses `claude/issue-<n>` branch names. Pushes go over SSH; HTTPS push is disabled on the server.
+- Branch from `master`; issue work uses `claude/issue-<n>` branch names. Once the owner approves its frozen hash, a range goes straight to `master` on the project's Forgejo at `forgejo.catcrafts.net/Catcrafts/Crafter.Build`, as a fast-forward push with no merge commit and no pull request; open a pull request against `master` only when the owner asks for one. If `master` has moved since the freeze, rebase onto it, then freeze and review the rebased range again. Pushes go over SSH; HTTPS push is disabled on the server.
 - Subject line: `type(scope): imperative summary`, with `feat`, `fix`, `refactor`, `docs` or `test`; the scope (`lint`, `incremental`, ...) is optional. Body: what was wrong, why, and why the fix has this shape, wrapped at about 75 columns. Read `git log` for the voice.
 - Separate commits for the fix, its test and the README change when each stands on its own.
-- Update the README in the same PR when user-visible behaviour changes.
+- Update the README in the same push when user-visible behaviour changes.
-- `format`, `lint` and `test` green before pushing. CI builds the Flatpak and runs the suite inside it on PRs, publishes the `beta` branch of the Catcrafts repo on every push to `master`, and the `stable` branch plus a release on an `X.Y.Z` tag.
+- `format`, `lint` and `test` green before pushing. CI builds the Flatpak and runs the suite inside it for every release tag, every pull request into `master` and every manual run. Without a pull request, CI does not run on a range before it reaches `master` unless someone starts it by hand (`workflow_dispatch`), so the review's gate0, the commands in `.review-gates/config.json`, is the check before the push.
+- Every push to `master` is a release, made by the signed tag pushed with it (see "CI and publishing"). Every pushed range adds a `<release>` entry for its version at the top of `packaging/flatpak/net.catcrafts.CrafterBuild.metainfo.xml`, in a commit of its own (`docs(packaging): add the X.Y.Z release entry`), dated the day of the push in UTC. Its notes have up to three sections, `<p>New</p>`, `<p>Fixes</p>` and `<p>Breaking</p>` in that order, each followed by a `<ul>` of its items, the most important first, and nothing after the last section. The version follows from them: a Breaking section makes it a major, New items a minor, and Fixes alone a patch. Once the owner has approved the frozen hash, the commit `master` is to receive gets the signed tag of that version, made locally, and both go out in one push: `git tag -s X.Y.Z -m 'crafter-build X.Y.Z'`, then `git push --atomic origin HEAD:master X.Y.Z`. That commit is the range's last one, or, when the owner asks for a pull request instead, the merge of the reviewed branch into `master`.
+- Every push of new commits goes through Crafter.Review's pre-push review first, and goes out only once the owner approves the frozen hash. Run `flatpak run net.catcrafts.CrafterReview init` once in a fresh checkout or worktree: it writes the `/prepush` skill that drives the review, and the skill stays untracked. `freeze` refuses merge commits: a range reaches `master` as a fast-forward, and when the owner asks for a pull request instead, the merge of the reviewed branch into `master` is pushed without a freeze of its own.
+- Every commit of a pushed range is GPG-signed, has `jorijnvdgraaf@catcrafts.net` as its author and committer, and carries no AI attribution trailer in its message, neither `Co-Authored-By:` nor `Assisted-by:`. `freeze` refuses a range with a commit that breaks any of these (`requireSigned`, `authors` and `aiTrailers` in `.review-gates/config.json`).
 - Never commit `bin/`, `build/`, `share/crafter-build/`, `lib/*.a`, `AGENTS.md` or fixture build outputs (all gitignored), and never edit the vendored files in `lib/`.
 - Keep `CRAFTER_BUILD_MARCH=x86-64-v2` in the manifest for the shipped binary: it has to run on any x86_64 machine. User projects still default to `native`.
 
@@ -152,14 +156,14 @@ These were decided deliberately. Do not undo them without the maintainer's say-s
 - `--runner=cmd:<command>` executes the named wrapper around every test binary. Wrappers come from `--runner=` or `CRAFTER_BUILD_RUNNER_*`; do not hardcode hosts, wrappers or credentials in `project.cpp` or tests.
 - `crafter-build run <name>` executes whatever the script does, with your permissions. Only the scripts of the project crafter-build was pointed at can be run, never a dependency's; keep it that way.
 - The linter loads `libclang` at runtime by name. `CRAFTER_BUILD_LIBCLANG` pins an exact path and must fail loudly when wrong, never fall back to another library.
-- CI force-pushes the rolling `latest` tag and publishes a prerelease on every push to `master` with the workflow's own token, and signs the Flatpak repo with the key mounted from the runner host. Do not add secrets to the workflow or echo the environment in it.
+- CI creates a release for each release tag with the workflow's own token, pushes nothing to git, and signs the Flatpak repo with the key mounted from the runner host. Do not add secrets to the workflow or echo the environment in it.
 - Tests write only under `fs::temp_directory_path()` and the fixture's own `bin/` and `build/`. Keep it that way.
 
 ## CI and publishing
 
-`.forgejo/workflows/ci.yaml` runs on the `crafter-flatpak` runner label: a dedicated privileged forgejo-runner on the Hetzner box (`forgejo-runner-flatpak.service`, config `/etc/forgejo-runner/config-flatpak.yaml`), registered to this repository only and the only runner with that label. It is privileged because bubblewrap inside the job container needs it, and separate from the other runners so that privilege is not shared with any other repository. Its config allows four volumes, which the workflow mounts: `crafter-flatpak-system` (the Sdk install at `/var/lib/flatpak`), `crafter-flatpak-builder` (flatpak-builder state and ccache, so the LLVM and WASI modules are rebuilt only when their sources change; a cold run takes about 80 minutes on 8 cores, a warm one a fraction of that), `/var/www/flatpak`, the web root Caddy serves as `https://flatpak.catcrafts.net/`, and `/etc/crafter-flatpak`, which holds the repo signing key (`signing-key.asc`, no passphrase, and `key-id`), generated once on the host and mounted read-only into the job; nothing is stored in the forge. The live repo at `/var/www/flatpak/repo` is canonical; builds are promoted into it with `flatpak build-commit-from`, never built into it.
+`.forgejo/workflows/ci.yaml` runs on the `crafter-flatpak` runner label: a dedicated privileged forgejo-runner on the Hetzner box (`forgejo-runner-flatpak.service`, config `/etc/forgejo-runner/config-flatpak.yaml`), registered to this repository only and the only runner with that label. It is privileged because bubblewrap inside the job container needs it, and no other repository's job runs on it. Its config allows four volumes, which the workflow mounts: `crafter-flatpak-system` (the Sdk install at `/var/lib/flatpak`), `crafter-flatpak-builder` (flatpak-builder state and ccache, which later runs reuse: flatpak-builder builds a module again when its sources or its `build-commands` change, and every module after it with it, so a new version of `swig` or `libedit`, which come before LLVM, also rebuilds the LLVM and WASI modules), `/var/www/flatpak`, the web root Caddy serves as `https://flatpak.catcrafts.net/`, and `/etc/crafter-flatpak`, which holds the repo signing key (`signing-key.asc`, no passphrase, and `key-id`), generated once on the host and mounted read-only into the job; nothing is stored in the forge. The web root and the key are not this runner's alone: the organisation-wide `flatpak` runner (`forgejo-runner-org-flatpak.service`), which serves every Catcrafts repository, mounts both for Crafter.Review's publish job, and the volumes a runner allows (`valid_volumes` in its config) are open to every job it runs, so a job of any Catcrafts repository that runs there can mount them as well. The live repo at `/var/www/flatpak/repo` is canonical; builds are promoted into it with `flatpak build-commit-from`, never built into it. Crafter.Review's workflow publishes into the same repo, and each workflow holds an flock on `/var/www/flatpak/.publish.lock` while it commits and updates the summary.
 
-Keep the label unique to that runner. Plain `flatpak` also belongs to the organisation-wide runner (`forgejo-runner-org-flatpak.service`), which serves every Catcrafts repository and on purpose allows no volumes. Whenever this job lands there, flatpak-builder stops with `The state dir (/root/.cache/flatpak-builder) is not on the same filesystem as the target dir`; the top of the job log shows which runner took it and lists every volume it ignored.
+Keep the label unique to that runner. Plain `flatpak` belongs to the organisation-wide runner. When this job still asked for `flatpak` and that runner took it (runs #368 and #370, in October 2026), the runner allowed none of the job's volumes, and flatpak-builder stopped with `The state dir (/root/.cache/flatpak-builder) is not on the same filesystem as the target dir`; the top of such a job's log shows which runner took it and lists every volume it ignored.
 
 The key is made once, as root on the runner host, and the step fails with a message pointing here when it is missing:
 
@@ -171,7 +175,8 @@ gpg --batch --pinentry-mode loopback --passphrase '' --export-secret-keys --armo
 printf '%s\n' "$KEYID" > /etc/crafter-flatpak/key-id && chmod 600 /etc/crafter-flatpak/signing-key.asc /etc/crafter-flatpak/key-id
 ```
 
-To release: add a `<release>` to `packaging/flatpak/net.catcrafts.CrafterBuild.metainfo.xml` (its description becomes the release notes), merge, and push the tag `X.Y.Z`. CI refuses a tag that does not match the newest entry.
+A release is a tag `X.Y.Z`, annotated and signed, pushed with the `master` it releases; a push to `master` without one runs nothing. Before building, every run renders the release notes from the newest `<release>` entry in `packaging/flatpak/net.catcrafts.CrafterBuild.metainfo.xml`, and stops when the metainfo does not parse or the notes come out empty. A tag run also checks that Forgejo verifies the tag as signed by the address the workflow's `RELEASE_SIGNER` names, that the tag's commit is on `master`, that its version has the form `X.Y.Z` and is newer than every release the forge has published, its own included, and that the newest entry is that version. Once the build and the suite inside it pass, the tag run publishes `stable` and creates the release, with the notes, the bundle, the `.flatpakref` and `SHA256SUMS` attached. Release runs queue one behind another, and a failed one can be re-run while no newer release exists, once a release it left half made is deleted; when the fix needs a commit of its own, that push is the next version's release. Pull requests and manual runs publish nothing. The `beta` branch, which every push to `master` used to go to, gets no more builds: the publish step marks its last build end-of-life, once, and the next `flatpak update` of a beta installation prints the reason.
+
 Local builds are two scripts in `project.cpp`. Run them with the native binary: the Flatpak build of crafter-build has no `flatpak` to drive.
 
 ```bash
@@ -179,7 +184,7 @@ Local builds are two scripts in `project.cpp`. Run them with the native binary:
 ./bin/crafter-build run install                # install that build as branch `local` and make it current
 ```
 
-`run flatpak` needs `flatpak-builder` or the `org.flatpak.Builder` app, and the Sdk (`flatpak install flathub org.freedesktop.Sdk//26.08`). It builds the working tree, uncommitted changes included, runs the whole suite inside the sandbox and reports version `0.0.0-dev`. Its state is `build/flatpak/` (`state/`, `repo/`, `build-dir/`). The first run builds LLVM and the WASI sysroot, about 25 minutes on a 56-core machine; later runs rebuild only the crafter-build module, a few minutes, because flatpak-builder never caches a `type: dir` source. The checkout must not be under `/tmp`, which `org.flatpak.Builder` cannot see. Use it for anything toolchain-sensitive: the native loop compiles with the distro's clang and the Flatpak with its bundled LLVM, and the two can be a major version apart.
+`run flatpak` needs `flatpak-builder` or the `org.flatpak.Builder` app, and the Sdk (`flatpak install flathub org.freedesktop.Sdk//26.08`). It builds the working tree, uncommitted changes included, runs the whole suite inside the sandbox and reports version `0.0.0-dev`. Its state is `build/flatpak/` (`state/`, `repo/`, `build-dir/`). The first run builds every module, LLVM with lldb, the WASI sysroot and the Vulkan validation layer among them, in about 30 minutes with 56 CPU threads; later runs rebuild only the crafter-build module while the manifest is unchanged, a few minutes, because flatpak-builder never caches a `type: dir` source. The checkout must not be under `/tmp`, which `org.flatpak.Builder` cannot see. Use it for anything toolchain-sensitive: the native loop compiles with the distro's clang and the Flatpak with its bundled LLVM, and the two can be a major version apart.
 
 `run install` does not build; it installs what `run flatpak` last exported. It points the user remote `crafter-build-local` at `build/flatpak/repo`, installs `net.catcrafts.CrafterBuild//local` from it next to whichever published branch is installed, and makes it the branch `flatpak run net.catcrafts.CrafterBuild` starts. `flatpak make-current --user net.catcrafts.CrafterBuild <branch>` switches back. Before `crafter-build clean`, or before deleting the checkout, run `flatpak uninstall --user net.catcrafts.CrafterBuild//local` and `flatpak remote-delete --user crafter-build-local`; otherwise the remote is left pointing at a repo that is gone.
 
@@ -194,6 +199,7 @@ Local builds are two scripts in `project.cpp`. Run them with the native binary:
 - The bootstrap binary is compiled without `CRAFTER_BUILD_HAS_ASSET`, so `cfg.assets` only works in the self-hosted binary. Changing asset extensions means updating two maps in `Crafter.Build-Clang.cpp`: `assetOutput` and the transitive copy loop.
 - A warning is printed only when its unit actually recompiles. A build with nothing to do is silent, which is not evidence that a warning is gone.
 - A std module source only compiles against the headers of its own libc++ release, and a sysroot does not always ship one (Alpine). The Flatpak therefore carries the sources of the release next to the bundled one under `share/crafter-build/libc++-modules/<major>/`, one `libcxx-<major>-modules` manifest module each. When the bundled LLVM is bumped, keep the release it leaves behind as such a module: sysroots on the stable distro stay on it for months. The native loop has no such directory; stage one by hand under `share/crafter-build/` to test against a foreign sysroot.
+- The Flatpak carries the debugging tools for what it builds, because those programs run in its sandbox: lldb is a project of the `llvm` module, with `LLDB_ENABLE_PYTHON`, `LIBEDIT`, `CURSES`, `LIBXML2` and `LZMA` set ON so that a missing dependency fails the configure step (SWIG through Python, which needs it), and the `swig` and `libedit` modules come before it. The Khronos validation layer is the `vulkan-validation-layers` module plus four modules before it, build-only except for SPIRV-Tools' programs (`spirv-val` and the rest), all after the LLVM and WASI modules, so that bumping them reuses the cached LLVM and WASI builds. The layer follows the Sdk's Vulkan loader: when `runtime-version` moves to a runtime with a newer loader, move the layer to the Vulkan SDK release of that loader and take the other four revisions from that release's `scripts/known_good.json`.
 - The wasm compile flags live in one place, `WasmBaselineFlags` in `Crafter.Build-Clang.cppm`: the std module and every unit have to agree on them, and `VariantId()` and the std PCM directory hash them, so a change rebuilds instead of mixing old and new BMIs. They enable C++ exceptions, so the link takes the exception-enabled libc++ and libunwind from the sysroot's `lib/<triple>/eh/` (wasi-sdk 33 and later). The Flatpak's sysroot has them and a distro's may not; where they are missing the wasm tests skip, so run those through the Flatpak. A browser page checks the engine with the `WasmBaselineProbes` named in `variants.json`.
 - `WasiBrowserRuntimeExit` runs `wasi-runtime/runtime.js` under node and skips where there is none. The Flatpak has no node, so CI never runs it: after touching `runtime.js`, run the suite in the native loop with node on `PATH`.
 - `VariantId()` names the output directory, so CI globs `bin/crafter.build-exe-<target>-<march>-*/` rather than predicting the hash. The hash includes the compiler, so after a toolchain update the previous variant's directories stay in `bin/` and `build/` until `clean`, and such a glob matches both.

README.md

@@ -4,15 +4,17 @@ A C++26 modules build system. Project descriptions are written in C++ with no JS
 
 ## Install
 
-crafter-build ships as a Flatpak that carries its own clang, lld, libc++ and WASI sysroot, so every machine builds with the same compiler:
+crafter-build ships as a Flatpak that carries its own clang, lld, libc++ and WASI sysroot, so every machine builds with the same compiler, and lldb and the Vulkan validation layers to debug the result (see [Debugging](#debugging)):
 
 ```bash
 flatpak remote-add --if-not-exists catcrafts https://flatpak.catcrafts.net/catcrafts.flatpakrepo
 flatpak install catcrafts net.catcrafts.CrafterBuild
-alias crafter-build='flatpak run net.catcrafts.CrafterBuild'
+alias crafter-build='flatpak run --die-with-parent net.catcrafts.CrafterBuild'
 ```
 
-Pre-release builds of `master` are the `beta` branch (`flatpak install catcrafts net.catcrafts.CrafterBuild//beta`), and every release also attaches a single-file bundle on the Forgejo releases page (`flatpak install --user crafter-build-<version>.flatpak`). The sandbox sees the whole host filesystem, so projects can live anywhere. Binaries built for the host link the bundled `libc++.so.1` through an rpath into the Flatpak: they run inside it (`-r`, the test runner), and are not meant to be copied out onto the host.
+`--die-with-parent` ends the sandbox with the `flatpak run` that started it. Without the flag, killing only the `flatpak run` process leaves the sandbox running: a build carries on writing into `bin/` and `build/`, and a program started with `-r` keeps running. With it, bubblewrap kills everything in the sandbox with SIGKILL when the `flatpak run` process dies or when that process's parent does. For `crafter-build …` or `crafter-build … &` typed at a bash or zsh prompt, that parent is the shell, so the sandbox ends with the shell, even after a `disown`. Ctrl-C reaches the program either way.
+
+Releases are published to the `stable` branch that the commands above install, and every release also attaches a single-file bundle on the Forgejo releases page (`flatpak install --user crafter-build-<version>.flatpak`). The sandbox sees the whole host filesystem, so projects can live anywhere. Binaries built for the host link the bundled `libc++.so.1` through an rpath into the Flatpak: they run inside it (`-r`, the test runner), and are not meant to be copied out onto the host.
 
 ## Writing a project.cpp
 
@@ -364,6 +366,32 @@ Things to know:
 - Inside the Flatpak, commands run in its sandbox: the host's files are visible, but the tools on `PATH` are the ones the Flatpak ships (`git`, `cmake`, `python3`, `tar`, ...), not everything installed on the host.
 - A return value outside 0 to 255 is not an exit status and becomes 1. So does a script that throws, with the exception's message printed.
 
+## Debugging
+
+Programs that `-r` and the test runner start run inside the Flatpak's sandbox, and so do the tools to debug them: lldb, with `lldb-server`, `lldb-dap` and `lldb-mcp`, from the same LLVM build as the compiler; `gdb`, `gdbserver`, `valgrind` and `strace` from the Freedesktop Sdk; the Khronos Vulkan validation layer; and the SPIRV-Tools programs (`spirv-val`, `spirv-opt`, `spirv-dis`, ...). A default build is optimised (`-O3`, and ThinLTO except for wasm) and carries no debug information: set `cfg.debug = true` for a program you want to debug, which compiles its C++ units with `-g` and links it without LTO; its C and CUDA sources (`cfg.cFiles`, `cfg.cuda`) stay at `-O3` without debug information. A `project.cpp` that calls `ApplyStandardArgs` sets it from the `--debug` argument, as in `crafter-build --debug -r`. Start the tools with `--command`:
+
+```bash
+flatpak run --die-with-parent --command=lldb net.catcrafts.CrafterBuild ./bin/myapp-<variant>/myapp
+flatpak run --die-with-parent --command=valgrind net.catcrafts.CrafterBuild ./bin/myapp-<variant>/myapp
+```
+
+Every `flatpak run` is a sandbox of its own, with process IDs of its own, so a debugger in one cannot see a program that another one, such as `crafter-build -r`, started. Either start the program under the debugger, or run the debugger inside that program's sandbox with `flatpak enter`, giving the instance `flatpak ps` lists for net.catcrafts.CrafterBuild and the debugger's full path:
+
+```bash
+flatpak ps --columns=instance,application
+flatpak enter <instance> /app/bin/lldb -n myapp
+```
+
+Where `/proc/sys/kernel/yama/ptrace_scope` is 1, a debugger in the sandbox, where processes hold no capabilities, can attach to a program that is not its descendant only when the program allowed it with `prctl(PR_SET_PTRACER, …)`: with the debugger's process ID, or with `PR_SET_PTRACER_ANY` for any process. Otherwise the attach fails. A program started under the debugger is its descendant. Prefer `flatpak enter` to `lldb-server gdbserver` in one sandbox and lldb's `gdb-remote` from another: when a process in lldb's own sandbox has the remote program's process ID, lldb takes that process's executable for the program's: symbols come out wrong, and a breakpoint in the program's source finds no location.
+
+The validation layer is enabled the usual ways, by the program itself or from the environment: `flatpak run` passes `VK_INSTANCE_LAYERS`, `VK_LOADER_LAYERS_ENABLE` and the layer's `VK_KHRONOS_VALIDATION_*` settings into the sandbox. `VK_KHRONOS_VALIDATION_GPUAV_ENABLE=1` adds GPU-assisted validation (GPU-AV):
+
+```bash
+VK_INSTANCE_LAYERS=VK_LAYER_KHRONOS_validation VK_KHRONOS_VALIDATION_GPUAV_ENABLE=1 crafter-build -r
+```
+
+The layer is the Vulkan SDK release of the runtime's own Vulkan loader. `VK_LAYER_PATH` and `VK_ADD_LAYER_PATH` are cleared on the way into the sandbox, so a layer installed on the host is out of reach.
+
 ## Examples
 
 [examples/](examples/) contains progressively larger self-contained projects:

build.sh

@@ -36,10 +36,9 @@ else
     STD_CPPM=/usr/share/libc++/v1/std.cppm
 fi
 
-# The version baked into the binary: the environment (CI sets it from the
+# The version baked into the binary: the environment (CI sets it), else the
-# tag), else the nearest tag, else a development marker. `latest` is the
+# nearest tag, else a development marker.
-# rolling CI tag and never a version.
+VERSION="${CRAFTER_BUILD_VERSION:-$(git describe --tags --always --dirty 2>/dev/null || echo 0.0.0-dev)}"
-VERSION="${CRAFTER_BUILD_VERSION:-$(git describe --tags --always --dirty --exclude=latest 2>/dev/null || echo 0.0.0-dev)}"
 
 mkdir -p build bin lib share/crafter-build share/crafter-build/wasi-runtime
 

packaging/flatpak/net.catcrafts.CrafterBuild.metainfo.xml

@@ -25,6 +25,42 @@
   </provides>
   <content_rating type="oars-1.1"/>
   <releases>
+    <release version="6.0.0" date="2026-11-02">
+      <description>
+        <p>New</p>
+        <ul>
+          <li>The Flatpak carries lldb, with <code>lldb-server</code>, <code>lldb-dap</code> and <code>lldb-mcp</code>, from the same LLVM build as the compiler, so programs that <code>-r</code> and the test runner start can be debugged inside the sandbox they run in. The README's new Debugging section says how, including <code>flatpak enter</code> to reach a program that is already running.</li>
+          <li>The Flatpak carries the Khronos Vulkan validation layer, the Vulkan SDK release of the runtime's own loader. <code>VK_INSTANCE_LAYERS</code> or <code>VK_LOADER_LAYERS_ENABLE</code> turns it on from the environment, and <code>VK_KHRONOS_VALIDATION_GPUAV_ENABLE=1</code> adds GPU-assisted validation. A layer installed on the host cannot stand in: <code>flatpak run</code> clears <code>VK_LAYER_PATH</code> and <code>VK_ADD_LAYER_PATH</code>.</li>
+          <li>The Flatpak carries the SPIRV-Tools programs (<code>spirv-val</code>, <code>spirv-opt</code>, <code>spirv-dis</code> and the rest), so a test that requires <code>tool:spirv-val</code> runs inside it instead of being skipped.</li>
+          <li>The alias in the README's install commands passes <code>--die-with-parent</code>, which ends the sandbox when its <code>flatpak run</code> process dies and, for a command typed at a bash or zsh prompt, when that shell does. Without it, killing <code>flatpak run</code> leaves a build writing into <code>bin/</code> and <code>build/</code> and a program started with <code>-r</code> running. An alias set up from an earlier README does not have it.</li>
+        </ul>
+        <p>Fixes</p>
+        <ul>
+          <li>The <code>.flatpakref</code> attached to a release carries the repository's signing key. Releases 2.0.0 to 5.0.0 attach one with a placeholder in its place, and installing from it fails with <code>GPG: Unable to export keys</code>; the one on flatpak.catcrafts.net has the key.</li>
+        </ul>
+        <p>Breaking</p>
+        <ul>
+          <li>Master has no builds of its own any more: the beta branch gets no new builds and the rolling "Latest master build" release is gone, and every change reaches users as a release on the stable branch. Beta's last build is marked end-of-life, and the next <code>flatpak update</code> of a beta installation says so: install stable with <code>flatpak install catcrafts net.catcrafts.CrafterBuild//stable</code> and remove beta with <code>flatpak uninstall net.catcrafts.CrafterBuild//beta</code>.</li>
+        </ul>
+      </description>
+    </release>
+    <release version="5.0.0" date="2026-10-31">
+      <description>
+        <p>Fixes</p>
+        <ul>
+          <li>A mingw build no longer sees the Linux system's headers and libraries. Inside the Flatpak the mingw-w64 prefix is the host's /usr, and it was clang's <code>--sysroot</code>, so clang searched /usr/include and /usr/lib for the Windows build as well: libstdc++ found glibc's <code>sys/single_threaded.h</code> and had <code>shared_ptr</code> read <code>__libc_single_threaded</code>, and every program that used one failed to link. <code>CRAFTER_MINGW_DIR=/usr</code> did the same outside the Flatpak. A prefix that also holds a Linux system (the host's /usr, or any prefix whose include/ has a C library's features.h) now reaches clang through a view of its mingw-w64 directories in the cache, and compiler messages still name its headers where they are installed. A prefix that holds mingw-w64 alone is the sysroot as before, so Windows libraries installed into its include/ and lib/ are found (#43).</li>
+          <li>Units that import a std module rebuilt in place, after a libc++ update or a mingw-w64 update under the same compiler, are compiled again. They used to be relinked unchanged.</li>
+          <li>A CMake external whose configure inputs changed, such as another compiler or <code>--sysroot</code>, is built again from an empty build directory. It used to be reconfigured in place, keeping the objects and check results of the old configure, so a mingw external built by 4.0.0 would have kept failing to link after the fix above.</li>
+          <li>Configurations that compile the std module differently no longer share one. Two that differed only in <code>-mtune</code> (a project built with <code>CRAFTER_BUILD_MTUNE</code> set, next to its own project.cpp) or only in sysroot took turns rebuilding it, and every module built against it, on every run.</li>
+          <li><code>crafter-build lint</code> fails, and says why, when a configuration's compile command cannot be assembled or its std module cannot be built. Its files used to pass every rule that needs an AST as if they were clean.</li>
+        </ul>
+        <p>Breaking</p>
+        <ul>
+          <li><code>Toolchain::mingwSysroot</code> is now <code>mingwPrefix</code>, beside <code>mingwPrefixIsSystem</code>, because clang no longer always gets the prefix itself. A project.cpp that passes the mingw sysroot to a command of its own calls <code>MingwSysroot()</code>; passing <code>mingwPrefix</code> brings the bug above back for a prefix like /usr.</li>
+          <li>The std module's cache directory is now keyed on every flag it is compiled with, and every build directory on the std module it imports, so the first build of each project after updating starts in fresh directories and compiles everything, as after a compiler update. <code>crafter-build clean</code> removes the old build directories; the old std module directories stay in the cache until it is cleared by hand.</li>
+        </ul>
+      </description>
+    </release>
     <release version="4.0.0" date="2026-10-31">
       <description>
         <p>New</p>

packaging/flatpak/net.catcrafts.CrafterBuild.yaml

@@ -5,9 +5,15 @@
 # Platform: a build tool needs glibc's headers and crt objects, gcc's
 # libgcc_s, cmake, ninja, make, git and python at run time. Everything
 # compiler-shaped is ours and lives under /app: clang, lld, libclang, libc++,
-# compiler-rt (native and wasm32) and the WASI sysroot, all built from one
+# compiler-rt (native and wasm32), lldb and the WASI sysroot, all built from
-# LLVM source tree so the modules crafter-build builds and the compiler that
+# one LLVM source tree so the modules crafter-build builds and the compiler
-# consumes them can never drift apart.
+# that consumes them can never drift apart.
+#
+# Programs that `-r` and the test runner start run in this sandbox, so the
+# tools to debug them live here too: lldb (above), the Sdk's gdb, valgrind
+# and strace, the Khronos Vulkan validation layers, GPU-assisted validation
+# included, which neither the Sdk nor its GL extensions carry, and the
+# SPIRV-Tools programs such as spirv-val.
 app-id: net.catcrafts.CrafterBuild
 runtime: org.freedesktop.Sdk
 runtime-version: '26.08'
@@ -25,13 +31,38 @@ finish-args:
   - --socket=fallback-x11
   - --socket=pulseaudio
   - --device=all
-  # gdb and friends from the Sdk
+  # lldb, and gdb and friends from the Sdk
   - --allow=devel
   - --env=PATH=/app/bin:/usr/bin
 cleanup:
   - /share/man
   - /share/doc
 modules:
+  - name: swig
+    # Generates lldb's Python bindings while the llvm module builds; nothing
+    # of it ships.
+    cleanup:
+      - '*'
+    sources:
+      - type: archive
+        url: https://downloads.sourceforge.net/project/swig/swig/swig-4.4.1/swig-4.4.1.tar.gz
+        sha256: 40162a706c56f7592d08fd52ef5511cb7ac191f3593cf07306a0a554c6281fcf
+
+  - name: libedit
+    # Line editing, history and completion at lldb's prompt. The Sdk has the
+    # ncurses it needs but not libedit itself; liblldb links the shared
+    # library, so that ships and the rest goes.
+    config-opts:
+      - --disable-static
+    cleanup:
+      - /include
+      - /lib/pkgconfig
+      - /lib/*.la
+    sources:
+      - type: archive
+        url: https://thrysoee.dk/editline/libedit-20260512-3.1.tar.gz
+        sha256: 432d5e7ea8b0116dd39f2eca7bc11d0eed77faa6b77ea526ace89907c23ea4a0
+
   - name: llvm
     buildsystem: cmake-ninja
     builddir: true
@@ -50,8 +81,20 @@ modules:
     config-opts:
       - -DCMAKE_BUILD_TYPE=Release
       - -DLLVM_ENABLE_ASSERTIONS=OFF
-      - -DLLVM_ENABLE_PROJECTS=clang;lld
+      - -DLLVM_ENABLE_PROJECTS=clang;lld;lldb
       - -DLLVM_ENABLE_RUNTIMES=compiler-rt;libcxx;libcxxabi;libunwind
+      # lldb with Python scripting (its bindings generated by the swig module
+      # above, against the Sdk's Python), libedit (the module above), curses,
+      # libxml2 and lzma, each set ON rather than left to the default of "if
+      # found", so a dependency gone missing fails the configure step instead
+      # of shipping an lldb without it. lldb-server, lldb-dap and lldb-mcp
+      # come with it.
+      - -DLLDB_ENABLE_PYTHON=ON
+      - -DLLDB_ENABLE_LIBEDIT=ON
+      - -DLLDB_ENABLE_CURSES=ON
+      - -DLLDB_ENABLE_LIBXML2=ON
+      - -DLLDB_ENABLE_LZMA=ON
+      - -DLLDB_ENABLE_LUA=OFF
       - -DLLVM_TARGETS_TO_BUILD=X86;AArch64;WebAssembly
       # Classic layout: libc++ in lib/ and include/c++/v1, not under a
       # per-target subdirectory, the same shape as a distro install.
@@ -82,6 +125,7 @@ modules:
       - /include/clang
       - /include/clang-tidy
       - /include/lld
+      - /include/lldb
       - /lib/cmake
       - /lib/*.a
       - /share/opt-viewer
@@ -219,6 +263,111 @@ modules:
         url: https://github.com/llvm/llvm-project/releases/download/llvmorg-22.1.8/llvm-project-22.1.8.src.tar.xz
         sha256: 922f1817a0df7b1489272d18134ee0087a8b068828f87ac63b9861b1a9965888
 
+  # The Khronos validation layers and the four modules they are built from,
+  # after llvm, so that bumping them reuses the cached LLVM build. All five
+  # are pinned to the Vulkan SDK release of the Sdk's own Vulkan loader and
+  # headers (1.4.357), at the dependency revisions that release's
+  # scripts/known_good.json names. When the runtime moves to a newer loader,
+  # move the layers to the SDK release of that loader and take the other
+  # four revisions from its known_good.json again. The four are built into
+  # /app at those revisions rather than taken from the Sdk, whose versions
+  # follow the runtime, and of them only SPIRV-Tools' programs ship.
+  - name: vulkan-headers
+    buildsystem: cmake-ninja
+    builddir: true
+    cleanup:
+      - '*'
+    sources:
+      - type: archive
+        url: https://github.com/KhronosGroup/Vulkan-Headers/archive/refs/tags/v1.4.357.tar.gz
+        sha256: 7dc0dbcf1d49dd3d7da3761c251c6097dfbaac475321a4a8a99269d3d5abecdc
+
+  - name: vulkan-utility-libraries
+    buildsystem: cmake-ninja
+    builddir: true
+    config-opts:
+      - -DCMAKE_BUILD_TYPE=Release
+      # CMake searches its install prefix after /usr, where the Sdk has
+      # Vulkan headers of its own.
+      - -DCMAKE_PREFIX_PATH=/app
+    cleanup:
+      - '*'
+    sources:
+      - type: archive
+        url: https://github.com/KhronosGroup/Vulkan-Utility-Libraries/archive/refs/tags/v1.4.357.tar.gz
+        sha256: e8688013cdc67dad26f15dcece91fa6b80ad595d551fceb56397fc4795efd00a
+
+  - name: spirv-headers
+    buildsystem: cmake-ninja
+    builddir: true
+    cleanup:
+      - '*'
+    sources:
+      - type: archive
+        url: https://github.com/KhronosGroup/SPIRV-Headers/archive/29981f65241605e08b0ede4cfeb999fe3b723c6a.tar.gz
+        sha256: 232899f1ad4104fb5bc377b94596c7621575eee62ad9a9e8f929b63a7dd8a7ad
+
+  - name: spirv-tools
+    # The optimizer GPU-assisted validation instruments shaders with, linked
+    # into the layer statically, and SPIRV-Tools' programs (spirv-val,
+    # spirv-opt, spirv-dis and the rest), which ship: a program or test that
+    # checks its SPIR-V with spirv-val, as Crafter.Graphics' do, finds it in
+    # the sandbox. The libraries and headers stay build-only.
+    buildsystem: cmake-ninja
+    builddir: true
+    build-options:
+      no-debuginfo: true
+      strip: true
+    config-opts:
+      - -DCMAKE_BUILD_TYPE=Release
+      # The installed SPIRV-Headers: its include/ holds the grammar files
+      # SPIRV-Tools generates its tables from, as the source tree does.
+      - -DSPIRV-Headers_SOURCE_DIR=/app
+      - -DSPIRV_SKIP_TESTS=ON
+      - -DSPIRV_WERROR=OFF
+    cleanup:
+      - /include/spirv-tools
+      - /lib/libSPIRV-Tools*.a
+      # Always built besides the static libraries, and linked by nothing
+      # here: the programs and the layer take SPIRV-Tools statically.
+      - /lib/libSPIRV-Tools-shared.so
+      - /lib/cmake/SPIRV-Tools*
+      - /lib/pkgconfig/SPIRV-Tools*
+    post-install:
+      - spirv-val --version
+    sources:
+      - type: archive
+        url: https://github.com/KhronosGroup/SPIRV-Tools/archive/b707790a898e44038547df54580022fc1cf89c3d.tar.gz
+        sha256: 05d8af89737bde57571c48dbd36714c9f520a69623e14de72c3be6b600e277d6
+
+  - name: vulkan-validation-layers
+    # VK_LAYER_KHRONOS_validation. The loader finds its manifest under
+    # /app/share/vulkan/explicit_layer.d through XDG_DATA_DIRS, and the
+    # manifest names the library without a path, which the sandbox's loader
+    # finds in /app/lib. GPU-AV is a setting of this layer, not a layer of
+    # its own (VK_KHRONOS_VALIDATION_GPUAV_ENABLE=1, or the layer settings).
+    buildsystem: cmake-ninja
+    builddir: true
+    build-options:
+      no-debuginfo: true
+      strip: true
+    config-opts:
+      - -DCMAKE_BUILD_TYPE=Release
+      - -DCMAKE_PREFIX_PATH=/app
+      # ON by default: it clones every dependency with update_deps.py, which
+      # the build sandbox has no network for, instead of using the four
+      # modules above.
+      - -DUPDATE_DEPS=OFF
+      - -DBUILD_TESTS=OFF
+      - -DBUILD_WERROR=OFF
+    post-install:
+      - test -f /app/share/vulkan/explicit_layer.d/VkLayer_khronos_validation.json
+      - test -f /app/lib/libVkLayer_khronos_validation.so
+    sources:
+      - type: archive
+        url: https://github.com/KhronosGroup/Vulkan-ValidationLayers/archive/refs/tags/vulkan-sdk-1.4.357.0.tar.gz
+        sha256: 73180b11992a3554e97ebc18e6bf2b45ff9790ded9d87fc526c7bab865d1303f
+
   - name: crafter-build
     buildsystem: simple
     build-options:

project.cpp

@@ -16,7 +16,8 @@ namespace {
     struct FlatpakPaths {
         fs::path manifest;
         // flatpak-builder's downloads, ccache and per-module cache. The
-        // LLVM build lives here: about 2 GB, and 25 minutes to rebuild.
+        // LLVM build lives here: about 3 GB in all after a first run,
+        // which takes about 30 minutes with 56 CPU threads.
         fs::path state;
         // The OSTree repo the build is exported to; `install` reads it.
         fs::path repo;
@@ -156,14 +157,14 @@ extern "C" Configuration CrafterBuildProject(std::span<const std::string_view> a
     if (const fs::path& llvmInclude = GetToolchain().llvmIncludeDir; !llvmInclude.empty()) {
         CrafterBuildLib->compileFlags.push_back(std::format("-I{}", llvmInclude.string()));
     }
-    // The version the binary reports: CI sets it from the tag, a checkout
+    // The version the binary reports: CI sets it, a checkout describes
-    // describes itself, anything else is a development build. A define on
+    // itself, anything else is a development build. A define on the
-    // the library, so each version is its own library variant.
+    // library, so each version is its own library variant.
     std::string version;
     if (const char* env = std::getenv("CRAFTER_BUILD_VERSION"); env && *env) {
         version = env;
     } else {
-        auto described = RunCommandWithTimeout("git describe --tags --always --dirty --exclude=latest 2>/dev/null", std::chrono::seconds(10));
+        auto described = RunCommandWithTimeout("git describe --tags --always --dirty 2>/dev/null", std::chrono::seconds(10));
         version = described.output;
         while (!version.empty() && (version.back() == '\n' || version.back() == '\r')) version.pop_back();
         if (described.exitCode != 0 || version.empty()) version = "0.0.0-dev";