Application ladder: rungs 0-3 (pastebin, bookmarks, polls) + shared infrastructure

.github/workflows/ci.yml

@@ -144,6 +144,40 @@ jobs:
           sudo apt-get install -y ninja-build catch2 libsqlite3-dev
           wget -qO- https://apt.llvm.org/llvm.sh | sudo bash -s -- ${{ env.CLANG_VERSION }}
 
+      # Only the coverage leg builds the ladder: examples/common's
+      # hand-written GUI/testkit code is real coverage of morph's client
+      # stack (Bridge, backends, QtExecutor, completions — see
+      # examples/TESTING.md's "round-7 T4 reframe"), so it belongs in the
+      # coverage number the same way the models it will host later do
+      # (examples/IMPLEMENTATION.md rule 5). asan/tsan/ubsan skip this, same
+      # as before — "a GUI stack under TSan is mostly noise" — coverage
+      # instrumentation carries none of that risk.
+      - name: Install ODBC + SQLite driver (coverage leg only)
+        if: matrix.preset == 'clang-coverage'
+        run: |
+          # unixodbc-dev + libsqliteodbc: the application ladder (built by this
+          # leg only) fetches the Lightweight ORM, whose CMake runs
+          # `pkg_check_modules(ODBC REQUIRED odbc)`, and whose ladder fixtures
+          # open a real `DRIVER=SQLite3` connection at test time.
+          # Named explicitly rather than relied on from the runner image.
+          sudo apt-get install -y libgl1-mesa-dev unixodbc-dev libsqliteodbc
+
+      # Not the distro's Qt: examples/common/CMakeLists.txt requires 6.5+
+      # unconditionally (not gated on MORPH_BUILD_FORMS_QML) and Ubuntu
+      # 24.04 still ships 6.4.2 -- the identical gap the "all optional
+      # features" and "Application ladder" jobs' own install-qt-action steps
+      # already document. Named qt6-base-dev/qt6-websockets-dev/qt6-tools-dev
+      # used to be installed above; replaced wholesale rather than kept
+      # alongside aqtinstall's Qt, which would leave two Qt6 installs on the
+      # same runner for find_package() to pick between.
+      - name: Install Qt ${{ env.QT_VERSION }} (coverage leg only)
+        if: matrix.preset == 'clang-coverage'
+        uses: jurplel/install-qt-action@v4
+        with:
+          version: ${{ env.QT_VERSION }}
+          modules: qtwebsockets
+          cache: true
+
       - name: Cache sccache
         uses: actions/cache@v4
         with:
@@ -159,23 +193,35 @@ jobs:
       # morph::net and the SQLite offline queue are opt-in, but they are also
       # where the memory/threading/UB risk actually lives (raw sockets, an I/O
       # thread, a hand-rolled frame reader, a C API). Left off, the sanitizers
-      # and the coverage number both silently skipped them. Qt/QML and the
-      # fuzzers stay out of this matrix — they are covered by the
-      # linux-all-features job, and a GUI stack under TSan is mostly noise.
+      # and the coverage number both silently skipped them. QML and the
+      # fuzzers stay out of this matrix entirely — they are covered by the
+      # linux-all-features job, and a GUI stack under TSan is mostly noise;
+      # the ladder (Qt6::WebSockets, no QML) is the one exception, built only
+      # on the coverage leg, for the reason in the Qt install step above.
       - name: Configure
         run: |
+          EXTRA_ARGS=()
+          if [ "${{ matrix.preset }}" = "clang-coverage" ]; then
+            EXTRA_ARGS+=(-DMORPH_BUILD_QT=ON -DMORPH_BUILD_LADDER=ON -DMORPH_LADDER_RUNGS=all)
+          fi
           cmake --preset ${{ matrix.preset }} \
             -DMORPH_BUILD_NET=ON \
             -DMORPH_BUILD_OFFLINE_SQLITE=ON \
             -DCMAKE_C_COMPILER=clang-${{ env.CLANG_VERSION }} \
             -DCMAKE_CXX_COMPILER=clang++-${{ env.CLANG_VERSION }} \
             -DCMAKE_C_COMPILER_LAUNCHER=sccache \
