Production-hardening + GUI enhancement program (28 items) + 2 security fixes

.github/workflows/ci.yml

@@ -9,6 +9,8 @@ env:
   VCPKG_BINARY_SOURCES: "clear;x-gha,readwrite"
   SCCACHE_DIR: /home/runner/.cache/sccache
   CLANG_VERSION: "22"
+  # MORPH_BUILD_FORMS_QML needs Qt 6.5+; ubuntu-24.04 apt still ships 6.4.2.
+  QT_VERSION: "6.8.1"
 
 jobs:
   # ── Windows: MSVC + clang-cl ──────────────────────────────────────────
@@ -139,7 +141,7 @@ jobs:
       - name: Install Clang ${{ env.CLANG_VERSION }} from apt.llvm.org
         run: |
           sudo apt-get update -q
-          sudo apt-get install -y ninja-build catch2
+          sudo apt-get install -y ninja-build catch2 libsqlite3-dev
           wget -qO- https://apt.llvm.org/llvm.sh | sudo bash -s -- ${{ env.CLANG_VERSION }}
 
       - name: Cache sccache
@@ -154,9 +156,17 @@ jobs:
           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::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.
       - name: Configure
         run: |
           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 \
@@ -243,6 +253,129 @@ jobs:
           QT_QPA_PLATFORM: offscreen
         run: ctest --preset gcc-debug
 
