Fix 1830

.audit/oberstet_fix_1830.md

@@ -0,0 +1,8 @@
+- [ ] I did **not** use any AI-assistance tools to help create this pull request.
+- [x] I **did** use AI-assistance tools to *help* create this pull request.
+- [x] I have read, understood and followed the projects' [AI Policy](https://github.com/crossbario/autobahn-python/blob/main/AI_POLICY.md) when creating code, documentation etc. for this pull request.
+
+Submitted by: @oberstet
+Date: 2026-06-17
+Related issue(s): #1830
+Branch: oberstet:fix_1830

.github/workflows/main.yml

@@ -466,11 +466,11 @@ jobs:
           just create ${{ matrix.python-env }}
           just install-tools ${{ matrix.python-env }}
 
-      - name: Store original generated files checksum
-        run: |
-          echo "==> Computing checksums of committed FlatBuffers files..."
-          find src/autobahn/wamp/gen/ -name "*.py" -o -name "*.bfbs" | sort | xargs sha256sum > /tmp/original-checksums.txt
-          echo "Found $(wc -l < /tmp/original-checksums.txt) committed generated files"
+      - name: Clean generated FlatBuffers files (so orphans become detectable)
+        # Without this, `build-fbs` regenerates on top of the committed tree and
+        # any orphaned/stale file (no longer produced by the schema) survives in
+        # both the before and after states, hiding the drift (#1830).
+        run: just clean-fbs
 
       - name: Build FlatBuffers binary schema & Python wrappers
         run: just build-fbs
@@ -489,24 +489,37 @@ jobs:
 
       - name: Verify regenerated files match committed files
         run: |
-          echo "==> Computing checksums of regenerated files..."
-          find src/autobahn/wamp/gen/ -name "*.py" -o -name "*.bfbs" | sort | xargs sha256sum > /tmp/regenerated-checksums.txt
-
-          echo "==> Comparing checksums..."
-          if diff -u /tmp/original-checksums.txt /tmp/regenerated-checksums.txt; then
-            echo "✅ SUCCESS: All regenerated FlatBuffers files match committed versions exactly!"
-            echo "This confirms the build process is reproducible and up-to-date."
-          else
-            echo "❌ FAILURE: Regenerated files differ from committed versions!"
-            echo ""
-            echo "This indicates either:"
-            echo "1. The committed files were generated with a different flatc version"
-            echo "2. The committed files were manually modified"
-            echo "3. The build process has changed since files were last committed"
-            echo ""
-            echo "Please run 'just clean-fbs && just build-fbs' locally and commit the results."
-            exit 1
+          # Compare a clean regeneration (clean-fbs + build-fbs, above) against the
+          # committed generated tree using git's own classification, and fail with
+          # an actionable, categorized table (#1830):
+          #   M  -> content differs   (e.g. newer vendored flatc) -> regenerate & commit
+          #   D  -> committed but NOT produced by flatc -> orphan/attic leftover, delete (#1828)
+          #   ?? -> newly generated, not yet committed -> commit
+          status=$(git status --porcelain -- src/autobahn/wamp/gen/)
+          if [ -z "${status}" ]; then
+            echo "✅ SUCCESS: committed FlatBuffers generated code matches a clean regenerate."
+            exit 0
           fi
+          echo "❌ FAILURE: committed FlatBuffers generated code drifted from a clean regenerate."
+          echo ""
+          printf '%-36s %-21s %s\n' "CATEGORY" "ACTION" "FILE"
+          printf '%-36s %-21s %s\n' "------------------------------------" "---------------------" "----"
+          while IFS= read -r line; do
+            code="${line:0:2}"
+            file="${line:3}"
+            case "${code}" in
+              " M"|"M "|"MM") category="content differs"               ; action="regenerate & commit" ;;
+              " D"|"D ")      category="orphan / not generated [#1828]" ; action="delete" ;;
+              "??")           category="new, not committed"            ; action="commit" ;;
+              *)              category="changed (${code})"             ; action="review" ;;
+            esac
+            printf '%-36s %-21s %s\n' "${category}" "${action}" "${file}"
+          done <<< "${status}"
+          echo ""
+          count=$(printf '%s\n' "${status}" | grep -c .)
+          echo "FAIL: ${count} generated file(s) drifted."
+          echo "Run 'just clean-fbs && just build-fbs' locally and commit the result."
+          exit 1
 
       # Upload FlatBuffers artifacts (split into two uploads since verified action
       # doesn't support multi-line paths like actions/upload-artifact@v4)

docs/changelog.rst