-            -DCMAKE_CXX_COMPILER_LAUNCHER=sccache
+            -DCMAKE_CXX_COMPILER_LAUNCHER=sccache \
+            "${EXTRA_ARGS[@]}"
 
       - name: Build
         run: cmake --build --preset ${{ matrix.preset }}
 
       - name: Test
+        env:
+          # Harmless for the non-Qt legs (nothing reads it); required for the
+          # coverage leg's ladder tests, which open real Qt widgets/sockets
+          # on a runner with no display.
+          QT_QPA_PLATFORM: offscreen
         run: |
           if [ "${{ matrix.preset }}" = "clang-coverage" ]; then
             LLVM_PROFILE_FILE="build/clang-coverage/%p.profraw" ctest --preset clang-coverage
@@ -253,6 +299,120 @@ jobs:
           QT_QPA_PLATFORM: offscreen
         run: ctest --preset gcc-debug
 
+  # ── Linux: application ladder testkit (path-filtered) ─────────────────
+  ladder-tests:
+    name: Application ladder
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # need history for the changed-paths diff below
+
+      - name: Determine whether the ladder needs to run
+        id: filter
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            base="${{ github.event.pull_request.base.sha }}"
+          else
+            base="${{ github.event.before }}"
+          fi
+          if [ -z "$base" ] || ! git cat-file -e "$base" 2>/dev/null; then
+            echo "run=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          changed=$(git diff --name-only "$base" HEAD)
+          # src/qt/: the compiled bodies of morph_qt_impl — the very thing the
+          # testkit exists to conformance-test (and where finding 017's fix
+          # lands). CMakeLists.txt/cmake/ and this workflow itself: a change to
+          # any of them can break or silently skip this job.
+          if echo "$changed" | grep -qE '^(examples/(common|pastebin|bookmarks|polls|kanban)/|examples/CMakeLists\.txt$|include/morph/|src/qt/|cmake/|CMakeLists\.txt$|CMakePresets\.json$|\.github/workflows/ci\.yml$|examples/LADDER\.md|examples/IMPLEMENTATION\.md|examples/TESTING\.md)'; then
+            echo "run=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "run=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Cache apt packages
+        if: steps.filter.outputs.run == 'true'
+        uses: actions/cache@v4
+        with:
+          path: /var/cache/apt/archives
+          key: apt-qt-${{ hashFiles('.github/workflows/ci.yml') }}
+          restore-keys: apt-qt-
+
+      - name: Install GCC 15, ninja, catch2
+        if: steps.filter.outputs.run == 'true'
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y software-properties-common
+          sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
+          sudo apt-get update -q
+          # unixodbc-dev + libsqliteodbc: the application ladder fetches the
+          # Lightweight ORM, whose CMake runs
+          # `pkg_check_modules(ODBC REQUIRED odbc)`, and whose ladder fixtures
+          # open a real `DRIVER=SQLite3` connection at test time.
+          # Named explicitly rather than relied on from the runner image.
+          # libyaml-cpp-dev + libzip-dev: Lightweight's own CMakeLists.txt
+          # does `find_package(yaml-cpp)`/`find_package(libzip)` as system
+          # CONFIG packages, not through CPM (examples/bank/CMakeLists.txt's
+          # comment on the identical fetch) — without these, configure fails
+          # the moment MORPH_BUILD_LADDER=ON pulls Lightweight in.
+          # Qt itself is installed by the aqtinstall step below, not apt: see
+          # that step's comment for why the distro package is unusable here.
+          sudo apt-get install -y gcc-15 g++-15 ninja-build catch2 \
+            libyaml-cpp-dev libzip-dev libgl1-mesa-dev \
+            unixodbc-dev libsqliteodbc
+          sudo update-alternatives --install /usr/bin/gcc gcc /usr/bin/gcc-15 15
+          sudo update-alternatives --install /usr/bin/g++ g++ /usr/bin/g++-15 15
+
+      # Not the distro's Qt: examples/common/CMakeLists.txt requires 6.5+
+      # (QQmlApplicationEngine::loadFromModule, used by MORPH_BUILD_FORMS_QML
+      # rungs) and Ubuntu 24.04 still ships 6.4.2 — the exact gap the "all
+      # optional features" job's identical step already documents. This job
+      # configures MORPH_BUILD_LADDER=ON without MORPH_BUILD_FORMS_QML, but
+      # examples/common/CMakeLists.txt's Qt6 6.5 REQUIRED applies unconditionally
+      # (it is not gated on MORPH_BUILD_FORMS_QML), so the floor still bites here.
+      - name: Install Qt ${{ env.QT_VERSION }}
+        if: steps.filter.outputs.run == 'true'
+        uses: jurplel/install-qt-action@v4
+        with:
+          version: ${{ env.QT_VERSION }}
+          modules: qtwebsockets
+          cache: true
+
+      - name: Cache sccache
+        if: steps.filter.outputs.run == 'true'
+        uses: actions/cache@v4
+        with:
+          path: /home/runner/.cache/sccache
+          key: sccache-ladder-${{ github.sha }}
+          restore-keys: sccache-ladder-
+
+      - name: Install sccache
+        if: steps.filter.outputs.run == 'true'
+        run: |
+          curl -sSL https://github.com/mozilla/sccache/releases/download/v0.9.1/sccache-v0.9.1-x86_64-unknown-linux-musl.tar.gz \
+            | tar -xz --strip-components=1 -C /usr/local/bin sccache-v0.9.1-x86_64-unknown-linux-musl/sccache
+
+      - name: Configure (gcc-debug, ladder + Qt on)
+        if: steps.filter.outputs.run == 'true'
+        run: |
+          cmake --preset gcc-debug \
+            -DMORPH_BUILD_QT=ON \
+            -DMORPH_BUILD_LADDER=ON \
+            -DMORPH_LADDER_RUNGS=all \
+            -DCMAKE_C_COMPILER_LAUNCHER=sccache \
+            -DCMAKE_CXX_COMPILER_LAUNCHER=sccache
+
+      - name: Build
+        if: steps.filter.outputs.run == 'true'
+        run: cmake --build --preset gcc-debug
+
+      - name: Test (offscreen Qt platform, ladder tests only, stress excluded)
+        if: steps.filter.outputs.run == 'true'
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: ctest --preset gcc-debug -L ladder -LE stress --output-on-failure
+
   # ── Linux: every optional feature enabled at once ─────────────────────
   # Every MORPH_BUILD_* option below is off by default, and until this job
   # existed no CI configuration turned any of them on — so several thousand
