searchi/docs/MACOS-RUNTIME.md

macOS runtime preparation

Normal macOS auto builds select Metal with CPU fallback. The worker links llama/ggml statically and uses Apple system libraries/frameworks. Searchi now forces GGML_METAL_EMBED_LIBRARY=ON so upstream Metal kernel sources reside inside the worker rather than requiring loose kernel files from the build tree.

After compilation, the builder inspects the artifact using Apple lipo and otool; it does not execute the worker or initialize a GPU. Inspection requires:

• Supported arm64/x86_64 architectures, including both for a universal artifact.
• Only explicitly allowed Apple system libraries/frameworks, including Metal.
• A nonempty __DATA,__ggml_metallib section for each architecture.
• Current build-input provenance and a SHA-256 of the resulting worker.

The generated inventory declares the static-metal-embedded layout with an empty packaged-library list. Normal macOS staging now requires this inventory; the previous optional-inventory exception is removed for auto/metal. Staging verifies source identity, worker bytes, Mach-O magic and the static layout instead of requiring Windows DLLs or Linux shared libraries. Explicit internal CPU tooling keeps its optional-inventory behavior.

On a native Mac with the required Apple build tools:

python3 tools/embeddinggemma2/build_runtime.py --backend auto --jobs 2
python3 tools/embeddinggemma2/stage_runtime.py --backend auto

These commands are prepared, not executed on macOS. Native compilation, actual lipo/otool output, relocation outside the source tree, genuine Google CPU/Metal inference, device fallback, app integration and signing/notarization remain open. This change does not create a macOS release download.

Evidence, 2026-10-13

Four controlled Mach-O metadata-fixture tests passed, covering static system dependencies, foreign library rejection, missing Metal data and per-architecture section coverage. Staging tests exercise the empty-library macOS layout and the mandatory normal-profile policy. These fixtures are not executable Mac builds.

Across macOS metadata, staging, builder, provenance and Windows/Linux packaging suites: 75 tests passed with one platform-specific skip, in normal and optimized Python modes. Actual Windows and Ubuntu WSL normal runtime builds passed after the recipe change. Windows staging and Linux inventory verification passed. Worker hashes remain identical to their previously tested CPU deployments: Windows c01cb3ec13cfca722ee768e8350e1399a8b9a4d14a24a35adc3473a5cfc82a73; Linux b52d50a1e676bd4bf64124daff1c4ce83d86a8bde01e4eaf09838cbb24a4c28f. No GPU inference or native macOS execution was performed.