Prepare inspected static Metal runtime inventory for macOS staging

docs/BUILDING.md

@@ -8,7 +8,11 @@ Windows needs Visual Studio C++ build tools, a Windows SDK, and WebView2.
 Linux desktop builds need WebKitGTK 4.1 development libraries; macOS needs
 Xcode command-line tools. Follow the [Tauri prerequisites](https://v2.tauri.app/start/prerequisites/).
 Headless Linux CLI/worker builds do not need WebKitGTK or a display server.
-They still need a C/C++ compiler, linker, CMake, and Rust: SQLite, USearch,
+
+macOS runtime preparation embeds Metal kernel sources and inspects the static
+worker's Apple dependencies before staging. See [macOS runtime](MACOS-RUNTIME.md)
+for the prepared workflow and explicitly unexecuted native checks.
+Headless builds still need a C/C++ compiler, linker, CMake, and Rust: SQLite, USearch,
 NumKong, and the Google worker contain native code.
 
 ## Windows CPU development

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.

docs/ROADMAP.md

@@ -122,6 +122,10 @@ release. Keep their evidence and unchecked production gates intact.
 - [x] Normal Windows/Linux source-build provenance gate before staging and
   archive preparation; stale inventories preserve existing resources/packages.
   Actual normal builds verified. See [runtime provenance](RUNTIME-PROVENANCE.md).
+- [x] Prepare static macOS Metal inventory and mandatory normal-profile staging,
+  with embedded-source/dependency/architecture metadata regressions.
+- [ ] Execute native macOS runtime build, relocation and genuine CPU/Metal
+  inference; fixture metadata tests do not satisfy this gate.
 - [ ] Verify power-loss durability and release-tool interaction with resource
   directory swaps on each OS; fault-injected process interruption is narrower.
 - [x] Shared monotonic Basic/Debug search metrics, granular bounded engine traces,

docs/RUNTIME-PROVENANCE.md

@@ -7,8 +7,8 @@ release preparation now records and checks build-input identity before staging
 or packaging a normal Windows/Linux runtime.
 
 `runtime-libraries.json` includes `build_provenance`, schema 1, the pinned
-llama.cpp commit and SHA-256 of six bounded inputs: worker.cpp, native
-CMakeLists.txt, build_runtime.py and the three runtime patches. Only CRLF line
+llama.cpp commit and SHA-256 of seven bounded inputs: worker.cpp, native
+CMakeLists.txt, build_runtime.py, the macOS artifact inspector and the three runtime patches. Only CRLF line
 endings in these build inputs are canonicalized to LF, allowing the same
 source revision to compare across checkouts. Indexed user-file bytes and their
 extraction provenance are unaffected.
@@ -29,8 +29,8 @@ check and were not altered retroactively.
 
 ## Recorded evidence, 2026-10-13
 
-- 69 tests passed across provenance, builder, staging, Windows packaging and
-  Linux packaging suites; one platform-specific staging test remained skipped.
+- 75 tests passed across provenance, builder, macOS metadata, staging, Windows
+  packaging and Linux packaging suites; one platform-specific staging test remained skipped.
   The same suites passed under optimized Python. Regressions reject a valid old
   inventory without provenance, changed source and oversized inputs, while
   preserving existing archives. Build-source CRLF/LF equivalence is checked.
@@ -39,17 +39,18 @@ check and were not altered retroactively.
   `c01cb3ec13cfca722ee768e8350e1399a8b9a4d14a24a35adc3473a5cfc82a73`;
   all 25 Windows DLL hashes also match the previously tested release exactly.
   New staged inventory SHA-256:
-  `7fde510984b4635ce127d25ad91aab9a391300d7968ac71e4f201cc8edd052e8`.
+`b3859169d2c21ee5d40cdca038c3494f5620fe544adb2dd404d4535c89b5076b`.
 - An actual historical extracted Windows inventory was rejected by normal
   staging preflight for missing provenance. Its files were only read.
 - Actual normal Linux `auto` build passed on Ubuntu 24.04 WSL. The packager
-  verified 21 runtime inventory/files and all six source identities against the
+  verified 21 runtime inventory/files and all seven source identities against the
   current repository, including checkout line-ending differences.
   Worker SHA-256 remains
   `b52d50a1e676bd4bf64124daff1c4ce83d86a8bde01e4eaf09838cbb24a4c28f`.
   New inventory SHA-256:
-  `de6e06c68815b35d83c6acbde468d100413f47c74536f0d4219a9edcbeb01a86`.
+  `6463ae8a126f8de3ca4349bbb02fd36852f30222fe30e11fb4070385ce1989e8`.
 
 These normal builds retain GPU modules plus CPU fallback; no GPU inference was
-executed. macOS inventory integration, cross-compilation and actual GPU checks
+executed. macOS inventory preparation is now implemented and fixture-tested;
+[native macOS checks](MACOS-RUNTIME.md), cross-compilation and actual GPU checks
 remain open. Published Windows and Linux assets retain their original hashes.