@@ -292,8 +452,21 @@ jobs:
           sudo apt-get install -y software-properties-common
           sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
           sudo apt-get update -q
+          # unixodbc-dev + libsqliteodbc: the application ladder (enabled in
+          # the configure step below) fetches the Lightweight ORM, whose CMake
+          # runs `pkg_check_modules(ODBC REQUIRED odbc)`, and whose ladder
+          # fixtures open a real `DRIVER=SQLite3` connection at test time.
+          # Named explicitly rather than relied on from the runner image.
+          # libyaml-cpp-dev + libzip-dev: Lightweight's own CMakeLists.txt
+          # (examples/bank/CMakeLists.txt's comment on the same fetch) does
+          # `find_package(yaml-cpp)`/`find_package(libzip)` as system CONFIG
+          # packages, not through CPM — without these, Lightweight's configure
+          # fails with "could not find a package configuration file" the
+          # moment MORPH_BUILD_LADDER=ON pulls it in here.
           sudo apt-get install -y ninja-build catch2 \
             libsqlite3-dev libsodium-dev libssl-dev \
+            unixodbc-dev libsqliteodbc \
+            libyaml-cpp-dev libzip-dev \
             libgl1-mesa-dev libxkbcommon-x11-0 libxcb-cursor0 libxcb-icccm4 \
             libxcb-keysyms1 libxcb-shape0 libxcb-xinerama0
           if [ "${{ matrix.compiler }}" = "gcc" ]; then
