test: contract + mock coverage for Apple Silicon GPU backends

[yasinBursali]

✅ Rebased on current main 2026-04-28

#999 has merged. The PR diff is now the 2 new test files (138 + 321 LoC = 459 lines added). Tests re-run on the rebased branch: 26/26 pass (21 in tests/test-gpu-apple.sh, 5 in tests/contracts/test-dream-doctor.sh).

#999 (fix/dream-cli-apple-silicon-coverage) introduced the 5 Apple GPU_BACKEND=apple code paths (_gpu_status, _gpu_topology, _gpu_validate, _gpu_reassign, cmd_status_json) plus a Darwin branch in scripts/dream-doctor.sh (RAM via sysctl hw.memsize, POSIX df -k); this PR adds regression shields for all of them.

What

Two new test files locking in Apple-Silicon behavior:

tests/contracts/test-dream-doctor.sh (138 lines, 5 cases, Darwin-guarded)

• dream-doctor.sh exits 0 under GPU_BACKEND=apple
• .preflight.inputs.ram_gb > 0 (sysctl hw.memsize path)
• .preflight.inputs.disk_gb > 0 (POSIX df -k on $HOME)
• .autofix_hints has 0 "incompatible with current GPU backend" entries under apple backend
• Empty-sysctl stub forces fallback to .env HOST_RAM_GB (writes/removes .env; pre-existing .env → SKIP)

Skips cleanly on Linux CI via [[ "$(uname -s)" == "Darwin" ]] || skip.

tests/test-gpu-apple.sh (321 lines, 21 cases)

Hermetic PATH-stub pattern (sysctl, system_profiler, curl, docker all PATH-prepended). nvidia-smi intentionally absent so command -v nvidia-smi returns false under the apple branch tests.

• gpu status (apple): rc=0 + header + Chip/Unified-memory/GPU-cores output + stub chip reflected
• gpu topology (apple): "Single integrated GPU" + rc=0
• gpu validate (apple): "Result: 0 check(s) passed, 0 failed" + rc=0
• gpu reassign (apple): rc=1 + "not applicable on Apple Silicon"
• status-json (apple): valid JSON with .gpu.backend=apple, .gpu.chip, .gpu.unified_memory_gb (number), .gpu.gpu_cores=38
• Negative cases: GPU_BACKEND=nvidia and GPU_BACKEND=amd do NOT take the apple branch; nvidia fallthrough warning emitted

Top-level Bash-4+ guard skips cleanly on stock macOS /bin/bash 3.2.

Testing

• test-gpu-apple.sh: 21/21 pass locally (macOS Darwin, homebrew bash 5.3) — re-verified on rebased branch
• test-dream-doctor.sh: 5/5 pass locally — re-verified on rebased branch
• bash -n + shellcheck clean (one justified # shellcheck disable=SC2016 on the single-quoted child-bash probe)
• Pre-commit hooks clean
• Fixture cleanup verified: no leftover .env files, no orphaned /tmp/test-* dirs

Platform Impact

• macOS (primary target): all 26 assertions exercise Apple GPU_BACKEND paths + Darwin doctor branch
• Linux: Darwin-specific cases skip via uname; mock-based cases run and confirm nvidia/amd backends fall through correctly
• Windows WSL2: would run as Linux (no Darwin-specific behavior to exercise; negative cases still valid)

[Lightheartdevs]

Audit follow-up: keep draft and rebase after the Apple/GPU merges.

#999 and #1025 are now on main, so this Apple Silicon GPU contract coverage should be restacked against them. Please keep only the still-needed contract/mock coverage and rerun the platform-sensitive tests, noting which parts are simulated versus macOS-only.

[yasinBursali]

Rebased on current main (#999 has merged). Diff is now the 2 new test files (138 + 321 = 459 lines). Re-ran on the rebased branch: 21/21 pass in tests/test-gpu-apple.sh, 5/5 in tests/contracts/test-dream-doctor.sh. shellcheck clean. Description updated.