Spike: prove a license-safe, performance-parity Mojo-Metal integration #84

New Issue

hugo · 2026-08-31T12:09:33Z

hugo commented

2026-08-31 12:09:33 +00:00

Goal

Prove a production-shaped Mojo GPU integration for DS4Server on macOS and Apple Metal while preserving DS4 behavior and matching the existing DS4Server Metal backend.

This exploratory spike is the first and mandatory decision gate. It must finish before broad operator or model porting begins. CUDA is an explicitly deferred follow-up and is not a completion requirement for this issue.

Scope

Revalidate and pin the Mojo/MAX toolchain, Modular source commit, Rust toolchain, and Apple compiler requirements.
Add pyproject.toml and uv.lock for only the accelerator build dependencies. Keep the local virtual environment ignored and avoid serving, registry, REST, graph, and broad MAX extras.
Prove a frozen bootstrap followed by Cargo builds using uv run --frozen --offline --no-sync mojo build without network access or dependency resolution.
Extend build.rs to watch Mojo sources and lock files and produce a macOS shared library in Cargo OUT_DIR.
Expose a narrow exported C ABI using fixed numeric types, opaque handles, and pointer-plus-length buffers. Keep all unsafe Rust declarations in one safe wrapper.
Prove lifecycle, explicit errors, tensor transfer, one representative matrix operation, resident memory across repeated decode-like calls, GPU timing, and Rust wall-clock timing on real Apple hardware.
Audit the produced library and app closure with otool and nm, tracing every non-system library and every AsyncRT, MAX, KGEN, or Modular symbol to a concrete file and license.
Determine whether an open product path can retain macOS 13 or must explicitly move to macOS 15.
Prove macOS packaging without absolute development RPaths, the project virtual environment, or the source checkout.

The ABI, module boundaries, tensor layouts, and target-policy seam must leave room for a later CUDA target, but this issue must not wait for CUDA hardware, Linux packaging, NVIDIA APIs, or CUDA performance work.

MAX versus project-owned kernel decision

The spike must decide each required component using two independent gates: license safety and measured Metal performance.

Use confirmed permissively licensed Mojo/MAX sources only when the actual linked artifact is redistributable and the path meets DS4Server native Metal performance.
Use a MAX runtime only if every required file is proven redistributable, the complete path meets parity, and the user explicitly approves any non-permissive dependency.
Implement DS4Server-owned Mojo kernels and host integration whenever MAX fails either gate, including failures caused by layouts, adapters, materialization, transfers, synchronization, or fusion boundaries.

MAX candidates must be measured both in isolation and in the representative resident layer path. A permissive license does not justify a slower kernel, and a fast kernel does not justify an unclear license.

The current DS4Server Metal kernels are the predefined implementation and performance oracle for project-owned replacements. Preserve their proven layouts, fusion boundaries, cache behavior, scheduling intent, and materialization choices where those drive performance. The shared Mojo design may expose a narrow compile-time target-policy seam for future CUDA, but it must not introduce speculative NVIDIA implementation work into the Metal path.

Gates

DS4 remains the behavior oracle for token, context, cache, checkpoint, sampling, and model semantics.
Compare Mojo-Metal only with DS4Server native Metal on the same Apple hardware and identical artifacts.
No process per token, elementary-operation synchronization, silent fallback, or mixed native and Mojo benchmark path.
The resident operation has no structural ABI, runtime, transfer, synchronization, memory, or performance blocker.
Unknown or non-redistributable dependencies block integration.
A MAX path that misses operation, layer, memory, transfer, or end-to-end parity is rejected even if its license is acceptable.

Deliverables

Reproducible spike, raw Metal timing data, binary closure reports, and a component-level license inventory.
Written go, revise, or stop decision.
Binding per-component decision listing approved, prohibited, unresolved, and too-slow MAX dependencies and every project-owned kernel required instead.
Recommended ABI, build, packaging, host-dispatch, kernel, and Apple target-policy direction.
Explicit future-CUDA constraints limited to stable data contracts and target boundaries, without CUDA implementation.
Updates to every other issue in this milestone so scope and acceptance criteria reflect the measured direction. Add, replace, or close issues if needed.

Primary sources to revalidate