@@ -336,10 +509,22 @@ jobs:
             EXTRA="-DCMAKE_C_COMPILER=clang-${{ env.CLANG_VERSION }} -DCMAKE_CXX_COMPILER=clang++-${{ env.CLANG_VERSION }}"
           fi
           # shellcheck disable=SC2086
+          # MORPH_BUILD_LADDER belongs in this job by its own charter ("every
+          # MORPH_BUILD_* option … enabling them together also proves they
+          # compose") and closes a real hole: until it was added here, *no* CI
+          # leg configured MORPH_BUILD_LADDER=ON together with
+          # MORPH_BUILD_FORMS_QML=ON. The ladder-tests job below cannot — its
+          # distro Qt is 6.4.2, under the 6.5 floor MORPH_BUILD_FORMS_QML
+          # requires — so each rung's QML module, desktop client and offscreen
+          # engine-load smoke test were built by nothing at all. This job has
+          # Qt ${{ env.QT_VERSION }} from aqtinstall, so here they are built,
+          # and the smoke test runs, on every push.
           cmake --preset ${{ matrix.preset }} \
             -DMORPH_BUILD_NET=ON \
             -DMORPH_BUILD_QT=ON \
             -DMORPH_BUILD_FORMS_QML=ON \
+            -DMORPH_BUILD_LADDER=ON \
+            -DMORPH_LADDER_RUNGS=all \
             -DMORPH_BUILD_OFFLINE_SQLITE=ON \
             -DMORPH_BUILD_LOAD_TESTS=ON \
             -DMORPH_BUILD_HMAC_EXAMPLES=ON \

.github/workflows/wasm-ladder.yml

