universal-wasm-loader 1.0.0__tar.gz

universal_wasm_loader-1.0.0/.gitignore

@@ -0,0 +1,219 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

universal_wasm_loader-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jon Marcum
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

universal_wasm_loader-1.0.0/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: universal-wasm-loader
+Version: 1.0.0
+Summary: Universal WASM loader for Python
+Project-URL: Homepage, https://github.com/jrmarcum/universalWasmLoader-py
+Project-URL: Repository, https://github.com/jrmarcum/universalWasmLoader-py
+Author-email: Jon Marcum <jrmarcum.se@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: canonical-abi,loader,wasm,webassembly,wit
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Requires-Dist: wasmtime>=26.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.9.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# universalWasmLoader-py
+
+Universal WASM loader for Python — the Python port of
+[universalWasmLoader-js](https://github.com/jrmarcum/universalWasmLoader-js). Loads and
+instantiates WebAssembly modules and, when a companion `.wit` file is present, applies the
+Canonical ABI so you call WIT exports with idiomatic Python values (`int`/`float`, `bool`,
+`str`) instead of raw i32/pointer pairs.
+
+- **PyPI package:** `universal-wasm-loader`
+- **WASM runtime:** [`wasmtime`](https://pypi.org/project/wasmtime/) ≥ 26.0.0
+- **License:** MIT
+
+## Install
+
+```sh
+pip install universal-wasm-loader
+```
+
+## Usage
+
+```python
+from universal_wasm_loader import wasm_import, create_singleton, InstancePool
+
+exports = await wasm_import("./math.wasm")
+result = exports["calculate"](1, 2)          # 3
+```
+
+See [`CLAUDE.md`](CLAUDE.md) / [`cmem/overview.md`](cmem/overview.md) for the full API surface.
+
+## Develop
+
+```sh
+pixi run test        # pytest tests/ -v
+pixi run lint        # ruff check src/ tests/
+pixi run typecheck   # mypy src/
+```
+
+## Release / publish to PyPI
+
+The version lives in **`pyproject.toml`** `[project] version` — the single source of truth
+(`pixi.toml` mirrors it). Three scripts key off it, each shipped in **two equivalent forms**: a
+Bash `.sh` and a cross-platform Nushell `.nu` (Nushell ≥ 0.113; runs on Windows/macOS/Linux
+without Git Bash). Use whichever your machine has — they have identical flags and behavior.
+
+**Tagging/releasing and publishing are deliberately decoupled:** `release` tags + pushes +
+creates the GitHub Release; `publish` is a separate, auth-gated, confirmation-guarded step that
+actually uploads to PyPI (irreversible). All three support `--dry-run`.
+
+```sh
+# 1) Bump the version (commits the isolated change)
+bash scripts/bump-version.sh patch     #  1.0.0 -> 1.0.1   (or minor | major | X.Y.Z)
+nu   scripts/bump-version.nu patch      #  …equivalent
+
+# 2) Tag v<version>, push branch + tag, create the GitHub Release (NO PyPI upload)
+bash scripts/release.sh                 #  --no-release / --no-build / --remote / --dry-run
+nu   scripts/release.nu
+
+# 3) Publish to PyPI — separate, deliberate, irreversible
+bash scripts/publish.sh                 #  prompts; --yes / --dry-run / --allow-dirty / --skip-tag-check
+nu   scripts/publish.nu
+```
+
+`publish` reads the version from `pyproject.toml`, requires the matching `v<version>` tag to
+exist locally **and** on the remote, refuses to run without a PyPI token, and is idempotent (if
+that version is already on PyPI it reports success and uploads nothing).
+
+### Required setup for `publish` (one-time)
+
+1. **PyPI project owned/registered.** The name `universal-wasm-loader` must exist on PyPI under
+   an account you control (do the first upload, or pre-register the name).
+2. **A PyPI API token in the environment** (project-scoped is best):
+
+   ```sh
+   export TWINE_USERNAME=__token__
+   export TWINE_PASSWORD=pypi-XXXXXXXX     # your token; or a [pypi] entry in ~/.pypirc
+   ```
+
+### Publishing from CI instead (optional, token-free)
+
+`.github/workflows/publish.yml` can also build + upload, but it is **manual-only**
+(`workflow_dispatch`) — it does **not** fire on a tag push, so it never double-publishes
+alongside `release`. Run it from the Actions tab against the release tag.
+
+It authenticates with **PyPI Trusted Publishing over short-lived OIDC — no long-lived PyPI token
+is stored in repo secrets**, so there's nothing to leak. One-time setup: register a Trusted
+Publisher on PyPI (a *pending publisher* before the project's first upload) with Owner
+`jrmarcum`, Repository `universalWasmLoader-py`, Workflow `publish.yml`.
+
+> **`run:`-only workflow.** This org's GitHub Actions policy permits only `jrmarcum`-owned
+> actions; any third-party `uses:` step (including `actions/checkout` and
+> `pypa/gh-action-pypi-publish`) causes a `startup_failure`. The workflow therefore uses plain
+> `run:` steps throughout — including the OIDC exchange (`ACTIONS_ID_TOKEN_REQUEST_*` →
+> `https://pypi.org/_/oidc/mint-token` → `twine upload` with the ephemeral token), done by hand
+> rather than via the pypa publish action.

universal_wasm_loader-1.0.0/README.md

@@ -0,0 +1,94 @@
+# universalWasmLoader-py
+
+Universal WASM loader for Python — the Python port of
+[universalWasmLoader-js](https://github.com/jrmarcum/universalWasmLoader-js). Loads and
+instantiates WebAssembly modules and, when a companion `.wit` file is present, applies the
+Canonical ABI so you call WIT exports with idiomatic Python values (`int`/`float`, `bool`,
+`str`) instead of raw i32/pointer pairs.
+
+- **PyPI package:** `universal-wasm-loader`
+- **WASM runtime:** [`wasmtime`](https://pypi.org/project/wasmtime/) ≥ 26.0.0
+- **License:** MIT
+
+## Install
+
+```sh
+pip install universal-wasm-loader
+```
+
+## Usage
+
+```python
+from universal_wasm_loader import wasm_import, create_singleton, InstancePool
+
+exports = await wasm_import("./math.wasm")
+result = exports["calculate"](1, 2)          # 3
+```
+
+See [`CLAUDE.md`](CLAUDE.md) / [`cmem/overview.md`](cmem/overview.md) for the full API surface.
+
+## Develop
+
+```sh
+pixi run test        # pytest tests/ -v
+pixi run lint        # ruff check src/ tests/
+pixi run typecheck   # mypy src/
+```
+
+## Release / publish to PyPI
+
+The version lives in **`pyproject.toml`** `[project] version` — the single source of truth
+(`pixi.toml` mirrors it). Three scripts key off it, each shipped in **two equivalent forms**: a
+Bash `.sh` and a cross-platform Nushell `.nu` (Nushell ≥ 0.113; runs on Windows/macOS/Linux
+without Git Bash). Use whichever your machine has — they have identical flags and behavior.
+
+**Tagging/releasing and publishing are deliberately decoupled:** `release` tags + pushes +
+creates the GitHub Release; `publish` is a separate, auth-gated, confirmation-guarded step that
+actually uploads to PyPI (irreversible). All three support `--dry-run`.
+
+```sh
+# 1) Bump the version (commits the isolated change)
+bash scripts/bump-version.sh patch     #  1.0.0 -> 1.0.1   (or minor | major | X.Y.Z)
+nu   scripts/bump-version.nu patch      #  …equivalent
+
+# 2) Tag v<version>, push branch + tag, create the GitHub Release (NO PyPI upload)
+bash scripts/release.sh                 #  --no-release / --no-build / --remote / --dry-run
+nu   scripts/release.nu
+
+# 3) Publish to PyPI — separate, deliberate, irreversible
+bash scripts/publish.sh                 #  prompts; --yes / --dry-run / --allow-dirty / --skip-tag-check
+nu   scripts/publish.nu
+```
+
+`publish` reads the version from `pyproject.toml`, requires the matching `v<version>` tag to
+exist locally **and** on the remote, refuses to run without a PyPI token, and is idempotent (if
+that version is already on PyPI it reports success and uploads nothing).
+
+### Required setup for `publish` (one-time)
+
+1. **PyPI project owned/registered.** The name `universal-wasm-loader` must exist on PyPI under
+   an account you control (do the first upload, or pre-register the name).
+2. **A PyPI API token in the environment** (project-scoped is best):
+
+   ```sh
+   export TWINE_USERNAME=__token__
+   export TWINE_PASSWORD=pypi-XXXXXXXX     # your token; or a [pypi] entry in ~/.pypirc
+   ```
+
+### Publishing from CI instead (optional, token-free)
+
+`.github/workflows/publish.yml` can also build + upload, but it is **manual-only**
+(`workflow_dispatch`) — it does **not** fire on a tag push, so it never double-publishes
+alongside `release`. Run it from the Actions tab against the release tag.
+
+It authenticates with **PyPI Trusted Publishing over short-lived OIDC — no long-lived PyPI token
+is stored in repo secrets**, so there's nothing to leak. One-time setup: register a Trusted
+Publisher on PyPI (a *pending publisher* before the project's first upload) with Owner
+`jrmarcum`, Repository `universalWasmLoader-py`, Workflow `publish.yml`.
+
+> **`run:`-only workflow.** This org's GitHub Actions policy permits only `jrmarcum`-owned
+> actions; any third-party `uses:` step (including `actions/checkout` and
+> `pypa/gh-action-pypi-publish`) causes a `startup_failure`. The workflow therefore uses plain
+> `run:` steps throughout — including the OIDC exchange (`ACTIONS_ID_TOKEN_REQUEST_*` →
+> `https://pypi.org/_/oidc/mint-token` → `twine upload` with the ephemeral token), done by hand
+> rather than via the pypa publish action.

universal_wasm_loader-1.0.0/pyproject.toml

@@ -0,0 +1,66 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "universal-wasm-loader"
+version = "1.0.0"
+description = "Universal WASM loader for Python"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [{ name = "Jon Marcum", email = "jrmarcum.se@gmail.com" }]
+requires-python = ">=3.11"
+keywords = ["wasm", "webassembly", "loader", "wit", "canonical-abi"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = ["wasmtime>=26.0.0"]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.9.0",
+    "mypy>=1.10.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/jrmarcum/universalWasmLoader-py"
+Repository = "https://github.com/jrmarcum/universalWasmLoader-py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/universal_wasm_loader"]
+
+# Ship the MIT LICENSE (and the user-facing docs) inside the sdist so the license
+# travels with the published package. Hatchling already auto-includes LICENSE* in
+# the wheel's .dist-info; this makes the sdist contents explicit.
+[tool.hatch.build.targets.sdist]
+include = [
+    "src/universal_wasm_loader",
+    "tests",
+    "LICENSE",
+    "README.md",
+    "pyproject.toml",
+]
+
+[tool.ruff]
+src = ["src"]
+line-length = 99
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP"]
+
+[tool.mypy]
+strict = true
+mypy_path = "src"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

universal_wasm_loader-1.0.0/src/universal_wasm_loader/__init__.py

@@ -0,0 +1,3 @@
+from ._loader import InstancePool, create_singleton, wasm_import
+
+__all__ = ["wasm_import", "create_singleton", "InstancePool"]

universal_wasm_loader-1.0.0/src/universal_wasm_loader/_abi.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+import wasmtime
+
+
+def _decode_string(memory: wasmtime.Memory, store: wasmtime.Store, ptr: int, length: int) -> str:
+    return bytes(memory.read(store, ptr, ptr + length)).decode("utf-8")
+
+
+def _read_i32_le(memory: wasmtime.Memory, store: wasmtime.Store, addr: int) -> int:
+    return int.from_bytes(bytes(memory.read(store, addr, addr + 4)), "little", signed=True)
+
+
+def _encode_string(
+    memory: wasmtime.Memory,
+    store: wasmtime.Store,
+    realloc: wasmtime.Func,
+    text: str,
+) -> tuple[int, int]:
+    data = text.encode("utf-8")
+    ptr: int = realloc(store, 0, 0, 1, len(data))  # type: ignore[assignment]
+    memory.write(store, data, ptr)
+    return ptr, len(data)
+
+
+def build_component_import_env(
+    imports: list[dict],  # type: ignore[type-arg]
+    callbacks: dict[str, Callable] | None,  # type: ignore[type-arg]
+    memory_ref: list[wasmtime.Memory | None],
+    store: wasmtime.Store,
+) -> dict[str, Callable]:  # type: ignore[type-arg]
+    callbacks = callbacks or {}
+
+    def make_wrapper(fd: dict, cb: Callable | None) -> Callable:  # type: ignore[type-arg]
+        has_str = any(p["type"] == "string" for p in fd["params"])
+
+        def wrapper(*raw_args: Any) -> Any:
+            memory = memory_ref[0]
+            converted: list[Any] = []
+            idx = 0
+            for p in fd["params"]:
+                val = raw_args[idx]
+                idx += 1
+                if p["type"] == "bool":
+                    converted.append(bool(val))
+                elif p["type"] == "string" and has_str and memory is not None:
+                    length = int(raw_args[idx])
+                    idx += 1
+                    converted.append(_decode_string(memory, store, int(val), length))
+                else:
+                    converted.append(val)
+            if cb is None:
+                return None if not fd["return_type"] else 0
+            result = cb(*converted)
+            if result is None:
+                return 0
+            return int(result) if isinstance(result, bool) else result
+
+        return wrapper
+
+    env: dict[str, Callable] = {}  # type: ignore[type-arg]
+    for func_def in imports:
+        cb = callbacks.get(func_def["camel_name"]) or callbacks.get(func_def["name"])
+        env[func_def["wasm_key"]] = make_wrapper(func_def, cb)
+    return env
+
+
+def build_component_export_proxy(
+    raw_exports: dict[str, Any],
+    wit_exports: list[dict],  # type: ignore[type-arg]
+    memory_ref: list[wasmtime.Memory | None],
+    store: wasmtime.Store,
+    cabi_realloc_ref: list[wasmtime.Func | None],
+) -> dict[str, Callable]:  # type: ignore[type-arg]
+    def make_proxy(fd: dict, raw_fn: wasmtime.Func) -> Callable:  # type: ignore[type-arg]
+        # SPEC 3.0.0: a string/aggregate-returning export returns a single i32
+        # pointer to a callee-allocated [ptr, len] pair. After reading it, the
+        # host calls the paired cabi_post_<name>(retArea) export (if present) to
+        # let the callee free that memory. <name> is the camelCase export name.
+        cabi_post = raw_exports.get(f"cabi_post_{fd['camel_name']}")
+        if not isinstance(cabi_post, wasmtime.Func):
+            cabi_post = None
+
+        def call(*args: Any) -> Any:
+            memory = memory_ref[0]
+            realloc = cabi_realloc_ref[0]
+            wasm_args: list[Any] = []
+            for p, val in zip(fd["params"], args):
+                if p["type"] == "bool":
+                    wasm_args.append(int(bool(val)))
+                elif p["type"] == "string" and memory is not None and realloc is not None:
+                    ptr, length = _encode_string(memory, store, realloc, str(val))
+                    wasm_args.extend([ptr, length])
+                else:
+                    wasm_args.append(val)
+            result = raw_fn(store, *wasm_args)
+            rt = fd.get("return_type")
+            if rt == "bool":
+                return bool(result)
+            if rt == "string" and memory is not None:
+                # The export returns a single i32 pointing at the 8-byte
+                # [ptr, len] return area (callee-allocated).
+                ret_area = int(result)
+                str_ptr = _read_i32_le(memory, store, ret_area)
+                str_len = _read_i32_le(memory, store, ret_area + 4)
+                decoded = _decode_string(memory, store, str_ptr, str_len)
+                if cabi_post is not None:
+                    cabi_post(store, ret_area)
+                return decoded
+            return result
+
+        return call
+
+    proxy: dict[str, Callable] = {}  # type: ignore[type-arg]
+    for func_def in wit_exports:
+        # wasmtk emits camelCase export names (e.g. WIT `str-len` -> `strLen`),
+        # matching the reference loader's lookup by camelCase tsName. Fall back
+        # to the underscore form for tolerance.
+        raw_fn = raw_exports.get(func_def["camel_name"]) or raw_exports.get(func_def["wasm_key"])
+        if raw_fn is not None and isinstance(raw_fn, wasmtime.Func):
+            proxy[func_def["camel_name"]] = make_proxy(func_def, raw_fn)
+    return proxy

universal_wasm_loader-1.0.0/src/universal_wasm_loader/_loader.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import asyncio
+import re
+from pathlib import Path
+from typing import Any, Callable
+
+import wasmtime
+from wasmtime import Engine, FuncType, Linker, Module, Store
+
+from ._abi import build_component_export_proxy, build_component_import_env
+from ._wit_parser import parse_wit
+
+
+def _parse_version_suffix(path: str) -> tuple[str, int | None]:
+    m = re.search(r"@(\d+)$", path)
+    return (path[: m.start()], int(m.group(1))) if m else (path, None)
+
+
+def _collect_raw_exports(
+    module: Module, instance: wasmtime.Instance, store: Store
+) -> dict[str, Any]:
+    exports_obj = instance.exports(store)
+    result: dict[str, Any] = {}
+    for exp in module.exports:
+        val = exports_obj[exp.name]
+        if val is not None:
+            result[exp.name] = val
+    return result
+
+
+def _make_noop(n_results: int) -> Callable[..., Any]:
+    if n_results == 0:
+        return lambda *_: None
+    if n_results == 1:
+        return lambda *_: 0
+    return lambda *_, n=n_results: [0] * n
+
+
+def _assert_version(raw: dict[str, Any], store: Store, expected: int, path: str) -> None:
+    g = raw.get("version")
+    if not isinstance(g, wasmtime.Global):
+        raise RuntimeError(f"{path!r}: no exported 'version' global")
+    actual = g.value(store)
+    if actual != expected:
+        raise RuntimeError(f"{path!r}: version mismatch — expected {expected}, got {actual}")
+
+
+def _wrap_for_user(raw: dict[str, Any], store: Store) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for name, val in raw.items():
+        if isinstance(val, wasmtime.Func):
+            fn = val
+            result[name] = lambda *args, f=fn: f(store, *args)
+        elif isinstance(val, wasmtime.Global):
+            result[name] = val.value(store)
+        else:
+            result[name] = val
+    return result
+
+
+async def wasm_import(
+    wasm_path: str | Path,
+    host_callbacks: dict[str, Callable[..., Any]] | None = None,
+) -> dict[str, Any]:
+    path_str = str(wasm_path)
+    cleaned, requested_version = _parse_version_suffix(path_str)
+    path = Path(cleaned)
+
+    wit: dict[str, Any] | None = None
+    wit_path = path.with_suffix(".wit")
+    if wit_path.exists():
+        try:
+            wit = parse_wit(wit_path.read_text(encoding="utf-8"))
+        except Exception:
+            wit = None
+
+    wasm_bytes = await asyncio.to_thread(path.read_bytes)
+    engine = Engine()
+    module = Module(engine, wasm_bytes)
+    store = Store(engine)
+
+    memory_ref: list[wasmtime.Memory | None] = [None]
+    cabi_realloc_ref: list[wasmtime.Func | None] = [None]
+
+    import_env: dict[str, Callable[..., Any]] = {}
+    if wit:
+        import_env = build_component_import_env(wit["imports"], host_callbacks, memory_ref, store)
+
+    linker = Linker(engine)
+    for imp in module.imports:
+        if not isinstance(imp.type, FuncType):
+            continue
+        ft: FuncType = imp.type
+        imp_name = imp.name
+        if imp_name in import_env:
+            linker.define_func(imp.module, imp_name, ft, import_env[imp_name])
+        elif host_callbacks and imp_name in host_callbacks:
+            cb = host_callbacks[imp_name]
+            linker.define_func(imp.module, imp_name, ft, lambda *a, fn=cb: fn(*a))
+        else:
+            linker.define_func(imp.module, imp_name, ft, _make_noop(len(ft.results)))
+
+    instance = linker.instantiate(store, module)
+    raw = _collect_raw_exports(module, instance, store)
+
+    mem = raw.get("memory")
+    if isinstance(mem, wasmtime.Memory):
+        memory_ref[0] = mem
+    realloc = raw.get("cabi_realloc")
+    if isinstance(realloc, wasmtime.Func):
+        cabi_realloc_ref[0] = realloc
+
+    if requested_version is not None:
+        _assert_version(raw, store, requested_version, cleaned)
+
+    if wit:
+        proxy = build_component_export_proxy(
+            raw, wit["exports"], memory_ref, store, cabi_realloc_ref
+        )
+        for name, val in raw.items():
+            if name not in proxy:
+                if isinstance(val, wasmtime.Func):
+                    fn = val
+                    proxy[name] = lambda *args, f=fn: f(store, *args)
+                elif isinstance(val, wasmtime.Global):
+                    proxy[name] = val.value(store)
+        return proxy
+
+    return _wrap_for_user(raw, store)
+
+
+def create_singleton(
+    wasm_path: str | Path,
+    host_callbacks: dict[str, Callable[..., Any]] | None = None,
+) -> Callable[[], Any]:
+    _cache: dict[str, Any] | None = None
+    _lock: asyncio.Lock | None = None
+
+    async def get() -> dict[str, Any]:
+        nonlocal _cache, _lock
+        if _lock is None:
+            _lock = asyncio.Lock()
+        async with _lock:
+            if _cache is None:
+                _cache = await wasm_import(wasm_path, host_callbacks)
+        return _cache
+
+    return get
+
+
+class InstancePool:
+    def __init__(
+        self,
+        wasm_path: str | Path,
+        host_callbacks: dict[str, Callable[..., Any]] | None = None,
+        size: int = 2,
+    ) -> None:
+        self._path = wasm_path
+        self._callbacks = host_callbacks
+        self._size = size
+        self._pool: asyncio.Queue[dict[str, Any]] | None = None
+        self._lock: asyncio.Lock | None = None
+
+    async def _ensure_ready(self) -> None:
+        if self._lock is None:
+            self._lock = asyncio.Lock()
+        async with self._lock:
+            if self._pool is not None:
+                return
+            q: asyncio.Queue[dict[str, Any]] = asyncio.Queue()
+            for inst in await asyncio.gather(
+                *[wasm_import(self._path, self._callbacks) for _ in range(self._size)]
+            ):
+                q.put_nowait(inst)
+            self._pool = q
+
+    async def acquire(self) -> dict[str, Any]:
+        await self._ensure_ready()
+        assert self._pool is not None
+        return await self._pool.get()
+
+    async def release(self, instance: dict[str, Any]) -> None:
+        if self._pool is not None:
+            await self._pool.put(instance)
+
+    async def run(self, fn: Callable[[dict[str, Any]], Any]) -> Any:
+        instance = await self.acquire()
+        try:
+            result = fn(instance)
+            if asyncio.iscoroutine(result):
+                return await result
+            return result
+        finally:
+            await self.release(instance)

universal_wasm_loader-1.0.0/src/universal_wasm_loader/_wit_parser.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import re
+
+_PRIMITIVE_TYPES = frozenset({"s32", "s64", "f32", "f64", "bool", "string"})
+
+
+def kebab_to_camel(name: str) -> str:
+    parts = name.split("-")
+    return parts[0] + "".join(p.capitalize() for p in parts[1:])
+
+
+def kebab_to_wasm_key(name: str) -> str:
+    return name.replace("-", "_")
+
+
+def parse_wit_type(raw: str) -> str:
+    t = raw.strip()
+    return t if t in _PRIMITIVE_TYPES else "s32"
+
+
+def parse_wit_params(raw: str) -> list[dict[str, str]]:
+    if not raw.strip():
+        return []
+    result: list[dict[str, str]] = []
+    for part in raw.split(","):
+        part = part.strip()
+        if ":" not in part:
+            continue
+        name_raw, type_raw = part.split(":", 1)
+        result.append({"name": kebab_to_camel(name_raw.strip()), "type": parse_wit_type(type_raw)})
+    return result
+
+
+def parse_wit_funcs(body: str, keyword: str) -> list[dict]:  # type: ignore[type-arg]
+    pattern = re.compile(
+        rf"\b{keyword}\s+([\w-]+)\s*:\s*func\s*\(([^)]*)\)\s*(?:->\s*([\w-]+))?",
+        re.MULTILINE,
+    )
+    funcs: list[dict] = []  # type: ignore[type-arg]
+    for m in pattern.finditer(body):
+        name = m.group(1)
+        funcs.append(
+            {
+                "name": name,
+                "camel_name": kebab_to_camel(name),
+                "wasm_key": kebab_to_wasm_key(name),
+                "params": parse_wit_params(m.group(2) or ""),
+                "return_type": parse_wit_type(m.group(3)) if m.group(3) else None,
+            }
+        )
+    return funcs
+
+
+def parse_wit(src: str) -> dict:  # type: ignore[type-arg]
+    pkg_match = re.search(r"package\s+([\w:@.\-/]+)\s*;", src)
+    world_match = re.search(r"world\s+([\w-]+)\s*\{([^}]*)\}", src, re.DOTALL)
+    body = world_match.group(2) if world_match else src
+    return {
+        "package": pkg_match.group(1) if pkg_match else "",
+        "world": world_match.group(1) if world_match else "",
+        "imports": parse_wit_funcs(body, "import"),
+        "exports": parse_wit_funcs(body, "export"),
+    }

universal_wasm_loader-1.0.0/tests/conftest.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+import wasmtime
+
+FIXTURES = Path(__file__).parent / "fixtures"
+
+
+def _compile_wat(name: str, tmp_dir: Path) -> Path:
+    wat_text = (FIXTURES / f"{name}.wat").read_text(encoding="utf-8")
+    engine = wasmtime.Engine()
+    # Module() accepts WAT text directly; serialize() gives canonical binary
+    module = wasmtime.Module(engine, wat_text)
+    wasm_bytes = module.serialize()
+    wasm_path = tmp_dir / f"{name}.wasm"
+    wasm_path.write_bytes(wasm_bytes)
+    return wasm_path
+
+
+def _add_wit(name: str, wasm_path: Path) -> Path:
+    wit_text = (FIXTURES / f"{name}.wit").read_text(encoding="utf-8")
+    (wasm_path.parent / f"{name}.wit").write_text(wit_text, encoding="utf-8")
+    return wasm_path
+
+
+def _stage_prebuilt(name: str, tmp_dir: Path) -> Path:
+    """Copy a prebuilt .wasm + companion .wit (produced by wasmtk) into a temp
+    dir so the loader's sibling-.wit auto-detection finds them."""
+    wasm_path = tmp_dir / f"{name}.wasm"
+    wasm_path.write_bytes((FIXTURES / f"{name}.wasm").read_bytes())
+    (tmp_dir / f"{name}.wit").write_text(
+        (FIXTURES / f"{name}.wit").read_text(encoding="utf-8"), encoding="utf-8"
+    )
+    return wasm_path
+
+
+# ── math fixtures ──────────────────────────────────────────────────────────────
+
+@pytest.fixture(scope="session")
+def math_wasm_path(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    return _compile_wat("math", tmp_path_factory.mktemp("math_no_wit"))
+
+
+@pytest.fixture(scope="session")
+def math_wasm_with_wit(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    wasm = _compile_wat("math", tmp_path_factory.mktemp("math_with_wit"))
+    return _add_wit("math", wasm)
+
+
+# ── bool fixtures ──────────────────────────────────────────────────────────────
+
+@pytest.fixture(scope="session")
+def bool_wasm_with_wit(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    wasm = _compile_wat("bool_mod", tmp_path_factory.mktemp("bool_with_wit"))
+    return _add_wit("bool_mod", wasm)
+
+
+# ── imports fixtures ───────────────────────────────────────────────────────────
+
+@pytest.fixture(scope="session")
+def imports_wasm_path(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    return _compile_wat("imports_mod", tmp_path_factory.mktemp("imports_no_wit"))
+
+
+@pytest.fixture(scope="session")
+def imports_wasm_with_wit(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    wasm = _compile_wat("imports_mod", tmp_path_factory.mktemp("imports_with_wit"))
+    return _add_wit("imports_mod", wasm)
+
+
+# ── strings fixture (prebuilt .wasm from wasmtk, SPEC 3.0.0 string ABI) ─────────
+
+@pytest.fixture(scope="session")
+def strings_wasm_with_wit(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    return _stage_prebuilt("strings_50", tmp_path_factory.mktemp("strings_with_wit"))

universal_wasm_loader-1.0.0/tests/fixtures/bool_mod.wat

@@ -0,0 +1,11 @@
+(module
+  (func (export "is_positive") (param i32) (result i32)
+    local.get 0
+    i32.const 0
+    i32.gt_s)
+  (func (export "is_even") (param i32) (result i32)
+    local.get 0
+    i32.const 2
+    i32.rem_s
+    i32.eqz)
+)

universal_wasm_loader-1.0.0/tests/fixtures/bool_mod.wit

@@ -0,0 +1,6 @@
+package example:bool@1.0.0;
+
+world bool-world {
+  export is-positive: func(n: s32) -> bool;
+  export is-even: func(n: s32) -> bool;
+}

universal_wasm_loader-1.0.0/tests/fixtures/imports_mod.wat

@@ -0,0 +1,12 @@
+(module
+  (import "env" "env_mul" (func $env_mul (param f32 f32) (result f32)))
+  (import "env" "env_add" (func $env_add (param i32 i32) (result i32)))
+  (func (export "scale") (param f32 f32) (result f32)
+    local.get 0
+    local.get 1
+    call $env_mul)
+  (func (export "combine") (param i32 i32) (result i32)
+    local.get 0
+    local.get 1
+    call $env_add)
+)

universal_wasm_loader-1.0.0/tests/fixtures/imports_mod.wit

@@ -0,0 +1,8 @@
+package example:imports@1.0.0;
+
+world imports-world {
+  import env-mul: func(a: f32, b: f32) -> f32;
+  import env-add: func(a: s32, b: s32) -> s32;
+  export scale: func(x: f32, y: f32) -> f32;
+  export combine: func(x: s32, y: s32) -> s32;
+}

universal_wasm_loader-1.0.0/tests/fixtures/math.wat

@@ -0,0 +1,7 @@
+(module
+  (global (export "version") i32 (i32.const 1))
+  (func (export "calculate") (param i32 i32) (result i32)
+    local.get 0
+    local.get 1
+    i32.add)
+)

universal_wasm_loader-1.0.0/tests/fixtures/math.wit

@@ -0,0 +1,5 @@
+package example:math@1.0.0;
+
+world math-world {
+  export calculate: func(a: s32, b: s32) -> s32;
+}

universal_wasm_loader-1.0.0/tests/fixtures/strings_50.wit

@@ -0,0 +1,8 @@
+// Generated by wasmtk wasic — do not edit manually
+package local:strings-50;
+
+world strings-50 {
+  export greet: func(name: string) -> string;
+  export shout: func(msg: string) -> string;
+  export str-len: func(s: string) -> s32;
+}

universal_wasm_loader-1.0.0/tests/test_loader.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+import pytest
+
+from universal_wasm_loader import InstancePool, create_singleton, wasm_import
+
+
+# ── raw load (no WIT) ─────────────────────────────────────────────────────────
+
+async def test_raw_load_calculate(math_wasm_path: Path) -> None:
+    exports = await wasm_import(math_wasm_path)
+    assert callable(exports["calculate"])
+    assert exports["calculate"](1, 2) == 3
+    assert exports["calculate"](10, -3) == 7
+
+
+async def test_raw_load_version_global(math_wasm_path: Path) -> None:
+    exports = await wasm_import(math_wasm_path)
+    assert exports["version"] == 1
+
+
+# ── version pinning ───────────────────────────────────────────────────────────
+
+async def test_version_pinning_ok(math_wasm_path: Path) -> None:
+    exports = await wasm_import(f"{math_wasm_path}@1")
+    assert exports["calculate"](3, 4) == 7
+
+
+async def test_version_pinning_mismatch(math_wasm_path: Path) -> None:
+    with pytest.raises(RuntimeError, match="version mismatch"):
+        await wasm_import(f"{math_wasm_path}@2")
+
+
+# ── WIT export proxy ─────────────────────────────────────────────────────────
+
+async def test_wit_export_proxy(math_wasm_with_wit: Path) -> None:
+    exports = await wasm_import(math_wasm_with_wit)
+    assert callable(exports["calculate"])
+    assert exports["calculate"](10, 5) == 15
+
+
+# ── bool ABI ─────────────────────────────────────────────────────────────────
+
+async def test_bool_export(bool_wasm_with_wit: Path) -> None:
+    exports = await wasm_import(bool_wasm_with_wit)
+    assert exports["isPositive"](5) is True
+    assert exports["isPositive"](-1) is False
+    assert exports["isPositive"](0) is False
+
+
+async def test_bool_is_even(bool_wasm_with_wit: Path) -> None:
+    exports = await wasm_import(bool_wasm_with_wit)
+    assert exports["isEven"](4) is True
+    assert exports["isEven"](3) is False
+
+
+# ── string ABI (SPEC 3.0.0: callee-allocated return + cabi_post) ──────────────
+
+async def test_string_greet(strings_wasm_with_wit: Path) -> None:
+    exports = await wasm_import(strings_wasm_with_wit)
+    assert exports["greet"]("World") == "Hello, World!"
+
+
+async def test_string_shout(strings_wasm_with_wit: Path) -> None:
+    exports = await wasm_import(strings_wasm_with_wit)
+    assert exports["shout"]("hi") == "hihi"
+
+
+async def test_string_len(strings_wasm_with_wit: Path) -> None:
+    exports = await wasm_import(strings_wasm_with_wit)
+    assert exports["strLen"]("hello") == 5
+
+
+# ── host import callbacks ─────────────────────────────────────────────────────
+
+async def test_host_callbacks_raw(imports_wasm_path: Path) -> None:
+    callbacks = {
+        "env_mul": lambda a, b: a * b,
+        "env_add": lambda a, b: a + b,
+    }
+    exports = await wasm_import(imports_wasm_path, callbacks)
+    assert exports["scale"](3.0, 4.0) == pytest.approx(12.0)
+    assert exports["combine"](10, 7) == 17
+
+
+async def test_host_callbacks_wit(imports_wasm_with_wit: Path) -> None:
+    callbacks = {
+        "envMul": lambda a, b: a * b,
+        "envAdd": lambda a, b: a + b,
+    }
+    exports = await wasm_import(imports_wasm_with_wit, callbacks)
+    assert exports["scale"](3.0, 4.0) == pytest.approx(12.0)
+    assert exports["combine"](10, 7) == 17
+
+
+# ── create_singleton ──────────────────────────────────────────────────────────
+
+async def test_create_singleton_same_instance(math_wasm_path: Path) -> None:
+    get_math = create_singleton(math_wasm_path)
+    a = await get_math()
+    b = await get_math()
+    assert a is b
+
+
+async def test_create_singleton_works(math_wasm_path: Path) -> None:
+    get_math = create_singleton(math_wasm_path)
+    math = await get_math()
+    assert math["calculate"](2, 3) == 5
+
+
+# ── InstancePool ──────────────────────────────────────────────────────────────
+
+async def test_instance_pool_run(math_wasm_path: Path) -> None:
+    pool = InstancePool(math_wasm_path, size=2)
+    r1, r2 = await asyncio.gather(
+        pool.run(lambda m: m["calculate"](1, 1)),
+        pool.run(lambda m: m["calculate"](2, 2)),
+    )
+    assert r1 == 2
+    assert r2 == 4
+
+
+async def test_instance_pool_acquire_release(math_wasm_path: Path) -> None:
+    pool = InstancePool(math_wasm_path, size=1)
+    inst = await pool.acquire()
+    assert inst["calculate"](5, 5) == 10
+    await pool.release(inst)
+    inst2 = await pool.acquire()
+    assert inst2 is inst

universal_wasm_loader-1.0.0/tests/test_wit_parser.py

@@ -0,0 +1,91 @@
+from universal_wasm_loader._wit_parser import (
+    kebab_to_camel,
+    kebab_to_wasm_key,
+    parse_wit,
+    parse_wit_funcs,
+    parse_wit_params,
+    parse_wit_type,
+)
+
+
+def test_kebab_to_camel() -> None:
+    assert kebab_to_camel("my-func") == "myFunc"
+    assert kebab_to_camel("calculate") == "calculate"
+    assert kebab_to_camel("is-positive") == "isPositive"
+    assert kebab_to_camel("env-mul") == "envMul"
+
+
+def test_kebab_to_wasm_key() -> None:
+    assert kebab_to_wasm_key("my-func") == "my_func"
+    assert kebab_to_wasm_key("env-add") == "env_add"
+    assert kebab_to_wasm_key("calculate") == "calculate"
+
+
+def test_parse_wit_type() -> None:
+    for t in ("s32", "s64", "f32", "f64", "bool", "string"):
+        assert parse_wit_type(t) == t
+    assert parse_wit_type("unknown") == "s32"
+    assert parse_wit_type("  f64  ") == "f64"
+
+
+def test_parse_wit_params() -> None:
+    result = parse_wit_params("a: s32, b: s32")
+    assert result == [{"name": "a", "type": "s32"}, {"name": "b", "type": "s32"}]
+
+    result = parse_wit_params("x: bool")
+    assert result == [{"name": "x", "type": "bool"}]
+
+    result = parse_wit_params("my-name: string")
+    assert result == [{"name": "myName", "type": "string"}]
+
+    assert parse_wit_params("") == []
+
+
+def test_parse_wit_funcs_exports() -> None:
+    body = """
+    export calculate: func(a: s32, b: s32) -> s32;
+    export is-positive: func(n: s32) -> bool;
+    import callback: func(x: s32);
+    """
+    exports = parse_wit_funcs(body, "export")
+    assert len(exports) == 2
+    assert exports[0]["name"] == "calculate"
+    assert exports[0]["camel_name"] == "calculate"
+    assert exports[0]["wasm_key"] == "calculate"
+    assert exports[0]["return_type"] == "s32"
+    assert exports[1]["name"] == "is-positive"
+    assert exports[1]["camel_name"] == "isPositive"
+    assert exports[1]["wasm_key"] == "is_positive"
+    assert exports[1]["return_type"] == "bool"
+
+
+def test_parse_wit_funcs_imports() -> None:
+    body = "import env-mul: func(a: f32, b: f32) -> f32;"
+    imports = parse_wit_funcs(body, "import")
+    assert len(imports) == 1
+    assert imports[0]["name"] == "env-mul"
+    assert imports[0]["camel_name"] == "envMul"
+    assert imports[0]["wasm_key"] == "env_mul"
+    assert imports[0]["return_type"] == "f32"
+
+
+def test_parse_wit_funcs_no_return() -> None:
+    body = "import log: func(msg: string);"
+    imports = parse_wit_funcs(body, "import")
+    assert imports[0]["return_type"] is None
+
+
+def test_parse_wit_full() -> None:
+    src = """
+    package example:math@1.0.0;
+
+    world math-world {
+      export calculate: func(a: s32, b: s32) -> s32;
+    }
+    """
+    result = parse_wit(src)
+    assert result["package"] == "example:math@1.0.0"
+    assert result["world"] == "math-world"
+    assert len(result["exports"]) == 1
+    assert result["exports"][0]["camel_name"] == "calculate"
+    assert len(result["imports"]) == 0