feat: maintain the Python compiler here with a native API, CLI and extension bundle

.config/mise/config.toml

@@ -1,6 +1,10 @@
 [tools]
 python = "3.14"
 uv = "latest"
+# The Rust half under rust/ (compiler, CPython bridge and WASM extension guest).
+rust = { version = "1.98.1", targets = "wasm32-unknown-unknown", components = "rustfmt,clippy" }
+# Validates the release WASM guest before bundling.
+wasm-tools = "1.259.0"
 
 [env]
 VIRTUAL_ENV = "{{config_root}}/.venv"

.config/mise/tasks/bench

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+#MISE description="Measure native, bridge, API and CLI compile and generate costs"
+# Arguments pass to scripts/bench.py, for example: mise run bench -- --modules 40
+set -euo pipefail
+
+# Measure the release wheel, not a development build.
+NATIVE_SDIST=0 mise run native:build
+uv pip install --quiet --no-deps --reinstall dist/native/morphir_python_native-*.whl
+uv run --no-sync python scripts/bench.py "$@"

.config/mise/tasks/coverage

@@ -3,3 +3,4 @@
 set -euo pipefail
 
 uv run pytest tests/ --cov=packages/morphir/src --cov=packages/morphir-tools/src --cov-report=term-missing --cov-report=html --cov-report=xml
+uv run python -m mypy.stubtest morphir_python_native._native

.config/mise/tasks/extension/bundle

@@ -0,0 +1,19 @@
+#!/usr/bin/env bash
+#MISE description="Build, package and qualify the morphir-python WASM extension bundle offline"
+set -euo pipefail
+
+bundle="${BUNDLE_DIR:-$PWD/.morphir/build/extensions/python}"
+receipts="${QUALIFICATION_DIR:-$PWD/.dev/qualification}"
+mkdir -p "$receipts" "$(dirname "$bundle")"
+rm -rf "$bundle"
+(cd rust && cargo build --locked --release -p morphir-python-binding --target wasm32-unknown-unknown)
+wasm="rust/target/wasm32-unknown-unknown/release/morphir_python_binding.wasm"
+wasm-tools validate "$wasm"
+commit=()
+if [[ -z "$(git status --porcelain --untracked-files=normal)" ]]; then
+  commit=(--git-commit "$(git rev-parse HEAD)")
+fi
+uv run --no-sync python scripts/extension_bundle.py package --wasm "$wasm" --output "$bundle" "${commit[@]}" \
+  >"$receipts/bundle.json"
+uv run --no-sync python scripts/extension_bundle.py host-check --bundle "$bundle" >"$receipts/bundle-host.json"
+cat "$receipts/bundle-host.json"

.config/mise/tasks/install

@@ -1,8 +1,20 @@
 #!/usr/bin/env bash
 #MISE description="Install all dependencies and workspace packages"
+#
+# By default uv builds morphir-python-native from source, which needs Rust.
+# MORPHIR_NATIVE_WHEEL=PATH installs that prebuilt wheel instead, so a CI job can
+# reuse one wheel. MORPHIR_SKIP_NATIVE=1 omits the native compiler for jobs that
+# only lint or type-check.
 set -euo pipefail
 
 echo "Syncing dependencies..."
-uv sync --frozen --all-packages --all-groups
+if [[ -n "${MORPHIR_NATIVE_WHEEL:-}" || "${MORPHIR_SKIP_NATIVE:-0}" == 1 ]]; then
+  uv sync --frozen --all-packages --all-groups --no-install-package morphir-python-native
+  if [[ -n "${MORPHIR_NATIVE_WHEEL:-}" ]]; then
+    uv pip install --no-deps "$MORPHIR_NATIVE_WHEEL"
+  fi
+else
+  uv sync --frozen --all-packages --all-groups
+fi
 
 echo "Install complete!"

.config/mise/tasks/native/build

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+#MISE description="Build the morphir-python-native wheel and source archive into dist/native"
+set -euo pipefail
+
+out="${NATIVE_DIST:-$PWD/dist/native}"
+mkdir -p "$out"
+cd packages/morphir-python-native
+# Portable wheels: refuse host-specific CPU settings.
+if [[ "${RUSTFLAGS:-}" == *target-cpu* || "${CARGO_ENCODED_RUSTFLAGS:-}" == *target-cpu* ]]; then
+  echo "RUSTFLAGS must not select a target CPU for portable wheels" >&2
+  exit 1
+fi
+uvx --from maturin==1.15.0 maturin build --release --locked --out "$out" "$@"
+if [[ "${NATIVE_SDIST:-1}" == 1 ]]; then
+  uvx --from maturin==1.15.0 maturin sdist --out "$out"
+fi

