feats(demos) astubbs#242: the ten per-language demos, and the evidence behind the seed's conventions

AGENTS.md

@@ -84,8 +84,9 @@ is untracked (a whole triage doc was once written duplicating `docs/refactoring.
 | [`docs/self-hosted-runner.md`](docs/self-hosted-runner.md) | Setting up or operating the self-hosted highcpu runner |
 | [`docs/agent-harness.md`](docs/agent-harness.md) | Adding a rule you need agents to follow *reliably* - which layers fire on their own, and which are merely available |
 | [`docs/merge-checklist.md`](docs/merge-checklist.md) | Getting a PR ready to merge - what to offer the author, including the squash message and reorganising the commits |
-| [`bin/AGENTS.md`](bin/AGENTS.md) | Writing or changing a script in `bin/` - the shell conventions, including the ones no check enforces |
+| [`bin/AGENTS.md`](bin/AGENTS.md) | Writing or changing **any shell script** - `bin/`, `.githooks/`, `.claude/hooks/` - the shell conventions, including the cross-platform rule and the others no check enforces |
 | [`docs/inflight/AGENTS.md`](docs/inflight/AGENTS.md) | Adding, editing or retiring a note in `docs/inflight/` - what may live there, the tag vocabulary, and where a note's content goes when its work lands |
+| [`parallel-consumer-proxy-clients/AGENTS.md`](parallel-consumer-proxy-clients/AGENTS.md) | Changing a client or its demo - the two test suites over them, which one your feature needs, and why neither substitutes for the other |
 | [`parallel-consumer-core/src/main/java/bz/stub/parallelconsumer/AGENTS.md`](parallel-consumer-core/src/main/java/bz/stub/parallelconsumer/AGENTS.md) | Changing a field in the engine - the `@GuardedBy` rule, the known shared state and its ledgers, and the shard-map pin |
 
 **A directory with its own `AGENTS.md` owns the rules for what goes in it - read it before you write
@@ -292,9 +293,28 @@ counts. This is a community-maintained fork of the no-longer-maintained
 
 ## Build Requirements
 
-- **JDK 17** (the project uses Jabel to compile Java 17 source to Java 8 bytecode)
+- **JDK 17** (the project uses Jabel to compile Java 17 source to Java 8 bytecode). On JDK 21 the
+  build dies as `Unable to delombok: InvocationTargetException` in `parallel-consumer-core` - a
+  module your change never touched, so it reads as a real breakage and is not one. Check
+  `java -version` first. Set it **per command** (`JAVA_HOME=... ./mvnw`), never by repointing a
+  shared default that every other session inherits.
 - **Docker** (integration tests - TestContainers spins up Kafka brokers)
 - **Maven via wrapper** (`./mvnw`) - do not use system Maven
+- **[mise](https://mise.jdx.dev)**, for the cross-language conformance module and the client
+  builds. `mise install` reads **`mise.toml`**, which is the single declaration of every toolchain
+  version; the CI matrix mirrors it and `bin/check-toolchain-versions.sh` fails if the two ever
+  disagree. It provides every foreign toolchain except the two that build in containers
+  (`bin/build-client.sh` names them: C++ and Swift). **Agents may install it and run `mise use -g`
+  themselves** - that call is recorded in
+  [`docs/inflight/parked-containerised-toolchains-and-runtime.md`](docs/inflight/parked-containerised-toolchains-and-runtime.md),
+  along with the rule that follows from it: *do not build an image fleet for problems mise has
+  already solved*.
+
+  Without mise the build falls through to whatever the host has, and the conformance module then
+  **fails** - correctly, because it refuses to let a runner nobody could build look like a runner
+  that passed. The two failure modes read as project breakage and are not: Go reports
+  `go.mod: unknown block type: tool` when `go env GOTOOLCHAIN` is `local` rather than its default
+  `auto`, and Ruby reports a missing `bundler` when macOS's system 2.6 is on `PATH`.
 
 ## How to Build
 

bin/AGENTS.md

@@ -1,8 +1,9 @@
 # `bin/` - how these scripts relate to CI and to the reviewer
 
 Repo scripts. This doc owns the conventions for writing a script in `bin/`; the root AGENTS.md
-routes here and keeps only what binds every session. Two conventions live here because nothing else
-enforces them.
+routes here and keeps only what binds every session. These conventions live here because nothing
+else enforces them. The portability rule below is the exception to the directory in the title: it
+binds **every shell script in the repo**, including `.githooks/` and `.claude/hooks/`.
 
 ## Naming a script here can grant it to the PR reviewer
 
@@ -61,6 +62,33 @@ Two structural guards exist and are worth copying into any new checker's self-te
   buried mid-body and a match at the very end, and neither can trigger the bug - the first is small,
   the second has nothing following it. A case that reaches it is added in astubbs#210.
 
+## Every script must be cross-platform, and degrade rather than guess
+
+Scripts here run on macOS dev machines, Linux CI runners, and self-hosted runners, so **a script that
+only works on the author's machine is a broken script**. Two rules, and the second is the one that
+actually bites:
+
+- **Never let a missing tool become a confident wrong answer.** Probe for what you need and skip what
+  is absent, saying so. `docker`, `gdate`, `realpath`, `timeout` and `sha256sum` are all absent
+  somewhere this repo runs. A check that cannot run must report that it did not run - the failure
+  mode to design against is the one where "I could not measure it" is indistinguishable from "it is
+  fine".
+
+- **`stat -f` is NOT a portable idiom, and must never be used as a try-then-fallback.** On macOS
+  `stat -f %b` is a *file's* allocated blocks; on GNU/Linux `-f` switches stat into *filesystem*
+  mode, where `%b` is the total blocks in the filesystem. It exits **0** and returns a number three
+  orders of magnitude too large, so `stat -f ... || stat -c ...` silently produces garbage on Linux
+  rather than falling through. Resolve the platform once from `uname -s` and branch. The same
+  divergence applies to `date -r` vs `date -d`, `sed -i ''` vs `sed -i`, and `readlink -f`.
+
+  `.claude/hooks/warn-low-disk.sh` is the worked example, and it also shows the seam that makes such
+  a branch testable: which `stat` **syntax** to speak is read from the real `uname` and is never
+  injectable, while which platform **layout** to look for is injectable - so a self-test can exercise
+  the macOS branch on a Linux runner without pretending Linux has BSD stat.
+
+- **`df` needs `-P`.** Without POSIX output a long device name wraps onto its own line on Linux and a
+  column-indexing `awk` silently reads the wrong field.
+
 ## Workflows
 
 **One version per action.** `bin/check-action-versions.sh` fails if any action appears at two
@@ -78,6 +106,20 @@ caught it in review, and the same mistake had been seen before.
 The github-actions ecosystem was re-enabled in `.github/dependabot.yml` at the same time; it had
 been off since 2022, when the repo genuinely had no workflows.
 
+**One toolchain declaration.** `bin/check-toolchain-versions.sh` fails when `mise.toml` and the
+`.github/workflows/clients.yml` matrix disagree about a language's version, and runs in Repo Hygiene
+behind its own self-test. The two *install* differently on purpose - mise locally, `setup-*` actions
+on the runner, which carry the client matrix's caching and a SHA-pinned `ruby/setup-ruby` - but they
+must never *declare* differently. Same class as the rule above: **nothing else could catch it**, and
+they had already drifted by whole major versions (dotnet 8 against 9, node 22 against 25) before the
+gate existed. The four languages with no host toolchain (swift and cpp build in containers, kotlin
+and scala on the Maven reactor) are asserted absent from both, so "nobody declared it" cannot be
+mistaken for "it deliberately has none".
+
+`bin/build-client.sh` asserts the *installed* version separately, at build time, on major.minor
+only - the declarations are exact, but a developer one patch along from the pin is not a problem
+worth blocking, and every failure the assertion exists for was a major or minor gap.
+
 **Temporary CVE exclusions expire.** `bin/check-cve-exclusions.sh` parses the root pom's
 `excludeVulnerabilityIds` and fails once an entry marked `TEMPORARY-SINCE: YYYY-MM-DD` is more than
 90 days old - also on an undated, unparseable or future-dated marker, and on an id with no rationale

bin/build-client.sh

@@ -39,6 +39,8 @@
 
 set -euo pipefail
 
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+readonly REPO_ROOT
 readonly CLIENTS_DIR="parallel-consumer-proxy-clients"
 readonly MODULE_PREFIX="parallel-consumer-proxy-client-"
 readonly PROTO_CONTEXT="parallel-consumer-proxy-protocol/src/main/proto"
@@ -170,12 +172,97 @@ maven_module_list() { # <module dir> -> comma-separated :artifactId list
     printf '%s' "$list"
 }
 
+# ─────────────────────────────────────────────────────────────────────────────────────────────────
+# TOOLCHAIN VERSION ASSERTION
+#
+# Maven shells out to whatever `go`, `ruby`, `node`, `python3`, `rustc` or `dotnet` is on PATH, and
+# a wrong one does not announce itself - it produces an error deep inside a module nobody touched.
+# Both real cases cost an hour each before anyone suspected their PATH: Go 1.23 against a 1.25
+# module reports `go.mod: unknown block type: tool`, and macOS's system Ruby 2.6 reports a missing
+# `bundler`. Neither says "your toolchain is the wrong version", which is the only useful sentence.
+#
+# MAJOR.MINOR, NOT EXACT. mise.toml and CI pin an exact patch and `bin/check-toolchain-versions.sh`
+# holds those two declarations identical - but asserting the patch HERE would fail every developer
+# whose mise resolved one release along (this was written on a box with go 1.25.14 against a pinned
+# 1.25.13) while catching nothing: every failure this guard exists for was a major or minor gap.
+#
+# A version it cannot read is a FAILURE, not a pass. "I could not check" and "it is fine" must never
+# look the same - the rule bin/AGENTS.md states for every script here.
+# ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+# The runtime each language builds with. `typescript` is the one place the language and the tool have
+# different names, matching the mapping in bin/check-toolchain-versions.sh.
+tool_for_language() { # <language> -> tool name, or empty when the language has no host toolchain
+    case "$1" in
+        typescript) printf 'node' ;;
+        go | ruby | rust | python | dotnet) printf '%s' "$1" ;;
+        *) printf '' ;;
+    esac
+}
+
+declared_version() { # <tool> -> the version mise.toml pins, or empty
+    local mise="$REPO_ROOT/mise.toml"
+    [ -f "$mise" ] || return 0
+    sed -n "s/^[[:space:]]*$1[[:space:]]*=[[:space:]]*\"\([^\"]*\)\".*/\1/p" "$mise" | head -1
+}
+
+active_version() { # <tool> -> the version actually on PATH, or empty when it cannot be determined
+    case "$1" in
+        go)     go version 2>/dev/null | sed -n 's/.*go\([0-9][0-9.]*\).*/\1/p' ;;
+        ruby)   ruby --version 2>/dev/null | sed -n 's/^ruby \([0-9][0-9.]*\).*/\1/p' ;;
+        rust)   rustc --version 2>/dev/null | sed -n 's/^rustc \([0-9][0-9.]*\).*/\1/p' ;;
+        python) python3 --version 2>/dev/null | sed -n 's/^Python \([0-9][0-9.]*\).*/\1/p' ;;
+        node)   node --version 2>/dev/null | sed -n 's/^v\([0-9][0-9.]*\).*/\1/p' ;;
+        dotnet) dotnet --version 2>/dev/null | sed -n 's/^\([0-9][0-9.]*\).*/\1/p' ;;
+        *)      printf '' ;;
+    esac
+}
+
+major_minor() { # <version> -> first two components
+    printf '%s' "$1" | cut -d. -f1,2
+}
+
+assert_toolchain_version() { # <language>
+    local language="$1" tool declared active
+    tool="$(tool_for_language "$language")"
+    [ -n "$tool" ] || return 0
+
+    declared="$(declared_version "$tool")"
+    if [ -z "$declared" ]; then
+        die 1 "$language: mise.toml pins no version for $tool, so the toolchain cannot be checked.
+        Add it, or remove $language from tool_for_language() and say why it has no host toolchain."
+    fi
+
+    active="$(active_version "$tool")"
+    if [ -z "$active" ]; then
+        die 1 "$language: could not determine the installed $tool version - is it on PATH?
+        mise.toml pins $tool $declared; install it with 'mise install' (or 'mise use -g $tool@$declared').
+        Refusing to build rather than guess: an unreadable toolchain is not a working one."
+    fi
+
+    if [ "$(major_minor "$active")" != "$(major_minor "$declared")" ]; then
+        die 1 "$language: wrong $tool version.
+          on PATH   : $active
+          mise.toml : $declared
+        Install the pinned one with 'mise install', or 'mise use -g $tool@$declared'.
+        Building anyway produces an error inside a module you did not touch - Go reports
+        'unknown block type: tool', Ruby reports a missing bundler - which reads as project breakage."
+    fi
+
+    if [ "$active" != "$declared" ]; then
+        printf '==> %s: %s %s on PATH, %s pinned - same minor, continuing\n' \
+            "$language" "$tool" "$active" "$declared"
+    fi
+}
+
 build_natively() { # <maven phase>
     local phase="$1"
     local module_dir="$CLIENTS_DIR/$MODULE_PREFIX$LANGUAGE"
     local projects
     projects="$(maven_module_list "$module_dir")"
 
+    assert_toolchain_version "$LANGUAGE"
+
     printf '==> %s: native toolchain via Maven (%s), projects %s\n' "$LANGUAGE" "$phase" "$projects"
     # No `clean`, deliberately: several agents and worktrees share this tree, and a clean here would
     # delete output nobody asked this script to rebuild.

bin/check-toolchain-versions.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+#
+# Copyright (C) 2026 Antony Stubbs and contributors
+#
+
+# Asserts that `mise.toml` and the `.github/workflows/clients.yml` matrix declare the SAME toolchain
+# versions.
+#
+# WHY IT EXISTS. The two install differently on purpose - mise locally, `setup-*` actions in CI,
+# because those actions carry the client matrix's caching and `ruby/setup-ruby` is SHA-pinned. What
+# is not on purpose is that they were two sources of truth for the same numbers with nothing
+# comparing them, and they had already drifted by WHOLE MAJOR VERSIONS before anyone looked: dotnet
+# 8.0.404 in CI against 9.0.101 on a developer machine, node 22.17.0 against 25.9.0. That is the
+# classic shape of "passes locally, fails in CI" - and the nastier reverse, where CI runs the older
+# runtime and the developer never sees the failure their change causes.
+#
+# WHAT IT DOES NOT DO. It does not check what is INSTALLED - that is
+# `assert_toolchain_version` in bin/build-client.sh, which runs at build time against the machine.
+# This one compares two declarations, so it is exact: a patch difference between two files that are
+# both meant to say the same thing is a mistake, not tolerable drift.
+#
+# THE FOUR ABSENT LANGUAGES ARE CHECKED TOO, because "nobody declared it" and "it deliberately has no
+# host toolchain" look identical otherwise: swift and cpp build in a container, kotlin and scala on
+# the Maven reactor, so all four must be absent from mise.toml AND carry an empty matrix toolchain.
+#
+# Read-only: no network, no writes, nothing outside this repository. Safe under the `check-*` grant
+# described in bin/AGENTS.md.
+#
+# Run: bin/check-toolchain-versions.sh
+
+set -uo pipefail
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+# The two overrides exist only for bin/test-check-toolchain-versions.sh, which has to drive this
+# gate against crafted fixtures to prove it can go red. bin/AGENTS.md's rule is that a regression
+# test which has never failed proves nothing, and the only other way to make this one fail is to
+# break the real repository.
+MISE="${PC_MISE_TOML:-$REPO_ROOT/mise.toml}"
+WORKFLOW="${PC_CLIENTS_WORKFLOW:-$REPO_ROOT/.github/workflows/clients.yml}"
+
+for f in "$MISE" "$WORKFLOW"; do
+    [ -f "$f" ] || {
+        printf 'check-toolchain-versions: MISSING %s - cannot compare, so this is a FAILURE rather than a pass\n' "$f" >&2
+        exit 1
+    }
+done
+
+# python3 rather than a yaml/toml parser: it is already a hard dependency of the agent hooks and the
+# conformance harness, and adding a parser dependency to a gate that guards the build is backwards.
+python3 - "$MISE" "$WORKFLOW" <<'PY'
+import re
+import sys
+
+mise_path, workflow_path = sys.argv[1], sys.argv[2]
+
+# The matrix names the LANGUAGE; mise names the RUNTIME. They differ in exactly one place, and
+# hard-coding that one mapping is clearer than inferring it.
+LANGUAGE_TO_TOOL = {"typescript": "node"}
+
+# Languages with no host toolchain by design. Named here so that a language quietly losing its
+# version is a failure rather than joining this list by accident.
+NO_HOST_TOOLCHAIN = {"swift", "cpp", "kotlin", "scala"}
+
+mise_text = open(mise_path).read()
+tools_block = re.search(r"^\[tools\]\s*$(.*?)(?=^\[|\Z)", mise_text, re.M | re.S)
+if not tools_block:
+    print("check-toolchain-versions: mise.toml has no [tools] section", file=sys.stderr)
+    raise SystemExit(1)
+declared = dict(re.findall(r'^\s*([A-Za-z0-9_-]+)\s*=\s*"([^"]+)"', tools_block.group(1), re.M))
+
+workflow_text = open(workflow_path).read()
+entries = re.findall(r"- language:\s*(\S+)(.*?)(?=\n\s*- language:|\Z)", workflow_text, re.S)
+matrix = {}
+for language, body in entries:
+    found = re.search(r"toolchain:\s*'([^']*)'", body)
+    if found is not None:
+        matrix[language] = found.group(1)
+
+if not matrix:
+    print("check-toolchain-versions: parsed NO languages out of the workflow matrix - the format "
+          "changed, and a gate that silently checks nothing is worse than no gate", file=sys.stderr)
+    raise SystemExit(1)
+
+problems = []
+
+for language, ci_version in sorted(matrix.items()):
+    tool = LANGUAGE_TO_TOOL.get(language, language)
+    if language in NO_HOST_TOOLCHAIN:
+        if ci_version:
+            problems.append(f"{language}: builds without a host toolchain, but the CI matrix pins "
+                            f"'{ci_version}'. Either it now needs one (add it to mise.toml) or the "
+                            f"pin is stale.")
+        if tool in declared:
+            problems.append(f"{language}: builds without a host toolchain, but mise.toml declares "
+                            f"{tool} = \"{declared[tool]}\".")
+        continue
+    if not ci_version:
+        problems.append(f"{language}: the CI matrix declares no toolchain version. If that is "
+                        f"deliberate, add it to NO_HOST_TOOLCHAIN in this script and say why.")
+        continue
+    if tool not in declared:
+        problems.append(f"{language}: CI pins '{ci_version}' but mise.toml declares no {tool}.")
+        continue
+    if declared[tool] != ci_version:
+        problems.append(f"{language}: mise.toml says {tool} = \"{declared[tool]}\", the CI matrix "
+                        f"says '{ci_version}'. These must be identical.")
+
+matrix_tools = {LANGUAGE_TO_TOOL.get(lang, lang) for lang in matrix}
+for tool in sorted(set(declared) - matrix_tools):
+    problems.append(f"mise.toml declares {tool} = \"{declared[tool]}\", which no language in the CI "
+                    f"matrix uses. Remove it, or add the language that needs it.")
+
+if problems:
+    print("check-toolchain-versions: the two declarations disagree.\n", file=sys.stderr)
+    for problem in problems:
+        print(f"  - {problem}", file=sys.stderr)
+    print("\nmise.toml is the single declaration; the workflow matrix must mirror it. They install\n"
+          "differently on purpose - see the header of mise.toml.", file=sys.stderr)
+    raise SystemExit(1)
+
+checked = len(matrix)
+print(f"check-toolchain-versions: {checked} language(s) agree between mise.toml and the CI matrix "
+      f"({len(declared)} pinned, {len(NO_HOST_TOOLCHAIN & set(matrix))} deliberately without a host toolchain).")
+PY