# Cross-architecture determinism corpus

This corpus compares Wax-visible values across C instant, C optimized, Wasm,
and Wax's machine-code backend. It includes NaN generation and
observation, scalar and vector stores, float-width conversion, host composite
marshalling, saturating float-to-integer conversion, masked shifts, traps, and
exact-bit subnormal boundary arithmetic.

`Reference/full/` and `Reference/machine/` contain retained Linux x86-64,
macOS ARM64, Windows x86-64, and Windows ARM64 artifacts. They are evidence,
not expectation authorities: the two
`expected-*.txt` files independently pin values to the language contract, while
`compare-probes.mjs` pins equality between machines. The Linux artifacts are
legacy outputs accepted by this revision's expectations; the macOS and Windows
artifacts record their exact producing compiler identity.

The legacy `native` leg is explicitly `--backend c` and uses the selected host
C compiler at `-O0`; `native-optimized` uses that compiler at `-O2`. Only
`machine-native` selects Wax's machine-code backend. Never cite the first two as
native x64 or native AArch64 evidence.

## Reproduce and compare

The public corpus manifest links every probe source, pinned expectation,
retained artifact, runner, comparator, and a self-contained ZIP. Running the
ZIP's `run.mjs` uses `waxc` from `PATH` and records its `--version` identity in
every output artifact. This intentionally lets any installed Wax version be
tested against the contract. The older retained Linux artifacts predate that
identity header, so their exact producing compiler revision is unknown; the
adjacent deployment manifest identifies the website build, not those artifacts.

On each machine, choose a unique platform label and output directory, then run
the full corpus:

```bash
cmake --build cmake-build-debug --target waxc WxRuntime wxdbg_runtime_wasm
node Tools/Determinism/run-probes.mjs \
  --waxc cmake-build-debug/waxc \
  --out artifacts/full-local \
  --label local-os-arch \
  --legs native,native-optimized,wasm \
  --runtime-wasm cmake-build-debug/Runtime/WasmHost/wxdbg-runtime.wasm \
  --node "$(Toolchain/find-multimem-node.sh)" \
  --require-host-probe
```

Copy the output directories from at least two machines together and compare
them with the retained reference. The comparator ignores identity headers but
requires every named value to be byte-for-byte equal:

```bash
node Tools/Determinism/compare-probes.mjs \
  Tools/Determinism/Reference/full \
  artifacts/full-machine-a \
  artifacts/full-machine-b \
  --min 14
```

Use `--corpus machine --legs native,native-optimized,machine-native,wasm` with
a separate output directory to reproduce the machine-backend digest corpus.
`node Tools/Determinism/run-probes.mjs --help` lists platform-specific overrides
for the C compiler, Node executable, and working directory.

## Run on Apple Silicon

From the repository root, with the normal debug build configured:

```bash
cmake --build cmake-build-debug --target waxc WxRuntime wxdbg_runtime_wasm -j12
rm -rf cmake-build-determinism/macos-arm64-full
node Tools/Determinism/run-probes.mjs \
  --waxc cmake-build-debug/waxc \
  --out cmake-build-determinism/macos-arm64-full \
  --label macos-arm64 \
  --legs native,native-optimized,wasm \
  --runtime-wasm cmake-build-debug/Runtime/WasmHost/wxdbg-runtime.wasm \
  --node "$(Toolchain/find-multimem-node.sh)" \
  --require-host-probe
node Tools/Determinism/compare-probes.mjs \
  Tools/Determinism/Reference/full \
  cmake-build-determinism/macos-arm64-full \
  --min 11

rm -rf cmake-build-determinism/macos-arm64-machine
node Tools/Determinism/run-probes.mjs \
  --waxc cmake-build-debug/waxc \
  --out cmake-build-determinism/macos-arm64-machine \
  --label macos-arm64 \
  --corpus machine \
  --legs native,native-optimized,machine-native,wasm \
  --runtime-wasm cmake-build-debug/Runtime/WasmHost/wxdbg-runtime.wasm \
  --node "$(Toolchain/find-multimem-node.sh)"
node Tools/Determinism/compare-probes.mjs \
  Tools/Determinism/Reference/machine \
  cmake-build-determinism/macos-arm64-machine \
  --min 13

WAX_TEST_FAST=0 WAX_CODEGEN_BEHAVIORAL_BACKEND=ir-native ./bt --filter='CodeGen.FloatingPointEnv_*'
```

The full run must write three 87-probe Mac artifacts and finish with:

```text
all 11 artifacts agree on 87 probes
```

The machine run must write four artifacts and finish with:

```text
all 13 artifacts agree on 1 probes
```

The final targeted suite poisons the host's floating-point control state before
entering native AArch64 Wax. It must prove gradual underflow survives and that
the host state is restored after normal, error, panic, callback, and replay
transitions.

## Run on Windows

From the repository root in a provisioned Windows environment, run either
native architecture with one command:

```powershell
pwsh Tools/Windows/determinism.ps1 -Architecture x64
pwsh Tools/Windows/determinism.ps1 -Architecture arm64
```

Each command builds `waxc` and `WxRuntime`, runs the full corpus through the C
instant and optimized tiers with host-composite marshalling required, runs the
machine scalar corpus through both C tiers, and compares every result with the
retained cross-platform evidence. Wax's machine-code backend is not yet
available on Windows, so these commands do not claim a `machine-native` leg.

Do not use `--no-check`: that would permit all architectures to agree on a
value that violates the checked-in language contract.