+  # ── 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
+  # lines (morph::net, the Qt/QML forms renderer, the SQLite queue, the fuzz
+  # harnesses, the vetted-HMAC adapters, the soak/bench targets) were never
+  # compiled here, let alone tested. That is how a build that cannot configure
+  # (MORPH_REQUIRE_VETTED_HMAC) and a replay test matching the wrong file
+  # extension both reached master green. Enabling them together also proves
+  # they compose, which building each alone would not.
+  linux-all-features:
+    name: Linux / all optional features (${{ matrix.compiler }})
+    runs-on: ubuntu-24.04
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # Clang additionally builds the libFuzzer harnesses, which require it.
+          - compiler: clang
+            preset: clang-debug
+            fuzzers: 'ON'
+          - compiler: gcc
+            preset: gcc-debug
+            fuzzers: 'OFF'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cache apt packages
+        uses: actions/cache@v4
+        with:
+          path: /var/cache/apt/archives
+          key: apt-all-features-${{ matrix.compiler }}-${{ hashFiles('.github/workflows/ci.yml') }}
+          restore-keys: apt-all-features-${{ matrix.compiler }}-
+
+      - name: Install toolchain and the non-Qt dependencies
+        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
+          sudo apt-get install -y ninja-build catch2 \
+            libsqlite3-dev libsodium-dev libssl-dev \
+            libgl1-mesa-dev libxkbcommon-x11-0 libxcb-cursor0 libxcb-icccm4 \
+            libxcb-keysyms1 libxcb-shape0 libxcb-xinerama0
+          if [ "${{ matrix.compiler }}" = "gcc" ]; then
+            sudo apt-get install -y gcc-15 g++-15
+            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
+          else
+            wget -qO- https://apt.llvm.org/llvm.sh | sudo bash -s -- ${{ env.CLANG_VERSION }}
+          fi
+
+      # Not the distro's Qt: MORPH_BUILD_FORMS_QML needs 6.5+ (see the version
+      # floor in CMakeLists.txt) and Ubuntu 24.04 still ships 6.4.2, whose
+      # QQmlApplicationEngine has no loadFromModule.
+      - 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-all-features-${{ matrix.compiler }}-${{ github.sha }}
+          restore-keys: sccache-all-features-${{ matrix.compiler }}-
+
+      - 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_REQUIRE_VETTED_HMAC is deliberately combined with
+      # MORPH_BUILD_TESTS=ON (the preset default). docs/spec/security.md
+      # documents that pairing as supported; this is what keeps it that way.
+      - name: Configure (every optional feature ON)
+        run: |
+          EXTRA=""
+          if [ "${{ matrix.compiler }}" = "clang" ]; then
+            EXTRA="-DCMAKE_C_COMPILER=clang-${{ env.CLANG_VERSION }} -DCMAKE_CXX_COMPILER=clang++-${{ env.CLANG_VERSION }}"
+          fi
+          # shellcheck disable=SC2086
+          cmake --preset ${{ matrix.preset }} \
+            -DMORPH_BUILD_NET=ON \
+            -DMORPH_BUILD_QT=ON \
+            -DMORPH_BUILD_FORMS_QML=ON \
+            -DMORPH_BUILD_OFFLINE_SQLITE=ON \
+            -DMORPH_BUILD_LOAD_TESTS=ON \
+            -DMORPH_BUILD_HMAC_EXAMPLES=ON \
+            -DMORPH_BUILD_FUZZERS=${{ matrix.fuzzers }} \
+            -DMORPH_REQUIRE_VETTED_HMAC=ON \
+            $EXTRA \
+            -DCMAKE_C_COMPILER_LAUNCHER=sccache \
+            -DCMAKE_CXX_COMPILER_LAUNCHER=sccache
+
+      - name: Build
+        run: cmake --build --preset ${{ matrix.preset }}
+
+      # Includes the fuzz *replay* tests on the clang leg: each committed seed
+      # and crash reproducer is replayed once and must not crash. This is a
+      # deterministic regression check, not a fuzzing campaign.
+      - name: Test (offscreen Qt platform)
+        env:
+          QT_QPA_PLATFORM: offscreen
+        run: ctest --preset ${{ matrix.preset }} --output-on-failure
+
+      # A guard that never fires is indistinguishable from one that works, so
+      # assert the fuzz replay actually ran the committed crash reproducers
+      # rather than silently matching nothing (the `.txt`-vs-`.bin` glob bug).
+      - name: Verify the fuzz replay covered the committed reproducers
+        if: matrix.fuzzers == 'ON'
+        run: |
+          ctest --preset ${{ matrix.preset }} -R fuzz -V > fuzz-replay.log 2>&1
+          status=0
+          for finding in tests/fuzz/findings/*/*; do
+            if ! grep -qF "$(basename "$finding")" fuzz-replay.log; then
+              echo "::error::fuzz replay never referenced committed reproducer $finding"
+              status=1
+            fi
+          done
+          exit "$status"
+
   # ── Valgrind (memcheck) ───────────────────────────────────────────────
   valgrind:
     name: Valgrind memcheck
@@ -279,22 +412,41 @@ jobs:
           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::net and the SQLite queue are where the raw pointers, manual
+      # buffers and C API calls live — precisely what memcheck is for — so they
+      # are built here rather than left to the default (Qt/QML stays out: it
+      # drags in a GUI stack whose own allocations dominate the report).
       - name: Configure
-        run: cmake --preset gcc-debug -DCMAKE_C_COMPILER_LAUNCHER=sccache -DCMAKE_CXX_COMPILER_LAUNCHER=sccache
+        run: |
+          cmake --preset gcc-debug \
+            -DMORPH_BUILD_NET=ON \
+            -DMORPH_BUILD_OFFLINE_SQLITE=ON \
+            -DCMAKE_C_COMPILER_LAUNCHER=sccache \
+            -DCMAKE_CXX_COMPILER_LAUNCHER=sccache
 
       - name: Build
         run: cmake --build --preset gcc-debug
 
       - name: Run tests under Valgrind
         run: |
-          valgrind \
-            --tool=memcheck \
-            --leak-check=full \
-            --show-leak-kinds=definite,indirect \
-            --errors-for-leak-kinds=definite,indirect \
-            --error-exitcode=1 \
-            --suppressions=cmake/valgrind.supp \
-            build/gcc-debug/tests/morph_tests
+          status=0
+          for suite in tests/morph_tests tests/net/morph_net_tests tests/offline_sqlite/morph_offline_sqlite_tests; do
+            binary="build/gcc-debug/$suite"
+            if [ ! -x "$binary" ]; then
+              echo "::error::expected Valgrind suite $binary was not built"
+              exit 1
+            fi
+            echo "── memcheck: $suite ──"
+            valgrind \
+              --tool=memcheck \
+              --leak-check=full \
+              --show-leak-kinds=definite,indirect \
+              --errors-for-leak-kinds=definite,indirect \
+              --error-exitcode=1 \
+              --suppressions=cmake/valgrind.supp \
+              "$binary" || status=1
+          done
+          exit "$status"
 
   # ── clang-tidy-diff (changed lines only) ──────────────────────────────
   clang-tidy:
@@ -312,13 +464,24 @@ jobs:
           key: apt-clang-tidy-${{ hashFiles('.github/workflows/ci.yml') }}
           restore-keys: apt-clang-tidy-
 
-      - name: Install Clang ${{ env.CLANG_VERSION }} and clang-tidy from apt.llvm.org
+      - name: Install Clang ${{ env.CLANG_VERSION }}, clang-tidy, and the non-Qt deps
         run: |
           sudo apt-get update -q
-          sudo apt-get install -y ninja-build catch2
+          sudo apt-get install -y ninja-build catch2 \
+            libsqlite3-dev libsodium-dev libssl-dev \
+            libgl1-mesa-dev libxkbcommon-x11-0 libxcb-cursor0 libxcb-icccm4 \
+            libxcb-keysyms1 libxcb-shape0 libxcb-xinerama0
           wget -qO- https://apt.llvm.org/llvm.sh | sudo bash -s -- ${{ env.CLANG_VERSION }}
           sudo apt-get install -y clang-tidy-${{ env.CLANG_VERSION }}
 
+      # See the linux-all-features job: the QML renderer needs Qt 6.5+.
+      - 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:
@@ -331,9 +494,22 @@ jobs:
           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 (generates compile_commands.json)
+      # Every optional feature is ON here purely so its sources land in
+      # compile_commands.json. clang-tidy only ever analyses *changed lines*, so
+      # this costs a wider build, not a wider lint. Configured narrowly before,
+      # the whole opt-in surface — morph::net, the Qt transport, the QML forms
+      # renderer, the SQLite queue, the fuzz harnesses — was invisible to the
+      # one gate in this workflow that reads code rather than running it.
+      - name: Configure (generates compile_commands.json over every optional feature)
         run: |
           cmake --preset clang-debug \
+            -DMORPH_BUILD_NET=ON \
+            -DMORPH_BUILD_QT=ON \
+            -DMORPH_BUILD_FORMS_QML=ON \
+            -DMORPH_BUILD_OFFLINE_SQLITE=ON \
+            -DMORPH_BUILD_LOAD_TESTS=ON \
+            -DMORPH_BUILD_HMAC_EXAMPLES=ON \
+            -DMORPH_BUILD_FUZZERS=ON \
             -DCMAKE_C_COMPILER=clang-${{ env.CLANG_VERSION }} \
             -DCMAKE_CXX_COMPILER=clang++-${{ env.CLANG_VERSION }} \
             -DCMAKE_C_COMPILER_LAUNCHER=sccache \
@@ -374,3 +550,20 @@ jobs:
         with:
           name: clang-tidy-report
           path: clang-tidy-report.txt
+
+  # ── Deprecation-marker format lint ────────────────────────────────────
+  deprecation-lint:
+    name: Deprecation marker format
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      # The checker itself is tested first. A lint gate nobody tests reports
+      # green whether or not it still detects anything — this one was blind to
+      # both the bare `[[deprecated]]` form and any message wrapped across
+      # lines, which is exactly what VERSIONING.md forbids.
+      - name: Self-test the deprecation-marker checker
+        run: bash scripts/test_check_deprecated_markers.sh
+
+      - name: Check [[deprecated]] markers cite a replacement and removal version
+        run: bash scripts/check_deprecated_markers.sh include/morph

.github/workflows/docs.yml

@@ -37,10 +37,22 @@ jobs:
           sudo apt-get install -y software-properties-common
           sudo add-apt-repository -y ppa:ubuntu-toolchain-r/test
           sudo apt-get update -q
-          sudo apt-get install -y cmake ninja-build doxygen g++-15
+          sudo apt-get install -y cmake ninja-build g++-15
           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
 
+      # Ubuntu 24.04's apt package is Doxygen 1.9.8, which misreports several
+      # correctly-documented symbols as undocumented (confirmed: two template
+      # overloads of the same free function, and a function immediately
+      # following a file-level doc comment both trip its param/return
+      # association) -- fixed upstream by 1.15.0. Install a release binary
+      # instead of relying on the distro package.
+      - name: Install Doxygen 1.17.0
+        run: |
+          curl -sL https://github.com/doxygen/doxygen/releases/download/Release_1_17_0/doxygen-1.17.0.linux.bin.tar.gz -o /tmp/doxygen.tar.gz
+          tar -xzf /tmp/doxygen.tar.gz -C /tmp
+          echo "/tmp/doxygen-1.17.0/bin" >> "$GITHUB_PATH"
+
       - name: Configure (docs target only)
         run: |
           cmake -S . -B build -G Ninja \

.github/workflows/drift-guard.yml

@@ -0,0 +1,39 @@
+name: Drift guard
+
+# Two independent gates for the "spec <-> code drift" class of bug (a
+# docs/spec/*.md file stating a mechanical fact -- an enum cardinality, a
+# constant, a canonical error string, a glaze parsing flag -- that silently
+# stops matching the code):
+#
+#   1. The compiled pinned-facts test (tests/test_pinned_facts.cpp) needs no
+#      job here: it is already part of the `morph_tests` target, so it runs
+#      in every job of the main CI workflow (.github/workflows/ci.yml) for
+#      free, and benefits from running under every compiler in that matrix
+#      (GCC, Clang, MSVC, clang-cl) since the enum-cardinality switch pins
+#      (see tests/test_pinned_facts.cpp) rely on compiler-specific warning
+#      behavior that is worth exercising on all of them, not just one.
+#   2. The prose-vs-manifest lint (scripts/check_spec_citations.sh) is a
+#      repo-wide text scan, unrelated to compilation -- it runs here, in its
+#      own fast, dependency-free job.
+#
+# Unlike .github/workflows/spec-sync.yml, this gate has no "no docs update"
+# label escape hatch: a wrong citation or a reintroduced banned term is never
+# a legitimate state to merge, so there is nothing to opt out of.
+
+on:
+  push:
+    branches: [main, master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  prose-lint:
+    name: Spec-citation & banned-terminology lint
+    runs-on: ubuntu-24.04
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Run prose-vs-manifest lint
+        run: bash scripts/check_spec_citations.sh

CHANGELOG.md

@@ -4,7 +4,7 @@ Notable changes to morph, in [Keep a Changelog](https://keepachangelog.com/en/1.
 format. morph is pre-1.0 and has no tagged releases yet: `master` is the only
 supported line, this file tracks notable changes going forward, and history
 predating it lives in `git log`. From 1.0 on, versioning follows the policy
-planned in `docs/planned/api_stability.md` (SemVer for the public, non-`detail`
+published in `docs/spec/VERSIONING.md` (SemVer for the public, non-`detail`
 API surface).
 
 ## [Unreleased]
@@ -22,6 +22,16 @@ API surface).
   `docs/planned/gui_cross_field_rules.md`; accessibility assertions in
   `docs/planned/gui_renderer_toolkit.md`'s conformance kit; a
   banned-terminology check in `docs/planned/drift_guard.md`'s prose lint.
+- API stability & versioning policy (`docs/spec/VERSIONING.md`, folded in
+  from `docs/planned/api_stability.md`): the semantic-versioning rules, the
+  stable (non-`detail`) surface definition, and the deprecation-window
+  discipline morph commits to starting at 1.0. Backed by two new mechanical
+  checks: the `include/morph/version.hpp` version constants (cross-checked
+  against `CMakeLists.txt`'s `project(VERSION ...)` by
+  `tests/test_version.cpp`), and the `deprecation-lint` CI job
+  (`scripts/check_deprecated_markers.sh`) enforcing that every
+  `[[deprecated("...")]]` marker names a replacement and a target removal
+  version.
 
 ### Fixed