ladder: rung 4 -- kanban

.github/workflows/ci.yml

@@ -302,6 +302,126 @@ jobs:
           name: coverage-report
           path: build/clang-coverage/html/
 
+  # ── Linux: kanban's concurrent-move stress test under ThreadSanitizer ──
+  # test_kanban_stress.cpp's [tsan]-tagged TEST_CASE drives BoardModel through
+  # a bare morph::bridge::Bridge/morph::backend::LocalBackend directly, on a
+  # real morph::exec::ThreadPoolExecutor{4}, with zero Qt frames anywhere in
+  # its call graph (see the test file's own header comment) -- so the "a GUI
+  # stack under TSan is mostly noise" rationale that keeps the ladder out of
+  # linux-sanitizers does not apply to this one test. This job builds only
+  # what that test needs -- MORPH_BUILD_LADDER=ON, MORPH_LADDER_RUNGS=kanban,
+  # no Qt GUI modules beyond the WebSockets backend the ladder testkit itself
+  # requires -- to keep it a minimal, fast, TSan-clean addition rather than
+  # pulling every rung's Qt Quick/QML code into the sanitizer matrix.
+  #
+  # (History: an earlier version of this test drove the same scenario through
+  # BackendRig{Mode::Local, ...}, whose Mode::Local unconditionally
+  # constructs a real morph::qt::QtExecutor for client-facing callback
+  # delivery -- morph#128 found 165 ThreadSanitizer warnings bottoming out in
+  # genuine Qt-internal frames reached through it, undetectable as real bugs
+  # or false positives from outside a TSan-instrumented Qt build. Rewriting
+  # the test to never construct a QtExecutor at all sidesteps the ambiguity
+  # entirely rather than resolving it.)
+  kanban-tsan:
+    name: Kanban / ThreadSanitizer
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cache apt packages
+        uses: actions/cache@v4
+        with:
+          path: /var/cache/apt/archives
+          key: apt-kanban-tsan-${{ hashFiles('.github/workflows/ci.yml') }}
+          restore-keys: apt-kanban-tsan-
+
+      - name: Install Clang ${{ env.CLANG_VERSION }} from apt.llvm.org
+        run: |
+          sudo apt-get update -q
+          # unixodbc-dev + libsqliteodbc: the ladder (built by this job)
+          # fetches the Lightweight ORM, whose CMake runs
+          # `pkg_check_modules(ODBC REQUIRED odbc)`, and whose DbFixture
+          # opens a real `DRIVER=SQLite3` connection at test time (identical
+          # rationale to linux-sanitizers' coverage-leg step and ladder-tests'
+          # own install step). 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.
+          # libgl1-mesa-dev: every other job that configures MORPH_BUILD_QT=ON
+          # together with MORPH_BUILD_LADDER=ON installs this (linux-sanitizers'
+          # coverage leg, ladder-tests, linux-all-features) for Qt's GL platform
+          # integration; carried here for the same reason even though this leg's
+          # test run itself stays off-GUI.
+          sudo apt-get install -y ninja-build catch2 libsqlite3-dev \
+            unixodbc-dev libsqliteodbc libyaml-cpp-dev libzip-dev libgl1-mesa-dev
+          wget -qO- https://apt.llvm.org/llvm.sh | sudo bash -s -- ${{ env.CLANG_VERSION }}
+
+      # Not the distro's Qt: examples/common/CMakeLists.txt requires 6.5+
+      # unconditionally and Ubuntu 24.04 still ships 6.4.2 — the same gap
+      # every other job that builds the ladder on Linux already documents.
+      - name: Install Qt ${{ env.QT_VERSION }}
+        uses: jurplel/install-qt-action@v4
+        with:
+          version: ${{ env.QT_VERSION }}
+          modules: qtwebsockets
+          cache: true
+
+      - name: Cache sccache
+        uses: actions/cache@v4
+        with:
+          path: /home/runner/.cache/sccache
+          key: sccache-kanban-tsan-${{ github.sha }}
+          restore-keys: sccache-kanban-tsan-
+
+      - name: Install sccache
+        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
+
+      # MORPH_LADDER_RUNGS=kanban (a single rung, not "all"): examples/CMakeLists.txt's
+      # rung-selection loop (`if(MORPH_LADDER_RUNGS STREQUAL "all" OR _rung IN_LIST
+      # MORPH_LADDER_RUNGS)`) matches a single-value list correctly, and examples/common
+      # (the testkit every rung's tests link) is always added regardless of which rungs
+      # are selected — so this configures and builds only kanban's ladder targets, not
+      # the whole ladder.
+      - name: Configure (clang-tsan, kanban only)
+        run: |
+          cmake --preset clang-tsan \
+            -DMORPH_BUILD_QT=ON \
+            -DMORPH_BUILD_LADDER=ON \
+            -DMORPH_LADDER_RUNGS=kanban \
+            -DCMAKE_C_COMPILER=clang-${{ env.CLANG_VERSION }} \
+            -DCMAKE_CXX_COMPILER=clang++-${{ env.CLANG_VERSION }} \
+            -DCMAKE_C_COMPILER_LAUNCHER=sccache \
+            -DCMAKE_CXX_COMPILER_LAUNCHER=sccache
+
+      # QT_QPA_PLATFORM=offscreen here too, not just on Test below: Catch2's
+      # catch_discover_tests() runs ladder_kanban_tests once at BUILD time to
+      # enumerate its cases, which can abort on this headless runner (no X
+      # server) without it — see linux-sanitizers' and ladder-tests' own Build
+      # steps for the identical note.
+      - name: Build
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: cmake --build --preset clang-tsan
+
+      # Every ladder ctest case only ever carries the "ladder"/"ladder-<rung>"
+      # labels morph_add_rung() applies (cmake/morph_add_rung.cmake) — Catch2's
+      # own tags ([kanban][stress][tsan]) are never translated into ctest
+      # labels anywhere in this repo's CMake (no catch_discover_tests call
+      # passes ADD_TAGS_AS_LABELS). A "-L tsan" filter would therefore match
+      # zero tests and silently run nothing. This test's name is the only
+      # thing distinguishing it, and "ThreadSanitizer" appears in exactly one
+      # TEST_CASE name across the whole kanban tree (confirmed by grep), so
+      # -R selects it precisely.
+      - name: Test (kanban's TSan-tagged stress test only)
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: ctest --preset clang-tsan -L ladder-kanban -R ThreadSanitizer --output-on-failure
+
   # ── Linux: Qt WebSocket backend build + tests ─────────────────────────
   linux-qt:
     name: Linux / Qt6 WebSockets

CMakeLists.txt

@@ -213,6 +213,48 @@ target_sources(morph
         include/morph/render/locale_format.hpp
 )
 
+# ── SQLite-backed durable offline queue: library target (optional) ──────────
+# Only the morph::offline_sqlite target itself is created here, deliberately
+# ahead of "Application ladder"'s add_subdirectory(examples) further below:
+# examples/kanban/CMakeLists.txt links morph::offline_sqlite (a namespaced
+# target, which CMake requires to already exist at the point it is named --
+# see the identical note on morph::qt_forms vs the plain
+# morph_forms_moduleplugin just below). The tests/offline_sqlite subdirectory
+# that also depends on MORPH_BUILD_OFFLINE_SQLITE stays deferred to its
+# original spot, after the "Tests" section, since it links
+# Catch2::Catch2WithMain and that target only exists once Catch2 has been
+# found/fetched there.
+if(MORPH_BUILD_OFFLINE_SQLITE)
+    find_package(SQLite3 REQUIRED)
+
+    # FindSQLite3 reports success but does not always leave `SQLite3::SQLite3`
+    # resolvable at generate time (observed on the ubuntu-24.04 runner, which
+    # fails with "the link interface ... contains SQLite3::SQLite3 but the
+    # target was not found" while printing "Found SQLite3" moments earlier).
+    # Synthesise the target from the variables the module *does* set, and
+    # promote it to GLOBAL either way so every subdirectory that consumes
+    # morph::offline_sqlite can see it.
+    if(NOT TARGET SQLite3::SQLite3)
+        add_library(SQLite3::SQLite3 UNKNOWN IMPORTED GLOBAL)
+        set_target_properties(SQLite3::SQLite3 PROPERTIES
+            IMPORTED_LOCATION "${SQLite3_LIBRARIES}"
+            INTERFACE_INCLUDE_DIRECTORIES "${SQLite3_INCLUDE_DIRS}")
+    else()
+        set_target_properties(SQLite3::SQLite3 PROPERTIES IMPORTED_GLOBAL TRUE)
+    endif()
+
+    add_library(morph_offline_sqlite INTERFACE)
+    add_library(morph::offline_sqlite ALIAS morph_offline_sqlite)
+    target_link_libraries(morph_offline_sqlite INTERFACE morph SQLite3::SQLite3)
+    target_sources(morph_offline_sqlite
+        INTERFACE
+        FILE_SET HEADERS
+        BASE_DIRS include
+        FILES
+            include/morph/offline/sqlite_offline_queue.hpp
+    )
+endif()
+
 # ── Qt/QML forms renderer setup (optional) ───────────────────────────────────
 # Ships the reference Qt/QML renderer (MorphForms, src/qt/forms) as a reusable
 # component, independent of MORPH_BUILD_EXAMPLES. examples/forms/gui_qml
@@ -420,40 +462,14 @@ if(MORPH_BUILD_NET)
     endif()
 endif()
 
-# ── SQLite-backed durable offline queue (optional) ──────────────────────────
-if(MORPH_BUILD_OFFLINE_SQLITE)
-    find_package(SQLite3 REQUIRED)
-
-    # FindSQLite3 reports success but does not always leave `SQLite3::SQLite3`
-    # resolvable at generate time (observed on the ubuntu-24.04 runner, which
-    # fails with "the link interface ... contains SQLite3::SQLite3 but the
-    # target was not found" while printing "Found SQLite3" moments earlier).
-    # Synthesise the target from the variables the module *does* set, and
-    # promote it to GLOBAL either way so every subdirectory that consumes
-    # morph::offline_sqlite can see it.
-    if(NOT TARGET SQLite3::SQLite3)
-        add_library(SQLite3::SQLite3 UNKNOWN IMPORTED GLOBAL)
-        set_target_properties(SQLite3::SQLite3 PROPERTIES
-            IMPORTED_LOCATION "${SQLite3_LIBRARIES}"
-            INTERFACE_INCLUDE_DIRECTORIES "${SQLite3_INCLUDE_DIRS}")
-    else()
-        set_target_properties(SQLite3::SQLite3 PROPERTIES IMPORTED_GLOBAL TRUE)
-    endif()
-
-    add_library(morph_offline_sqlite INTERFACE)
-    add_library(morph::offline_sqlite ALIAS morph_offline_sqlite)
-    target_link_libraries(morph_offline_sqlite INTERFACE morph SQLite3::SQLite3)
-    target_sources(morph_offline_sqlite
-        INTERFACE
-        FILE_SET HEADERS
-        BASE_DIRS include
-        FILES
-            include/morph/offline/sqlite_offline_queue.hpp
-    )
-
-    if(MORPH_BUILD_TESTS)
-        add_subdirectory(tests/offline_sqlite)
-    endif()
+# ── SQLite-backed durable offline queue: tests (optional) ───────────────────
+# The morph::offline_sqlite target itself is created much earlier (see
+# "SQLite-backed durable offline queue: library target" above, before
+# "Application ladder"'s add_subdirectory(examples)) -- only this suite's own
+# subdirectory stays deferred to here, since it links Catch2::Catch2WithMain
+# and Catch2 is only found/fetched in the "Tests" section just above.
+if(MORPH_BUILD_OFFLINE_SQLITE AND MORPH_BUILD_TESTS)
+    add_subdirectory(tests/offline_sqlite)
 endif()
 
 # ── Documentation ───────────────────────────────────────────────────────────

cmake/morph_add_rung.cmake

@@ -139,6 +139,15 @@ function(morph_add_rung)
             if(AF_COVERAGE)
                 apply_coverage(ladder_${_rung}_lib)
             endif()
+            # AF_SANITIZER (asan/tsan/ubsan): applied the same way apply_coverage()
+            # is above. Without this, a --preset clang-tsan build of the ladder
+            # compiles this target (a rung's models -- the code kanban-tsan's
+            # stress test actually races on) with no sanitizer instrumentation at
+            # all, silently defeating the whole point of building under that
+            # preset. See .github/workflows/ci.yml's kanban-tsan job.
+            if(DEFINED AF_SANITIZER)
+                apply_sanitizers(ladder_${_rung}_lib ${AF_SANITIZER})
+            endif()
         endif()
     endif()
 
@@ -178,6 +187,10 @@ function(morph_add_rung)
         if(AF_COVERAGE)
             apply_coverage(ladder_${_rung}_gui_lib)
         endif()
+        # See ladder_${_rung}_lib's identical AF_SANITIZER block above.
+        if(DEFINED AF_SANITIZER)
+            apply_sanitizers(ladder_${_rung}_gui_lib ${AF_SANITIZER})
+        endif()
     endif()
 
     # ── ladder_<rung>_qml: the rung's own QML module ─────────────────────
@@ -291,6 +304,10 @@ function(morph_add_rung)
             if(AF_COVERAGE)
                 apply_coverage(ladder_${_rung}_gui)
             endif()
+            # See ladder_${_rung}_lib's identical AF_SANITIZER block above.
+            if(DEFINED AF_SANITIZER)
+                apply_sanitizers(ladder_${_rung}_gui ${AF_SANITIZER})
+            endif()
         endif()
     endif()
 
@@ -363,6 +380,10 @@ function(morph_add_rung)
             if(AF_COVERAGE)
                 apply_coverage(ladder_${_rung}_server)
             endif()
+            # See ladder_${_rung}_lib's identical AF_SANITIZER block above.
+            if(DEFINED AF_SANITIZER)
+                apply_sanitizers(ladder_${_rung}_server ${AF_SANITIZER})
+            endif()
         endif()
     endif()
 
@@ -458,6 +479,16 @@ function(morph_add_rung)
             if(AF_COVERAGE)
                 apply_coverage(ladder_${_rung}_tests)
             endif()
+            # AF_SANITIZER (asan/tsan/ubsan): applied the same way apply_coverage()
+            # is above. This is the target kanban's [tsan]-tagged stress test
+            # actually links and runs from -- without this, a --preset clang-tsan
+            # build compiles it with no sanitizer instrumentation at all, and
+            # .github/workflows/ci.yml's kanban-tsan job would build and pass
+            # while never actually exercising ThreadSanitizer over the code it
+            # claims to cover.
+            if(DEFINED AF_SANITIZER)
+                apply_sanitizers(ladder_${_rung}_tests ${AF_SANITIZER})
+            endif()
 
             include(Catch)
             get_target_property(_qt_core_dll Qt6::Core IMPORTED_LOCATION)