Establish the Mojo 1.0 integration gate

docs/MOJO_SPIKE_84.md

@@ -0,0 +1,153 @@
+# Mojo 1.0 Metal integration spike (#84)
+
+## Decision
+
+**STOP** the product integration at the license/runtime gate. DS4Server can pin
+and invoke the Mojo 1.0 compiler through `uv`, but Mojo 1.0's open standard
+library does not provide the host-side `DeviceContext` needed to load and run a
+Metal kernel. That API is delivered by MAX and links to separately shipped
+AsyncRT and KGEN runtime libraries whose redistribution status is not explicit.
+
+This is a mandatory stop under issue #84, not a performance conclusion. The
+existing Objective-C Metal backend remains the production path. DS4Server now
+targets Apple silicon and macOS 15 or newer, matching Mojo 1.0's supported host
+floor. No MAX wheel, runtime library, virtual environment, or Modular source
+checkout is bundled.
+
+Run the committed proof from the repository root:
+
+```sh
+tools/mojo-spike/check.sh
+```
+
+The command syncs the locked `uv` environment, checks the exact compiler build,
+emits a C-ABI object and dynamic library, records their closure under
+`target/mojo-spike`, and verifies that the compiler-only environment cannot
+import the GPU host API. Once the lock has been synced, the same proof runs
+without network access as `UV_OFFLINE=1 tools/mojo-spike/check.sh`.
+
+## Pinned environment
+
+| Component | Pin / observation |
+| --- | --- |
+| Mojo compiler | `mojo-compiler==1.0.0` |
+| Compiler identity | `Mojo 1.0.0 (ed45d567)` |
+| Dependency manager | `uv.lock` revision 3; hashes recorded for every wheel |
+| Mojo source tag | `mojo/v1.0.0`, commit `b4497b7ce9ba96331c72c637ad41b44bab374f33` |
+| MAX probe | `max==26.5.0`, isolated outside the project environment |
+| Host | Apple M5 Max, arm64, macOS 26.6.2 (25G83) |
+| Xcode / Metal | Xcode 26.6 (17F113), Metal toolchain 17F109 |
+
+Only `mojo-compiler` is a project build dependency. The broader `mojo` package
+and MAX are intentionally absent because they add tools and runtimes that the
+committed proof does not need or may not redistribute.
+
+## Build and ABI findings
+
+`@export` produces a callable C symbol and `mojo build --emit object` produces a
+Mach-O object that can be linked by the platform linker. This is the viable ABI
+boundary if the GPU runtime gate is resolved: opaque handles, fixed-width C
+scalars, caller-owned buffers, integer status codes, and an explicit last-error
+function. Rust unwinding and Mojo exceptions must never cross it.
+
+`mojo build --emit shared-lib` is not self-contained. Even the trivial
+`ds4_mojo_probe` export has this non-system dependency:
+
+```text
+@rpath/libKGENCompilerRTShared.dylib
+```
+
+The object form avoids that dependency for the trivial CPU export, but it does
+not provide a way to construct a Metal device context or launch a GPU kernel.
+Importing `DeviceContext` from the open `std.gpu.host` package fails because it
+is not exported there. Importing the working API from `max.gpu.host` fails in
+the compiler-only environment because MAX is not installed.
+
+Compiling the Apache-licensed `max.gpu.host` Mojo sources directly did not make
+the program self-contained. The link still required these external symbols:
+
+```text
+_AsyncRT_DeviceContext_create
+_AsyncRT_DeviceContext_deviceName
+_AsyncRT_DeviceContext_release
+_AsyncRT_DeviceContext_strfree
+```
+
+An isolated `max==26.5.0` probe could enumerate the Apple M5 Max, proving that
+the API is technically viable when the proprietary runtime is present. Its
+executable closure included:
+
+```text
+@rpath/libKGENCompilerRTShared.dylib
+@rpath/libAsyncRTMojoBindings.dylib
+/usr/lib/libSystem.B.dylib
+```
+
+That probe is deliberately not part of the repository dependency graph.
+
+## License and redistribution inventory
+
+| Component | Source / package evidence | Product decision |
+| --- | --- | --- |
+| Mojo language, compiler sources, and standard library | Apache-2.0 with LLVM exceptions in the `modular/modular` repository | Approved for build use, subject to normal notices |
+| `mojo-compiler` and `mojo-compiler-mojo-libs` wheels | Pinned by hash; wheel metadata identifies the MAX Platform Software License | Build-only; do not redistribute the wheels |
+| MAX Mojo source modules | Repository source is Apache-2.0 with LLVM exceptions, while Modular separately states MAX usage and distribution remain under the Community License | Source license alone does not approve the runtime closure |
+| `max`, `max-core`, and `max-mojo-libs` wheels | Wheel metadata: `LicenseRef-MAX-Platform-Software-License` | Not a product dependency; do not bundle |
+| `libAsyncRTMojoBindings.dylib` and related AsyncRT libraries | Supplied only by the MAX wheel in this probe; no component-specific redistribution grant found | Blocked |
+| `libKGENCompilerRTShared.dylib` | Required by compiler-emitted shared libraries and the MAX GPU executable; no component-specific redistribution grant found | Blocked |
+| Apple Metal frameworks and system libraries | Supplied by macOS | Approved system dependency |
+| Existing DS4Server Objective-C Metal backend | Existing project code and Apple system frameworks | Remains the production implementation |
+
+The governing sources are the [Mojo repository license](https://github.com/modular/modular/blob/mojo/v1.0.0/LICENSE),
+the [Modular repository notice separating MAX licensing](https://github.com/modular/modular#license),
+and the [MAX and Mojo Community License](https://www.modular.com/legal/max-mojo-license).
+The Community License permits redistribution only for components Modular
+expressly identifies as redistributable and subject to its conditions. No
+authoritative component list was found that names the two required dylibs.
+Silence is not permission, so packaging is blocked.
+
+## Platform and packaging result
+
+Mojo 1.0 officially requires Apple silicon, macOS 15 or newer, Xcode or Command
+Line Tools 16 or newer, and the Metal toolchain. DS4Server now declares that
+same architecture and OS floor in its build environment, package metadata, and
+README. The native backend remains necessary because the license/runtime gate,
+not the platform floor, blocks the Mojo backend.
+
+The required package proof cannot pass today:
+
+- a clean machine would need non-system MAX runtime dylibs;
+- their exact redistributable status and required notices are unresolved;
+- an ad-hoc signed `.app` cannot be accepted while those dylibs are absent or
+  copied without permission;
+- CUDA viability cannot be inferred from this Metal probe and remains a
+  separate Linux/NVIDIA build, runtime, and license audit.
+
+## Performance result
+
+No parity number is reported. The approved compiler-only environment cannot
+launch a Metal operation, so there is no license-safe Mojo candidate to compare
+with native Metal. Timing a MAX-backed or CPU-only substitute would answer a
+different question and create a misleading baseline. The parity harness and raw
+GPU/wall-clock measurements begin only after an approved host/runtime path can
+build, link, and package.
+
+## Conditions to resume
+
+All of the following are required before issue #85 or later implementation may
+replace native code:
+
+1. Modular publishes an authoritative redistribution grant naming every
+   required runtime library, or Mojo exposes a host-side Metal launch path whose
+   complete closure is under an approved open-source/system license.
+2. The locked environment still builds through `uv` and works offline after
+   dependency installation.
+3. `otool -L` and `nm -u` show only system libraries and explicitly approved,
+   packaged runtime components.
+4. A clean-machine ad-hoc signed app launch proves install-name, rpath, code-sign,
+   and notice handling.
+5. The parity harness records identical workloads, correctness, GPU execution
+   time, wall time, and repeated samples against the native Metal oracle.
+
+Until then, later milestone issues are design and inventory work only; they may
+not introduce MAX as a Cargo, `uv`, build-script, or application dependency.