Add cross-version compatibility harness (T0 + T1)

.github/workflows/ci.yml

@@ -0,0 +1,121 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main, dev]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Pins the toolchain to go.mod's declared minimum, so accidental use of a
+  # newer language feature is caught. Linux only, see the note on the unit job.
+  vet:
+    name: vet + race
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: gofmt
+        run: |
+          unformatted="$(gofmt -l ./cmd ./internal ./test)"
+          if [ -n "$unformatted" ]; then
+            echo "These files need gofmt:"
+            echo "$unformatted"
+            exit 1
+          fi
+
+      - name: go vet
+        run: go vet ./...
+
+      - name: go test -race
+        run: go test -race ./...
+
+  # Unit tests over the cross-version corpus. Pure Go, no network, no Node, ~1s.
+  # The OS matrix is nearly free here and catches path, endianness and
+  # line-ending surprises that only ever show up off Linux.
+  unit:
+    name: unit (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          # A current toolchain, NOT go.mod's minimum, because macos-latest is
+          # now macos-26 and its dyld refuses binaries without an LC_UUID load
+          # command. Go's internal linker only started emitting one in 1.26
+          # (golang/go#69987, golang/go#78012), so building this repo with Go
+          # 1.21 on macOS 26 fails before any phantom code runs - including on
+          # pre-existing tests like internal/util.
+          #
+          # go.mod's directive stays at the true LANGUAGE minimum and is still
+          # exercised by the `vet` job on Linux, where LC_UUID is irrelevant.
+          go-version: 'stable'
+          cache: true
+
+      - name: Corpus + rewrite tests
+        run: go test ./internal/...
+
+      - name: Fuzz the pong parser (short)
+        if: matrix.os == 'ubuntu-latest'
+        run: go test ./internal/proto/ -run=Fuzz -fuzz=FuzzReadUnconnectedPing -fuzztime=30s
+
+  # End-to-end tests against a real phantom subprocess.
+  #
+  # Sharded for ISOLATION as much as for speed: phantom binds UDP :19132
+  # unconditionally with SO_REUSEPORT, so two concurrent instances on one host
+  # silently load-balance each other's datagrams. One shard per runner gives
+  # each its own network stack; cases run serially within a shard.
+  e2e:
+    name: e2e (shard ${{ matrix.shard }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [0, 1, 2, 3]
+    env:
+      PHANTOM_SHARD: ${{ matrix.shard }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: test/compat/node/package-lock.json
+
+      - name: Install bedrock-protocol
+        working-directory: test/compat/node
+        run: npm ci
+
+      - name: End-to-end
+        run: go test -tags='e2e slow node' ./test/compat/... -timeout=20m -v
+
+  cross-compile:
+    name: cross-compile
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Build every release target
+        run: make build

.github/workflows/nightly.yml

@@ -0,0 +1,74 @@
+name: Nightly compatibility
+
+on:
+  schedule:
+    - cron: '0 6 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # Runs the live tier against EVERY supported version rather than the sampled
+  # subset CI uses, by clearing PHANTOM_SHARD.
+  full-sweep:
+    name: Full version sweep
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: test/compat/node/package-lock.json
+
+      - name: Install bedrock-protocol
+        working-directory: test/compat/node
+        run: npm ci
+
+      - name: Every version, unsharded
+        run: go test -tags='e2e slow node' ./test/compat/... -timeout=45m -v
+
+  extended-fuzz:
+    name: Extended fuzzing
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Fuzz the pong parser (10m)
+        run: go test ./internal/proto/ -run=Fuzz -fuzz=FuzzReadUnconnectedPing -fuzztime=10m
+
+      - name: Upload any crashers
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: fuzz-corpus
+          path: internal/proto/testdata/fuzz/
+
+  # The mechanism that keeps "N versions" honest over time: when Mojang ships a
+  # version and bedrock-protocol adds support, this goes red and tells you
+  # exactly which file to regenerate.
+  matrix-drift:
+    name: Version matrix drift
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+
+      - name: Install generator deps
+        working-directory: internal/corpus/gen
+        run: npm install --no-audit --no-fund
+
+      - name: Check for new Minecraft versions
+        working-directory: internal/corpus/gen
+        run: node drift.js

.gitignore

@@ -1,2 +1,6 @@
 bin/
 .DS_Store
+
+# Compatibility harness: Node deps are installed by `npm ci` from the committed
+# lockfiles, never committed themselves.
+node_modules/

Makefile

@@ -1,61 +1,103 @@
 SHELL=/bin/bash
-.PHONY: prep
+.PHONY: prep build build-target clean test test-e2e test-all fuzz corpus drift
 
-OUT=bin/phantom-windows.exe bin/phantom-windows-32bit.exe bin/phantom-macos bin/phantom-macos-arm8 bin/phantom-linux bin/phantom-linux-arm5 bin/phantom-linux-arm6 bin/phantom-linux-arm7 bin/phantom-linux-arm8
+# ARM note:
+#   arm5/arm6/arm7 = 32-bit (GOARCH=arm + GOARM)
+#   arm8/arm64     = 64-bit aarch64 (GOARCH=arm64). "arm8" does NOT mean
+#                    "any ARMv8 Raspberry Pi" — most Pi OS installs are still
+#                    32-bit and need arm7 (or arm6 on Pi Zero / Pi 1).
+# linux-x86 = GOARCH=386 (iSH on iOS is x86 userspace; ARM/amd64 builds fail there)
+OUT=bin/phantom-windows.exe bin/phantom-windows-32bit.exe bin/phantom-macos bin/phantom-macos-arm8 bin/phantom-linux bin/phantom-linux-x86 bin/phantom-linux-arm5 bin/phantom-linux-arm6 bin/phantom-linux-arm7 bin/phantom-linux-arm8 bin/phantom-linux-arm64
 CMDSRC=phantom.go
 
 build: prep ${OUT}
 
 bin/phantom-windows.exe:
 	pushd cmd && \
-	GOOS=windows GOARCH=amd64 go build -o ../bin/phantom-windows.exe ${CMDSRC} && \
+	CGO_ENABLED=0 GOOS=windows GOARCH=amd64 go build -o ../bin/phantom-windows.exe ${CMDSRC} && \
 	popd
 
 bin/phantom-windows-32bit.exe:
 	pushd cmd && \
-	GOOS=windows GOARCH=386 go build -o ../bin/phantom-windows-32bit.exe ${CMDSRC} && \
+	CGO_ENABLED=0 GOOS=windows GOARCH=386 go build -o ../bin/phantom-windows-32bit.exe ${CMDSRC} && \
 	popd
 
 bin/phantom-macos:
 	pushd cmd && \
-	GOOS=darwin GOARCH=amd64 go build -o ../bin/phantom-macos ${CMDSRC} && \
+	CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -o ../bin/phantom-macos ${CMDSRC} && \
 	popd
 
 bin/phantom-macos-arm8:
 	pushd cmd && \
-	GOOS=darwin GOARCH=arm64 go build -o ../bin/phantom-macos-arm8 ${CMDSRC} && \
+	CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -o ../bin/phantom-macos-arm8 ${CMDSRC} && \
 	popd
 
 bin/phantom-linux:
 	pushd cmd && \
-	GOOS=linux GOARCH=amd64 go build -o ../bin/phantom-linux ${CMDSRC} && \
+	CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build -o ../bin/phantom-linux ${CMDSRC} && \
+	popd
+
+# Termux on Android uses these linux/arm* targets (not GOOS=android).
+# 32-bit x86 for iSH (iOS) and other linux/386 environments.
+bin/phantom-linux-x86:
+	pushd cmd && \
+	CGO_ENABLED=0 GOOS=linux GOARCH=386 go build -o ../bin/phantom-linux-x86 ${CMDSRC} && \
 	popd
 
 bin/phantom-linux-arm5:
 	pushd cmd && \
-	GOOS=linux GOARCH=arm GOARM=5 go build -o ../bin/phantom-linux-arm5 ${CMDSRC} && \
+	CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=5 go build -o ../bin/phantom-linux-arm5 ${CMDSRC} && \
 	popd
 
 bin/phantom-linux-arm6:
 	pushd cmd && \
-	GOOS=linux GOARCH=arm GOARM=6 go build -o ../bin/phantom-linux-arm6 ${CMDSRC} && \
+	CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=6 go build -o ../bin/phantom-linux-arm6 ${CMDSRC} && \
 	popd
 
 bin/phantom-linux-arm7:
 	pushd cmd && \
-	GOOS=linux GOARCH=arm GOARM=7 go build -o ../bin/phantom-linux-arm7 ${CMDSRC} && \
+	CGO_ENABLED=0 GOOS=linux GOARCH=arm GOARM=7 go build -o ../bin/phantom-linux-arm7 ${CMDSRC} && \
 	popd
 
+# 64-bit ARM / aarch64 only (64-bit Raspberry Pi OS, etc.)
+# GOARM64=v8.0 keeps the baseline compatible with Pi 3/4 (no LSE requirement).
 bin/phantom-linux-arm8:
 	pushd cmd && \
-	GOOS=linux GOARCH=arm64 go build -o ../bin/phantom-linux-arm8 ${CMDSRC} && \
+	CGO_ENABLED=0 GOOS=linux GOARCH=arm64 GOARM64=v8.0 go build -o ../bin/phantom-linux-arm8 ${CMDSRC} && \
 	popd
 
+# Clearer alias for arm8 (same aarch64 binary).
+bin/phantom-linux-arm64: bin/phantom-linux-arm8
+	cp -f bin/phantom-linux-arm8 bin/phantom-linux-arm64
+
 prep:
 	mkdir -p bin
 
 clean:
 	rm -rf bin
 
+# Unit tests over the cross-version corpus. Fast, no deps.
 test:
 	go test ./...
+
+# End-to-end tests against a real phantom subprocess.
+# Needs `npm ci` in test/compat/node first for the `node` tag to do anything;
+# without it those cases skip rather than fail.
+test-e2e:
+	go test -tags='e2e slow node' ./test/compat/... -timeout=20m
+
+test-all: test test-e2e
+
+fuzz:
+	go test ./internal/proto/ -run=Fuzz -fuzz=FuzzReadUnconnectedPing -fuzztime=60s
+
+# Regenerates the captured pong corpus from real bedrock-protocol servers, one
+# per supported Minecraft version. Dev-time only: CI replays the committed
+# bytes and never runs this. Commit the diff.
+corpus:
+	cd internal/corpus/gen && npm install --no-audit --no-fund && node capture.js
+
+# Reports Minecraft versions that bedrock-protocol supports but this repo does
+# not yet test.
+drift:
+	cd internal/corpus/gen && node drift.js