# 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:

```sh
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.