fix(amm): align execution zone dependencies

apps/amm/MACOS.md

@@ -0,0 +1,173 @@
+# AMM UI on macOS
+
+The AMM flake exposes native packages for Apple Silicon and Intel macOS. Nix
+provides the Rust, C++, Qt, and Apple SDK build dependencies. The only required
+host toolchain is Apple's Metal compiler, which Apple distributes through
+Xcode rather than through a redistributable package.
+
+The standalone build needs no input overrides, temporary source pins, or
+`DYLD_LIBRARY_PATH`.
+
+## One-time prerequisites
+
+### Nix
+
+Install Nix in multi-user mode, make sure its daemon is available, and enable
+flakes:
+
+```sh
+mkdir -p ~/.config/nix
+printf '%s\n' 'experimental-features = nix-command flakes' >> ~/.config/nix/nix.conf
+nix --version
+nix store info
+```
+
+Nix normally has `sandbox = false` on macOS. This build must retain that
+setting because RISC Zero invokes Apple's host-installed Metal toolchain. The
+preflight script below reports an actionable error if the daemon is configured
+otherwise.
+
+### Xcode and the Metal Toolchain
+
+Apple Command Line Tools alone do not include `metal` and `metallib`. Install
+the newest full Xcode release supported by the installed macOS from the App
+Store or [Apple Developer Downloads](https://developer.apple.com/download/all/).
+This requires an Apple account and cannot be automated by the repository.
+
+After installation:
+
+```sh
+sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer
+sudo xcodebuild -license accept
+sudo xcodebuild -runFirstLaunch
+xcodebuild -downloadComponent MetalToolchain
+xcrun --sdk macosx --find metal
+xcrun --sdk macosx --find metallib
+```
+
+The last two commands must print executable paths. Do not use
+`RISC0_SKIP_BUILD_KERNELS=1`: the pinned dependency graph requires the real
+Metal kernels.
+
+### Disk space and preflight
+
+Leave at least 60 GiB free before downloading Xcode. Once Xcode is installed,
+keep at least 40 GiB free for the first Nix build. Later builds reuse the Nix
+store.
+
+Run the complete machine check from `apps/amm`:
+
+```sh
+bash scripts/check-macos-prerequisites.sh
+```
+
+## Build and run
+
+From `apps/amm`:
+
+```sh
+nix build .
+nix run .
+```
+
+The first cold build is large because it includes Qt, the wallet, the AMM
+client, and the RISC Zero Metal kernels. The first start opens without a
+wallet; select **Connect** to create or open `~/.lee/wallet/`.
+
+## Why the flake is structured this way
+
+Nix 2.25 rejects committed lock entries for unlocked relative flake inputs such
+as `path:../shared/wallet` and `path:../..`. Newer Nix versions may accept that
+layout, which is why it can appear to work on one developer's Mac and fail on
+another.
+
+The portable layout avoids both relative flake inputs:
+
+- the shared wallet is passed to CMake as an ordinary Nix source path;
+- the repository-root AMM client package is imported directly with the same
+  locked `nixpkgs` and Crane inputs;
+- `flake.lock` contains only immutable upstream sources.
+
+The app output uses the builder's full-library QML package layout. The current
+`qt-plugin` layout copies the UI plugin and replica factory but omits sibling
+external libraries such as `libamm_client`. The module metadata still selects
+the C++ backend, so this packaging choice does not change process isolation or
+runtime behavior.
+
+Do not replace these with a pull-request URL, self-reference, or local
+`path:` flake input. A normal `nix flake lock`, `nix build`, and `nix run`
+must work without overrides.
+
+## Known-good validation host
+
+This configuration has been exercised on:
+
+- Apple Silicon (`arm64`)
+- macOS 26.5.2
+- Xcode 26.6 (build 17F113)
+- Metal Toolchain 32023.883
+- Nix 2.25.3
+
+The flake also evaluates its complete package and app outputs for
+`x86_64-darwin`; an Intel Mac is still required for native runtime validation.
+
+## Recovery
+
+### Nix is unavailable
+
+Open a new terminal after installing Nix. For the standard multi-user
+installation, check the store and daemon before trying to bootstrap it again:
+
+```sh
+test -x /nix/var/nix/profiles/default/bin/nix
+nix store info
+sudo launchctl print system/org.nixos.nix-daemon
+```
+
+`launchctl bootstrap` can report an I/O error when a service is already loaded
+or in an inconsistent state; that message alone does not prove the daemon is
+stopped.
+
+### `xcrun` cannot find `metal`
+
+The selected developer directory points at Command Line Tools, or Xcode lacks
+the separately downloaded Metal Toolchain component. Repeat the Xcode setup
+and verification commands above.
+
+Apple does not distribute the Metal compiler as a standalone redistributable
+SDK, so Nix cannot install this host component.
+
+### The build reports that the macOS sandbox blocks Metal
+
+Confirm the active setting:
+
+```sh
+nix config show sandbox
+```
+
+For this native macOS build it must be `false`. If a machine-wide policy set it
+to `true`, update that Nix installation's daemon configuration and restart the
+daemon before retrying.
+
+### The first build runs out of space
+
+Remove only disposable build outputs, then collect dead Nix store paths:
+
+```sh
+rm -rf /private/tmp/amm-build
+nix-store --gc
+```
+
+Do not remove `/nix/store` directly.
+
+### A lock error mentions an unlocked input
+
+Restore the committed app lock and verify it without rewriting it:
+
+```sh
+git restore flake.lock
+nix flake metadata --no-update-lock-file .
+```
+
+If the error still names `path:../shared/wallet` or `path:../..`, the checkout
+does not contain the portable flake fix described above.

apps/amm/README.md

@@ -50,6 +50,9 @@ nix profile install 'github:logos-co/logos-package-manager#cli'
 
 This makes `lgpm` available as a global command.
 
+For macOS prerequisites, the Metal toolchain requirement, and common Nix
+recovery steps, see [macOS setup](MACOS.md).
+
 ## Running the UI standalone
 
 The app is built from the **repository-root** flake (which also provides the
@@ -82,9 +85,11 @@ nix build '.#lgx' --out-link result-lgx
 # Portable variant (self-contained, works without nix)
 nix build '.#lgx-portable' --out-link result-lgx-portable
 
-# The core wallet module it depends on. Use the same rev this app pins as the
-# `logos_execution_zone` input in flake.nix so the ImageID/ABI match.
-nix build 'github:logos-blockchain/logos-execution-zone-module?rev=d2e9400ac06c3cdbfc2405b4f153fff9841a453c#lgx' \
+# The core wallet module it depends on. These are the same immutable upstream
+# revisions used by this app's flake, including the merged macOS Metal fix.
+nix build 'github:logos-blockchain/logos-execution-zone-module?rev=d70225ced646934d2294fd9e8f8b03615c104b80#lgx' \
+  --override-input logos-execution-zone \
+  'github:logos-blockchain/logos-execution-zone?rev=a7e06a660940a00093b1760560d37ff84aff5a05' \
   --out-link result-core
 ```
 

apps/amm/scripts/check-macos-prerequisites.sh

@@ -0,0 +1,117 @@
+#!/usr/bin/env bash
+
+# Verify the host requirements for a supported native macOS AMM build.
+
+set -euo pipefail
+
+failures=0
+
+pass() {
+  printf 'ok: %s\n' "$1"
+}
+
+fail() {
+  printf 'missing: %s\n' "$1" >&2
+  failures=$((failures + 1))
+}
+
+if [[ "$(uname -s)" != "Darwin" ]]; then
+  printf 'missing: this script must run on macOS\n' >&2
+  exit 1
+fi
+
+architecture="$(uname -m)"
+case "$architecture" in
+  arm64|x86_64)
+    pass "supported architecture $architecture"
+    ;;
+  *)
+    fail "unsupported architecture $architecture"
+    ;;
+esac
+
+developer_dir="$(xcode-select -p 2>/dev/null || true)"
+if [[ "$developer_dir" == *.app/Contents/Developer ]]; then
+  pass "full Xcode selected at $developer_dir"
+  required_gib=40
+else
+  fail "full Xcode is not selected (current developer directory: ${developer_dir:-none})"
+  required_gib=60
+fi
+
+if xcode_version="$(xcodebuild -version 2>/dev/null)"; then
+  pass "$(printf '%s' "$xcode_version" | tr '\n' ' ')"
+else
+  fail "xcodebuild is unavailable; install Xcode.app and select it with xcode-select"
+fi
+
+if xcodebuild -checkFirstLaunchStatus >/dev/null 2>&1; then
+  pass "Xcode first-launch setup and licence are complete"
+else
+  fail "Xcode setup is incomplete; run sudo xcodebuild -license accept and -runFirstLaunch"
+fi
+
+for tool in metal metallib; do
+  if tool_path="$(xcrun --sdk macosx --find "$tool" 2>/dev/null)" &&
+     [[ -x "$tool_path" ]]; then
+    pass "$tool at $tool_path"
+  else
+    fail "$tool is unavailable; run xcodebuild -downloadComponent MetalToolchain"
+  fi
+done
+
+nix_bin="$(command -v nix 2>/dev/null || true)"
+if [[ -z "$nix_bin" && -x /nix/var/nix/profiles/default/bin/nix ]]; then
+  nix_bin=/nix/var/nix/profiles/default/bin/nix
+fi
+
+if [[ -n "$nix_bin" ]]; then
+  pass "Nix at $nix_bin ($("$nix_bin" --version))"
+
+  configured_features="$(
+    "$nix_bin" config show experimental-features 2>/dev/null ||
+      "$nix_bin" show-config 2>/dev/null |
+        awk -F ' = ' '$1 == "experimental-features" { print $2 }'
+  )"
+  if [[ " $configured_features " == *" nix-command "* &&
+        " $configured_features " == *" flakes "* ]]; then
+    pass "Nix flakes and nix-command are enabled"
+  else
+    fail "enable experimental-features = nix-command flakes in nix.conf"
+  fi
+
+  if "$nix_bin" --extra-experimental-features 'nix-command flakes' \
+      store info >/dev/null 2>&1; then
+    pass "Nix daemon and store are available"
+  else
+    fail "Nix cannot contact its daemon or store"
+  fi
+
+  sandbox_setting="$("$nix_bin" config show sandbox 2>/dev/null || true)"
+  if [[ "$sandbox_setting" == "false" ]]; then
+    pass "Nix macOS sandbox is disabled for the host Metal toolchain"
+  else
+    fail "Nix sandbox must be false for the host Metal toolchain (current: ${sandbox_setting:-unknown})"
+  fi
+else
+  fail "Nix is unavailable; install multi-user Nix and start its daemon"
+fi
+
+if [[ -d /nix ]]; then
+  available_kib="$(df -Pk /nix | awk 'NR == 2 { print $4 }')"
+  required_kib=$((required_gib * 1024 * 1024))
+  if [[ "${available_kib:-0}" -ge "$required_kib" ]]; then
+    pass "at least ${required_gib} GiB free on the Nix volume"
+  else
+    fail "less than ${required_gib} GiB free on the Nix volume"
+  fi
+else
+  fail "/nix is not mounted"
+fi
+
+if (( failures > 0 )); then
+  printf '\nSee MACOS.md for installation and recovery instructions.\n' >&2
+  exit 1
+fi
+
+printf '\nAll macOS AMM prerequisites are available.\n'