@@ -25,6 +25,7 @@ Changelog
 * Commit the binary schemas (``reflection.bfbs``, ``wamp.bfbs``) to the source tree and ship them as-is; the package build no longer runs ``flatc``, which fixes cross-compilation from the PyPI sdist (e.g. Buildroot/Yocto/aarch64) (#1853)
 * Add ``just generate-reflection`` to regenerate the committed binary schemas with a version-matched ``flatc`` built from ``deps/flatbuffers`` (#1853)
 * Add ``just check-flatbuffers-sync`` and a unit test exercising ``check_zlmdb_flatbuffers_version_in_sync()`` (#1853)
+* Delete two orphaned generated files, ``Kdf.py`` and ``ChannelBinding.py``, left in ``src/autobahn/wamp/gen/wamp/proto/`` after the schema renamed those tables to ``KDF`` and ``TLSChannelBinding``. Their case-insensitive collisions with the current ``KDF.py`` / ``TLSChannelBinding.py`` broke ``git clone`` and directory copies on case-insensitive filesystems (APFS/macOS, some Docker setups). They are no longer produced by ``flatc``, and the verification from #1830 now keeps such orphans from recurring. Thanks to @dcki for the report (#1828)
 
 **Build & CI/CD**
 
@@ -38,6 +39,7 @@ Changelog
 * Build and publish the missing CPython 3.12 and 3.14 ``manylinux_*_aarch64`` (ARM64) wheels. The per-version ARM64 build matrix (added in commit 3d856f5 to deduplicate wheels) only covered cp311 and cp313, so no cp312 aarch64 wheel was ever published (and cp314 was never added) - e.g. ``pip download autobahn --platform manylinux_2_34_aarch64`` for CPython 3.12 found no matching distribution. The strict release fileset manifest shared the same gap and so could not catch it; it now requires the cp312/cp314 aarch64 wheels (fail-closed). Thanks to @norrisjeremy for the report (#1848)
 * Make the release fileset symmetric across all four platforms: every supported interpreter (cp311, cp312, cp313, cp314, pypy311) is now required on macOS/arm64, Linux/x86_64, Linux/aarch64, and Windows/amd64. The macOS job already built all interpreters via ``just build-all``, but the manifest only required cp313/cp314/pypy311, so the cp311/cp312 macOS wheels were built and then dropped as "extra" rather than published; they are now kept and required (#1848)
 * Remove orphaned/attic files left over from the pre-``justfile``/``uv`` CI/CD system: ``Makefile.orig``, ``Dockerfile.wheels``, ``mypy.ini``, ``test-docker-builds.sh``, ``versions.sh``, ``deploy.sh``, ``.prettierrc.json``, ``.coveragerc``, ``docs/DOCKER_BUILDS.md``, ``docker/README.md`` and the ``pyinstaller/`` PyInstaller hooks, plus the unused ``pyinstaller`` dev dependency. The ``.coveragerc`` ``omit = */test/*.py`` setting was preserved by migrating it to ``[tool.coverage.run]`` in ``pyproject.toml`` (so coverage still excludes in-package test modules), and the stale ``DOCKER_BUILDS.md`` entry was dropped from the Sphinx ``exclude_patterns``. ``mypy`` is unaffected: the typing recipe already passes ``--config-file pyproject-static-typing.toml`` explicitly. ``setuptools`` was added explicitly to the ``dev`` extra: it is required by ``cffi``'s ``ffi.compile()`` to build the NVX extensions in an editable install on Python >= 3.12 (stdlib ``distutils`` was removed in 3.12) and had been pulled in only transitively via the removed ``pyinstaller`` (#1831)
+* Fix the FlatBuffers generated-code verification so it actually detects drift. The ``build-fbs`` recipe now uses the vendored, version-matched ``flatc`` bundled in the venv (``${VENV_PATH}/bin/flatc``) instead of an arbitrary system ``flatc``, and the CI job runs ``just clean-fbs`` before ``just build-fbs`` so orphaned/stale generated files no longer survive in both the before and after states (previously they matched checksums and went undetected). On drift the job now fails with an actionable, categorized table - ``content differs`` (regenerate & commit, e.g. after a vendored-``flatc`` bump), ``orphan / not generated`` (delete), ``new, not committed`` (commit) - derived from ``git status`` of the regenerated tree (#1830)
 
 25.12.2
 -------

justfile

@@ -1941,7 +1941,15 @@ build-fbs venv="": (install-tools venv)
     VENV_PATH="{{ VENV_DIR }}/${VENV_NAME}"
 
     FBSFILES="./src/autobahn/wamp/flatbuffers/*.fbs"
-    FLATC="flatc"
+    # Use the vendored, version-matched flatc bundled in the venv (built from
+    # deps/flatbuffers during install), NOT a system flatc which may be a
+    # different version and silently produce different generated code (#1830).
+    FLATC="${VENV_PATH}/bin/flatc"
+    if [ ! -x "${FLATC}" ]; then
+        echo "ERROR: bundled flatc not found at ${FLATC}" >&2
+        echo "       Run 'just install-tools ${VENV_NAME}' first (it builds the vendored flatc)." >&2
+        exit 1
+    fi
     echo "==> Generating FlatBuffers binary schema and Python wrappers using $(${FLATC} --version)..."
 
     # Generate schema binary type library (*.bfbs files)