Prepare inspected static Metal runtime inventory for macOS staging

docs/MACOS-RUNTIME.md

@@ -0,0 +1,49 @@
+# 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.