@@ -0,0 +1,149 @@
+name: WASM ladder gate
+
+# Compile gate for the application ladder's WebAssembly clients — the one
+# examples/TESTING.md's CI tiering promises ("the WASM compile gate for the
+# affected rungs") and the only thing in this repository that can actually
+# verify them: no Emscripten toolchain was available where rung 0's WASM-remote
+# spike (examples/common/wasm_spike) or rung 1's WASM client
+# (examples/pastebin/gui_wasm) were authored, so both shipped structurally
+# complete and never compiled. Until this job runs green, treat every WASM
+# target here as unverified.
+#
+# Deliberately separate from wasm-demo.yml (bank's WASM GUI): different sources,
+# different path filter, and nothing here is deployed anywhere — this builds and
+# stops. Single-threaded Qt-for-WASM, same as that workflow.
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - 'examples/common/**'
+      - 'examples/pastebin/**'
+      - 'examples/bookmarks/**'
+      - 'examples/polls/**'
+      - 'examples/kanban/**'
+      - 'examples/CMakeLists.txt'
+      - 'cmake/**'
+      - 'include/morph/**'
+      - 'src/qt/**'
+      - 'CMakeLists.txt'
+      - '.github/workflows/wasm-ladder.yml'
+  pull_request:
+    branches:
+      - master
+    paths:
+      - 'examples/common/**'
+      - 'examples/pastebin/**'
+      - 'examples/bookmarks/**'
+      - 'examples/polls/**'
+      - 'examples/kanban/**'
+      - 'examples/CMakeLists.txt'
+      - 'cmake/**'
+      - 'include/morph/**'
+      - 'src/qt/**'
+      - 'CMakeLists.txt'
+      - '.github/workflows/wasm-ladder.yml'
+
+concurrency:
+  group: wasm-ladder-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  QT_VERSION: 6.8.3
+  EMSDK_VERSION: 3.1.56   # the emscripten Qt 6.8 was built against
+
+jobs:
+  build-ladder-wasm:
+    name: Build the ladder's WASM clients
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install build tools
+        run: |
+          sudo apt-get update -q
+          sudo apt-get install -y ninja-build
+
+      # aqtinstall gives a matched host + wasm Qt pair (same cmake glue), so no
+      # host/target version skew. qtwebsockets on *both*: morph::qt links
+      # Qt6::WebSockets, and a ladder WASM client is a remote client by rule
+      # (examples/IMPLEMENTATION.md rule 4's WASM clause), so the transport is
+      # not optional here the way it is for bank's local-only demo.
+      - name: Install Qt (host desktop)
+        uses: jurplel/install-qt-action@v4
+        with:
+          version: ${{ env.QT_VERSION }}
+          host: linux
+          target: desktop
+          arch: linux_gcc_64
+          modules: qtwebsockets
+          dir: ${{ runner.temp }}/qt
+
+      - name: Install Qt (wasm, single-threaded)
+        uses: jurplel/install-qt-action@v4
+        with:
+          version: ${{ env.QT_VERSION }}
+          host: all_os
+          target: wasm
+          arch: wasm_singlethread
+          modules: qtwebsockets
+          dir: ${{ runner.temp }}/qt
+
+      - name: Set up emsdk
+        uses: mymindstorm/setup-emsdk@v14
+        with:
+          version: ${{ env.EMSDK_VERSION }}
+          actions-cache-folder: emsdk-ladder-cache
+
+      # MORPH_CLIENT_ONLY is mandatory, not a tuning knob: a rung's presenters
+      # are BridgeHandler<Model> templates, so the client names its model type
+      # even though it never hosts one — and without this option morph still
+      # emits the registrars that closure over that model's ODBC-backed
+      # execute() bodies, which cannot link in a browser
+      # (docs/spec/core/registry.md). morph_add_rung() fails the configure with
+      # that explanation if it is missing.
+      #
+      # MORPH_BUILD_TESTS=OFF: Catch2 binaries are not browser artifacts, and
+      # examples/common/CMakeLists.txt returns before its Catch2/Lightweight
+      # section under Emscripten for exactly that reason.
+      - name: Configure
+        run: |
+          export EM_CACHE="$PWD/.emcache"
+          mkdir -p "$EM_CACHE"
+          HOST=${{ runner.temp }}/qt/Qt/${{ env.QT_VERSION }}/gcc_64
+          WASM=${{ runner.temp }}/qt/Qt/${{ env.QT_VERSION }}/wasm_singlethread
+          # The all_os/wasm package extracts its scripts without the exec bit.
+          chmod +x "$WASM"/bin/* || true
+          "$WASM/bin/qt-cmake" -S . -B build-wasm-ladder -G Ninja \
+            -DQT_HOST_PATH="$HOST" \
+            -DMORPH_BUILD_QT=ON \
+            -DMORPH_BUILD_FORMS_QML=ON \
+            -DMORPH_BUILD_LADDER=ON \
+            -DMORPH_LADDER_RUNGS=all \
+            -DMORPH_CLIENT_ONLY=ON \
+            -DMORPH_BUILD_TESTS=OFF \
+            -DMORPH_BUILD_EXAMPLES=OFF
+
+      # The rung-0 spike and rungs 1-3's clients, built by name so a target
+      # that silently stops being generated (morph_add_rung() skips a rung's
+      # gui_wasm when its prerequisites are missing, announcing why) fails this
+      # job instead of passing it vacuously. The plain build that follows
+      # covers any further rung automatically, so this file does not need
+      # editing again just to add another named target.
+      - name: Build the WASM-remote spike and every rung's WASM client
+        run: |
+          export EM_CACHE="$PWD/.emcache"
+          cmake --build build-wasm-ladder --target morph_ladder_wasm_spike
+          cmake --build build-wasm-ladder --target ladder_pastebin_gui_wasm
+          cmake --build build-wasm-ladder --target ladder_bookmarks_gui_wasm
+          cmake --build build-wasm-ladder --target ladder_polls_gui_wasm
+          # Catches any further rung's WASM client too, without editing this
+          # file again -- closing the gap rung 1's own final review flagged.
+          cmake --build build-wasm-ladder
+
+      # Informational: the build steps above are the gate. Listed rather than
+      # asserted by path, since where Qt drops a wasm bundle is Qt's business.
+      - name: Show the produced artifacts
+        run: find build-wasm-ladder -name '*.wasm' -o -name '*.html' | sort