CI: add e2e runs from benchx_examples

.github/workflows/tests.yml

@@ -49,24 +49,3 @@ jobs:
 
       - name: Run tests
         run: uv run --extra test --python ${{ matrix.python-version }} python -m pytest tests -ra
-
-      - name: Run the pyperf-bench example
-        shell: bash
-        run: uv run --extra test --python ${{ matrix.python-version }} bash examples/pyperf-bench/run.sh
-
-      # Needs cmake and a C++ compiler (preinstalled on the Linux and macOS
-      # runners) and fetches Google Benchmark; the example is bash and CMake
-      # with Unix paths, so it is not run on Windows.
-      - name: Run the archery-local example
-        if: runner.os != 'Windows'
-        shell: bash
-        run: uv run --extra test --python ${{ matrix.python-version }} bash examples/archery-local/run.sh
-
-      # Makes two venvs of its own with uv (Python 3.12, the newest with numpy 1.26.4 wheels), so
-      # the matrix Python only runs the outer script and one cell is enough. Needs network access.
-      - name: Run the numpy-venvs example
-        if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.13'
-        shell: bash
-        run: >-
-          uv run --extra test --python ${{ matrix.python-version }}
-          bash examples/numpy-venvs/run.sh

docs/design/prototype-design.md

@@ -75,8 +75,8 @@ environment kind: a context collector (§3) prints facts about the environment i
 under `environment.system.<name>`, a part of the varying coordinate; a setup file does the same for
 declared facts. A collector with `verify: how_built` and `on_fail: warn` checks the facts a target's
 `how_built` object declares against what it found, and the comparison lists the warning beside the
-facts that differ. `prototype/examples/numpy-venvs` is the worked example, with the map from UC-04's
-spellings to these.
+facts that differ. `examples/numpy-venvs` in benchx_examples is the worked example, with the map from
+UC-04's spellings to these.
 
 A bare path is read by the harness. For Google Benchmark it is
 `BUILD_DIR[:SOURCE_DIR]`, a `build` target. For pyperf it is a working tree, a
@@ -560,9 +560,10 @@ Allowing a local-only `revisions` comparison of a dirty tree is open
 
 Both profiles use one shape: two prepared build directories, one run key, R
 rounds, and `bx compare` in measure mode, which alternates the sides and
-assigns `round` and `slot`. The demo script plays the user, and in that role
+assigns `round` and `slot`. The demo script (`examples/arrow/demo/run.sh` in
+the benchx_examples repository) plays the user, and in that role
 the target provider: it prepares the sources and build directories with git
-and CMake, since benchx builds nothing. `prototype/examples/archery-local`
+and CMake, since benchx builds nothing. `examples/arrow/archery-local` there
 shows the other route, where a provider script named in
 `benchx.conf.json` builds and describes the targets and the sides are
 given as `@plain` and `@hardened`.
@@ -589,7 +590,7 @@ re-ingested to show idempotency, and compared again with `--results`; that
 document must equal the one from the local store (criterion 8).
 
 Every `bx run` delivers to the local store, so both shapes' results land in
-the demo project's store (`prototype/examples/demo/store.parquet`), the ad hoc ones as thin results of project
+the demo project's store (`examples/arrow/demo/store.parquet` in benchx_examples), the ad hoc ones as thin results of project
 `local/<hostname>`. Run keys carry a timestamp, so successive demo runs add
 rows rather than colliding on `ingest_key`. The store and each series'
 history grow from run to run, and the demo ends with `bx head`.

prototype/README.md

@@ -65,7 +65,8 @@ declare `how_built` and `activation` text, which are copied into the work order
 and into every result's `provenance.info`, shown in the comparison, and never
 executed or checked: you activate the environment yourself, and the runner
 records the allowlisted variables it inherited beside your declaration.