## Goal Prove a production-shaped Mojo GPU integration for DS4Server on macOS and Apple Metal while preserving DS4 behavior and matching the existing DS4Server Metal backend. This exploratory spike is the first and mandatory decision gate. It must finish before broad operator or model porting begins. CUDA is an explicitly deferred follow-up and is not a completion requirement for this issue. ## Scope - Revalidate and pin the Mojo/MAX toolchain, Modular source commit, Rust toolchain, and Apple compiler requirements. - Add pyproject.toml and uv.lock for only the accelerator build dependencies. Keep the local virtual environment ignored and avoid serving, registry, REST, graph, and broad MAX extras. - Prove a frozen bootstrap followed by Cargo builds using uv run --frozen --offline --no-sync mojo build without network access or dependency resolution. - Extend build.rs to watch Mojo sources and lock files and produce a macOS shared library in Cargo OUT_DIR. - Expose a narrow exported C ABI using fixed numeric types, opaque handles, and pointer-plus-length buffers. Keep all unsafe Rust declarations in one safe wrapper. - Prove lifecycle, explicit errors, tensor transfer, one representative matrix operation, resident memory across repeated decode-like calls, GPU timing, and Rust wall-clock timing on real Apple hardware. - Audit the produced library and app closure with otool and nm, tracing every non-system library and every AsyncRT, MAX, KGEN, or Modular symbol to a concrete file and license. - Determine whether an open product path can retain macOS 13 or must explicitly move to macOS 15. - Prove macOS packaging without absolute development RPaths, the project virtual environment, or the source checkout. The ABI, module boundaries, tensor layouts, and target-policy seam must leave room for a later CUDA target, but this issue must not wait for CUDA hardware, Linux packaging, NVIDIA APIs, or CUDA performance work. ## MAX versus project-owned kernel decision The spike must decide each required component using two independent gates: license safety and measured Metal performance. 1. Use confirmed permissively licensed Mojo/MAX sources only when the actual linked artifact is redistributable and the path meets DS4Server native Metal performance. 2. Use a MAX runtime only if every required file is proven redistributable, the complete path meets parity, and the user explicitly approves any non-permissive dependency. 3. Implement DS4Server-owned Mojo kernels and host integration whenever MAX fails either gate, including failures caused by layouts, adapters, materialization, transfers, synchronization, or fusion boundaries. MAX candidates must be measured both in isolation and in the representative resident layer path. A permissive license does not justify a slower kernel, and a fast kernel does not justify an unclear license. The current DS4Server Metal kernels are the predefined implementation and performance oracle for project-owned replacements. Preserve their proven layouts, fusion boundaries, cache behavior, scheduling intent, and materialization choices where those drive performance. The shared Mojo design may expose a narrow compile-time target-policy seam for future CUDA, but it must not introduce speculative NVIDIA implementation work into the Metal path. ## Gates - DS4 remains the behavior oracle for token, context, cache, checkpoint, sampling, and model semantics. - Compare Mojo-Metal only with DS4Server native Metal on the same Apple hardware and identical artifacts. - No process per token, elementary-operation synchronization, silent fallback, or mixed native and Mojo benchmark path. - The resident operation has no structural ABI, runtime, transfer, synchronization, memory, or performance blocker. - Unknown or non-redistributable dependencies block integration. - A MAX path that misses operation, layer, memory, transfer, or end-to-end parity is rejected even if its license is acceptable. ## Deliverables - Reproducible spike, raw Metal timing data, binary closure reports, and a component-level license inventory. - Written go, revise, or stop decision. - Binding per-component decision listing approved, prohibited, unresolved, and too-slow MAX dependencies and every project-owned kernel required instead. - Recommended ABI, build, packaging, host-dispatch, kernel, and Apple target-policy direction. - Explicit future-CUDA constraints limited to stable data contracts and target boundaries, without CUDA implementation. - Updates to every other issue in this milestone so scope and acceptance criteria reflect the measured direction. Add, replace, or close issues if needed. ## Primary sources to revalidate - https://docs.modular.com/mojo/requirements/ - https://docs.modular.com/mojo/tools/compilation/ - https://docs.modular.com/gpu/fundamentals/ - https://github.com/modular/modular/blob/main/max/mojo/max/gpu/host/device_context.mojo - https://www.modular.com/legal/mojo - https://github.com/modular/modular/blob/main/LICENSE - https://www.modular.com/legal/community/

hugo added the idea label 2026-08-31 12:09:33 +00:00