.config/mise/tasks/native/qualify

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+#MISE description="Qualify built native, core and tools distributions without Rust on PATH"
+set -euo pipefail
+
+native="${NATIVE_DIST:-$PWD/dist/native}"
+receipts="${QUALIFICATION_DIR:-$PWD/.dev/qualification}"
+mkdir -p "$receipts"
+shopt -s nullglob
+if [[ ${RELEASE_TAG:-} == python-v* ]]; then
+  # A CLI release ships with the published native compiler, so qualify those bytes,
+  # and refuse if the compiler sources changed after that native release.
+  pin="$(python3 -c 'import sys; sys.path.insert(0, "scripts"); import qualify_native as q; print(q.tools_pin())')"
+  git fetch --quiet --depth=1 origin "refs/tags/native-v$pin:refs/tags/native-v$pin"
+  if ! git diff --quiet "native-v$pin" HEAD -- rust packages/morphir-python-native; then
+    echo "the native compiler changed after native-v$pin; release a new native version first" >&2
+    exit 1
+  fi
+  native="$receipts/published-native"
+  rm -rf "$native"
+  uvx pip download --quiet --no-deps --only-binary=:all: --implementation cp \
+    --python-version 3.14 --abi abi3 --platform manylinux_2_28_x86_64 \
+    --dest "$native" "morphir-python-native==$pin"
+  export SKIP_SDIST_BUILD=1
+fi
+wheels=("$native"/morphir_python_native-*.whl)
+if [[ ${#wheels[@]} -ne 1 ]]; then
+  echo "expected exactly one native wheel in $native" >&2
+  exit 1
+fi
+python3 scripts/qualify_native.py wheel "${wheels[0]}" >"$receipts/native-wheel.json"
+sdists=("$native"/morphir_python_native-*.tar.gz)
+if [[ ${#sdists[@]} -eq 1 && "${SKIP_SDIST_BUILD:-0}" != 1 ]]; then
+  rm -rf "$receipts/from-sdist"
+  python3 scripts/qualify_native.py sdist "${sdists[0]}" --out "$receipts/from-sdist" \
+    >"$receipts/native-sdist.json"
+  # The wheel built from the archive alone must work when installed, too.
+  python3 scripts/qualify_native.py install \
+    packages/morphir/dist/morphir-*.whl "$receipts"/from-sdist/morphir_python_native-*.whl \
+    packages/morphir-tools/dist/morphir_python-*.whl >"$receipts/sdist-install.json"
+fi
+python3 scripts/qualify_native.py install \
+  packages/morphir/dist/morphir-*.whl "${wheels[0]}" packages/morphir-tools/dist/morphir_python-*.whl \
+  >"$receipts/clean-install.json"
+cat "$receipts"/*.json

.config/mise/tasks/release-check

@@ -5,12 +5,25 @@ set -euo pipefail
 release_dir="$(pwd)/.dev/release-check"
 mkdir -p "$release_dir"
 uv lock --check
-python scripts/check_distributions.py
+python -m scripts.check_distributions
 uvx --from twine==7.0.0 twine check --strict \
   packages/morphir/dist/* packages/morphir-tools/dist/*
 uv export --frozen --all-packages --no-default-groups --no-emit-workspace \
   --no-hashes --output-file "$release_dir/constraints.txt"
 
+# The CLI needs its exact native compiler. Use the wheel CI built, unless this is
+# a CLI release, which resolves the already published native release from PyPI.
+native_wheels=()
+if [[ ${RELEASE_TAG:-} != python-v* ]]; then
+  shopt -s nullglob
+  native_wheels=("${NATIVE_DIST:-$PWD/dist/native}"/morphir_python_native-*.whl)
+  shopt -u nullglob
+  if [[ ${#native_wheels[@]} -ne 1 ]]; then
+    echo "expected one native wheel in ${NATIVE_DIST:-dist/native}; run mise run native:build" >&2
+    exit 1
+  fi
+fi
+
 packages=(morphir morphir-python)
 if [[ ${RELEASE_TAG:-} == morphir-v* ]]; then
   packages=(morphir)
@@ -42,7 +55,7 @@ assert find_spec("typer") is None
 PY_CORE
   else
     uv pip install --python "$release_python" --constraint "$release_dir/constraints.txt" \
-      packages/morphir/dist/*.whl packages/morphir-tools/dist/*.whl
+      packages/morphir/dist/*.whl packages/morphir-tools/dist/*.whl "${native_wheels[@]}"
     "$release_python" -I - <<'PY_CLI'
 from importlib.metadata import distribution, version
 
@@ -60,6 +73,7 @@ PY_CLI
   fi
   uv pip check --python "$release_python"
   uv pip freeze --python "$release_python" --exclude morphir --exclude morphir-python \
+    --exclude morphir-python-native \
     > "$release_dir/$package-requirements.txt"
   if [[ -s "$release_dir/$package-requirements.txt" ]]; then
     uvx --from pip-audit==2.10.1 pip-audit --strict --no-deps --disable-pip \
@@ -86,7 +100,7 @@ uv pip install --python "$migration_python" --constraint "$release_dir/constrain
   'morphir-python==0.0.1'
 uv pip uninstall --python "$migration_python" morphir-python morphir
 uv pip install --python "$migration_python" --constraint "$release_dir/constraints.txt" \
-  packages/morphir/dist/*.whl packages/morphir-tools/dist/*.whl
+  packages/morphir/dist/*.whl packages/morphir-tools/dist/*.whl "${native_wheels[@]}"
 "$migration_python" -I - <<'PY_MIGRATION'
 from importlib.metadata import version
 

.config/mise/tasks/rust/check

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+#MISE description="Format, lint and test the Rust workspace; build the WASM guest without CPython"
+set -euo pipefail
+cd rust
+
+# mise points VIRTUAL_ENV at .venv, which a Rust-only job does not create.
+if [[ -n "${VIRTUAL_ENV:-}" && ! -x "$VIRTUAL_ENV/bin/python" ]]; then
+  unset VIRTUAL_ENV
+fi
+export PYO3_PYTHON="${PYO3_PYTHON:-$(command -v python3)}"
+
+cargo fmt --all --check
+cargo clippy --locked --all-targets -- -D warnings
+# The CPython module code builds only with the feature Maturin enables.
+cargo clippy --locked -p morphir-python-native --features python -- -D warnings
+cargo test --locked
+# The generated-code execution test runs Python; it is ignored by default.
+MORPHIR_TEST_PYTHON="${MORPHIR_TEST_PYTHON:-python3}" \
+  cargo test --locked -p morphir-python-binding --test functions -- --ignored
+cargo run --locked --quiet -p morphir-python-binding --example python_adt >/dev/null
+cargo run --locked --quiet -p morphir-python-binding --example python_modules -- 3 >/dev/null
+
+# The compiler crate, its native consumers and the WASM guest never link CPython.
+if cargo tree --locked -p morphir-python-binding -e normal,build | grep -q pyo3; then
+  echo "morphir-python-binding must not depend on PyO3" >&2
+  exit 1
+fi
+cargo build --locked --release -p morphir-python-binding --target wasm32-unknown-unknown
+wasm-tools validate target/wasm32-unknown-unknown/release/morphir_python_binding.wasm
+if wasm-tools print target/wasm32-unknown-unknown/release/morphir_python_binding.wasm \
+  | grep -E '^\s*\(import' | grep -v '"extism:host/env"'; then
+  echo "the WASM guest imports something other than the Extism host" >&2
+  exit 1
+fi

.config/mise/tasks/rust/consumer

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+#MISE description="Build and run an independent Cargo consumer of this commit's compiler crate"
+set -euo pipefail
+
+repository="$(git rev-parse --show-toplevel)"
+revision="$(git rev-parse HEAD)"
+consumer="$(mktemp -d)/consumer"
+trap 'rm -rf "$(dirname "$consumer")"' EXIT
+
+cargo new --quiet "$consumer"
+cat >>"$consumer/Cargo.toml" <<TOML
+morphir-python-binding = { git = "file://$repository", rev = "$revision" }
+morphir-extension-sdk = "=0.3.0"
+serde_json = "1"
+TOML
+# The README example is the consumer's main program.
+python3 - "$repository/rust/crates/morphir-python-binding/README.md" "$consumer/src/main.rs" <<'PY'
+import sys
+text = open(sys.argv[1]).read()
+start = text.index("## Use the crate from another Rust project")
+body = text.index("```rust\n", start) + len("```rust\n")
+open(sys.argv[2], "w").write(text[body:text.index("```", body)])
+PY
+output="$(cd "$consumer" && cargo run --quiet)"
+grep -q "def choose(" <<<"$output"
+if grep -q 'name = "pyo3' "$consumer/Cargo.lock"; then
+  echo "the consumer resolved PyO3" >&2
+  exit 1
+fi
+echo "independent consumer at $revision compiled and generated Python"

.config/mise/tasks/test

@@ -3,3 +3,5 @@
 set -euo pipefail
 
 uv run pytest tests/
+# The native stubs must match the installed extension module.
+uv run python -m mypy.stubtest morphir_python_native._native

.config/mise/tasks/typecheck

@@ -3,7 +3,7 @@
 set -euo pipefail
 
 echo "Running mypy..."
-uv run mypy packages/morphir/src packages/morphir-tools/src scripts
+uv run mypy packages/morphir/src packages/morphir-tools/src packages/morphir-python-native/python scripts
 
 echo "Running pyright..."
-uv run pyright packages/morphir/src packages/morphir-tools/src
+uv run pyright packages/morphir/src packages/morphir-tools/src packages/morphir-python-native/python