-`examples/archery-local` is a complete walk-through.
+`examples/arrow/archery-local` in [benchx_examples](https://github.com/benchx-dev/benchx_examples)
+is a complete walk-through.
 
 `bx bench` is the single-target form of `bx compare`: the same way of naming a target
 (`@CONFIG[=SOURCE_REF]`, or a path), the same options, the same code; it writes one
@@ -87,13 +88,15 @@ pyperf.
 functions: the module's git checkout is the target, its path the suite, and the
 functions are exact case names. `bx run` is the layer underneath: it executes a finished
 order, so `bx run results/KEY/orders/order.json` replays any bench run.
-`examples/pyperf-bench` is a runnable walk-through.
+`examples/pyperf-suite` in [benchx_examples](https://github.com/benchx-dev/benchx_examples)
+is a runnable walk-through.
 
 Environments that cannot share a process, such as two venvs with different numpy versions, are
 measured by separate `bx bench` calls that share a `--run-key`; `--label NAME=VALUE`, `--round N`
 and `--slot K` place each call in the session, and `bx compare --run KEY --profile environments
 --label NAME --baseline VALUE` compares the sides ([UC-04](../docs/use-cases/UC-04-cross-env.md)).
-`examples/numpy-venvs` is the worked example, with a shell script that drives it.
+`examples/numpy-venvs` in [benchx_examples](https://github.com/benchx-dev/benchx_examples)
+is the worked example, with a shell script that drives it.
 
 `bx bench PATH --adapter asv` runs an [asv](https://asv.readthedocs.io) benchmark suite
 unchanged, reading asv's benchmark format as a language and timing it with pyperf;
@@ -181,39 +184,14 @@ every result is pyperf. Results also record the installed project's version
 ```console
 $ uv venv && uv pip install -e '.[test]'   # editable: schemas are read from ../schemas
 $ .venv/bin/python -m pytest tests     # 344 tests, fake Google Benchmark binary, no compiler
-$ ./demo.sh                             # real builds; needs cmake, a C++ compiler, network once
 ```
 
-`demo.sh` prints every command before running it, as you would type it
-(`bx` for `.venv/bin/python -m benchx.cli`, `$WORK` for its scratch
-directory), so it doubles as a walkthrough. It prepares a git source with two
-commits and three CMake build directories of `examples/demo-suite` (base,
-head, and head with `DEMO_HARDENED=ON`), shows the first work order of each
-part, then:
-
-1. **revisions, ad hoc:** `bx compare` in measure mode alternates base and head
-   over five rounds with orders that name no project, then read mode compares
-   the same run key through a throwaway store;
-2. **environments, tracked:** `bx compare` alternates plain and hardened, labeled
-   `build: plain|hardened`, compares from the local store, re-ingests
-   (no-op), and rejects a unit conflict;
-3. checks that the throwaway store gives the same comparison document as the
-   persistent one, lists series and history, and ends with `bx head`.
-
-Every `bx run` and every measure-mode `bx compare` delivers to the local store, so each demo run adds its
-results, ad hoc and tracked, to `examples/demo/store.parquet` (the demo's project root, set
-in its `benchx.conf.json`). Run keys carry a
-timestamp, so runs accumulate and each series' history grows. Look at it any
-time:
-
-```console
-$ (cd examples/demo && ../../.venv/bin/python -m benchx.cli head -n 20)
-$ rm examples/demo/store.parquet    # start over
-```
-
-Both changes add two to three percent of work. The quiet benchmark flags them
-as regressed; the noisy one, with about ten percent spread between
-repetitions, does not.
+The end-to-end examples that build real software are in
+[benchx_examples](https://github.com/benchx-dev/benchx_examples), and the `e2e`
+workflow runs them. `examples/arrow/demo/run.sh` there is a walkthrough of both comparison
+profiles on a small Google Benchmark suite, with real CMake builds (it needs cmake, a
+C++ compiler, and network access once). It prints every command before running it,
+as you would type it, so it doubles as a walkthrough.
 
 ## Layout
 
@@ -243,11 +221,6 @@ benchx/
   compare.py         run mode over a profile's projection, comparison document (comparator.md)
   cli.py             bx (compare has a read mode and a measure mode)
 ../schemas/          the result and work-order schemas, read in place ($BENCHX_SCHEMAS overrides)
-examples/demo-suite  a two-benchmark Google Benchmark suite for the demo
-examples/demo        the demo's project root: its benchx.conf.json, and its persistent store
-examples/pyperf-bench  Python functions under `bx bench` (own README)
-examples/archery-local  an end-to-end, Arrow-local-shaped example with a target provider (own README)
-examples/numpy-venvs  UC-04 with two venvs and two numpy versions, driven by run.sh (own README)
 tests/               test_prototype.py: the success criteria and the runner and store
                      rules, on a fake Google Benchmark binary; test_comparator.py: the
                      comparator's invariants and method on hand-built results;