apple: implement binary opcodes 9-22 in the portable stub; fail closed on unknown ones

[gstoner]

The defect

apple_gpu_runtime_stub.cpp — compiled on every non-Darwin host so the C symbol exists — implemented opcodes 0–8 and ended its switch with:

default: out[i] = x; break;   // returns the LEFT operand

_APPLE_GPU_BINARY_OPCODES runs to 22. So 14 of 23 opcodes returned operand A instead of computing, on CI and on the Strix Halo box:

mod(9) floor_div(10) eq(11) ne(12) lt(13) le(14) gt(15) ge(16)
logical_and(17) logical_or(18) logical_xor(19)
bitwise_and(20) bitwise_or(21) bitwise_xor(22)

This was not a visible envelope miss. _load_apple_gpu_runtime compiles the stub off Darwin precisely "so the symbol still exists with a portable reference path" — and because the symbol then exists, _apple_gpu_dispatch_mpsgraph_binary takes the kernel branch instead of its numpy fallback. A wrong value came back as if computed, with no diagnostic. Decision #21: a lowering the backend cannot carry must diagnose, never silently fall through.

Observed directly on CI (run 32278268687): tessera.floor_div with {"scalar": 2.0} returned [1,2,4] where the truth is [0,1,2].

Pre-existing on main. Surfaced by #589, which was the first thing to exercise those opcodes on Linux.

The fix

Opcodes 9–22 implemented, matching mpsg_binary_node in apple_gpu_runtime.mm and the declared host reference runtime._apple_gpu_binary_numpy — which were already in agreement with each other. The subtleties that matter:

• mod and floor_div follow numpy (sign of the divisor), not C fmod/truncation
• comparisons and logical ops produce f32 0/1 masks
• bitwise ops go through int32, whose truncation toward zero matches both .astype(np.int32) and MPSGraph's castTensor:toType:MPSDataTypeInt32

Unknown opcodes now fail closed. Rejected before the output is touched, reported through the stub's last-error channel, and the buffer poisoned with NaN. That channel was three fixed no-op parity symbols — which is what left the stub unable to say it hadn't computed anything. It now carries real thread_local state mirroring the .mm's g_last_gpu_error_kind pattern, with a new kind 3 = "not implemented by the portable stub" (1 = timeout and 2 = command-buffer error are Metal-only and unreachable here). _apple_gpu_run_checked reads that channel and routes to the host fallback, so an unimplemented opcode now yields the correct answer via numpy rather than a plausible wrong one.

The guard is a separate predicate rather than a default: arm, so adding a case to the switch without adding it to the guard fails closed.

Testing something this host cannot execute

A Mac loads the real Metal symbol and never reaches the stub — which is exactly why the existing coverage couldn't catch this. tests/unit/test_apple_gpu_binary_opcodes.py layers four kinds of evidence:

Layer	Runs where	Catches
Dispatcher vs numpy reference, both lanes	everywhere	dispatch-level regressions
Structural gates on the stub source	any host, incl. this Mac	a newly declared opcode missing from the stub; a default: arm that returns an operand
Extracted + compiled + executed stub	any host with a C++ compiler	the stub's real semantics — the only layer that does
Kernel-reported-error fallback	everywhere	a failing kernel's buffer being believed

The compiled layer slices the opcode switch and error channel verbatim out of the real file rather than retyping them, so the tested text cannot drift from the shipped text. It compiles them with the host compiler and runs all 23 opcodes plus silu_mul and an unknown opcode against the numpy reference. It skips when no C++ compiler is present.

Inputs include a negative numerator and a zero — chosen to separate the implementations, not merely exercise them: they distinguish floor-mod from C fmod, floor-division from truncation, and the logical ops from the bitwise ones.

On the pre-fix stub the structural gates fail and the compiled lane cannot find its anchors.

Verification

Mac (M1 Max). Extracted stub compiles; all 23 opcodes match the numpy reference exactly, silu_mul matches, and opcode 23 reports kind 3 with NaN output.

• tests/unit/test_apple_gpu_binary_opcodes.py — 74 passed
• Full unit sweep: 14065 passed, 48 failed — failure set identical to the pre-existing baseline (all 48 the missing Apple runtime dylib in this worktree), zero new
• mypy clean over 467 files; ruff clean; generated-doc drift gate in sync

Limit of this evidence: the in-context Linux compile of the whole TU is proved by CI's build job, not by this host — -U__APPLE__ breaks libc++ on macOS, so the TU cannot be compiled here in its non-Darwin configuration. The extracted-region compile is the closest local proxy.

Cross-backend assessment (AGENTS.md)

Sync key APPLE-STUB-BINARY-OPCODES-2026-08-19, recorded in all four plans:

Backend	Outcome	Basis
apple	parity validated off-device	Metal was always correct — mpsg_binary_node implements the full table — so no exact-device row, .metallib, or dylib evidence changes or is re-claimed. What changes is that the portable path now agrees with Metal instead of silently disagreeing on 14 of 23 opcodes.
nvidia	not applicable	tessera_apple_gpu_mpsgraph_binary_f32 is referenced only by Apple files; no NVIDIA path reaches it.
rocm	not applicable	The gfx1151 binary lane is separate code (_execute_rocm_compiled_binary over a compiler-generated hsaco) and binds both operands positionally, raising rather than falling through. Checked for the same defect shape — it has no silent-default arm.
x86	not applicable today, one follow-up recorded	See below.

x86 follow-up (verified, not assumed)

The AVX-512 binary kernel carries the same shape: avx512_binary_f32.cpp ends scalar_binary with default: return a; and the vector loop with default: y = a; break;.

It is latent, not live: the kernel implements kinds 0–7 (kSub/kDiv/kMax/kMin/kAdd/kMul/kMod/kFloorDiv) and _X86_BINARY_OPS maps exactly onto that range, so no reachable call hits the default today. It becomes live the moment an opcode is added on one side only — which is precisely how the Apple defect arose. Fixing it needs AVX-512 evidence from the Zen 5 box, so it belongs in an x86 change, not here.

No device evidence is produced or claimed for nvidia, rocm, or x86.

🤖 Generated with Claude Code