Distribution Support and Clean-Install Evidence

ZapTrace is pre-1.0. This page is the public support contract for package and container artifacts. The machine-readable source of truth is config/distribution-support.json.

A platform is supported only when the exact artifact is continuously built, installed outside the source tree, and exercised through the applicable CLI, SDK, REST API, and MCP entry points. A compatibility test or successful compilation alone does not create a release-support claim.

Current distribution channels

• GitHub Releases is the authoritative channel for source distributions, supported native wheels, checksums, SBOMs, attestations, and clean-install evidence.
• PyPI publication is not enabled. The project name, registry ownership, and credential policy remain unresolved; do not assume pip install zaptrace resolves to an official ZapTrace package.
• GHCR publication is not enabled. The pinned Dockerfile is continuously built and verified, but no official registry image is currently claimed.
• A source checkout remains available for contributors and for explicitly best-effort or unsupported combinations.

Support levels

• supported: the named artifact/platform combination is continuously clean-installed and smoke-tested.
• best-effort: bounded compatibility or source-build evidence exists, but the combination does not receive the complete tagged-release artifact contract.
• unsupported: no artifact is published or continuously verified for that combination. The guidance column gives the safe next step.

Support matrix

Target ID	OS	Architecture	Python	Artifact	Native extension	Support level	Channel	Guidance
native-linux-x86_64-cp313	Linux	x86_64	CPython 3.13	native wheel (manylinux_x86_64)	required	supported	GitHub Releases	Install the matching Linux x86_64 wheel.
native-macos-x86_64-cp313	macOS	x86_64	CPython 3.13	native wheel (macosx_x86_64)	required	supported	GitHub Releases	Install the matching macOS Intel wheel.
native-macos-arm64-cp313	macOS	arm64	CPython 3.13	native wheel (macosx_arm64)	required	supported	GitHub Releases	Install the matching Apple Silicon wheel.
sdist-linux-x86_64-cp313	Linux	x86_64	CPython 3.13	source distribution	absent	supported	GitHub Releases	Use the verified pure-Python fallback.
source-linux-x86_64-cp312	Linux	x86_64	CPython 3.12	source distribution	absent	best-effort	GitHub Releases	Source compatibility is tested, but tagged clean-install evidence is produced on CPython 3.13.
source-linux-x86_64-cp314	Linux	x86_64	CPython 3.14	source distribution	absent	best-effort	GitHub Releases	Compatibility is tested, but tagged clean-install evidence is produced on CPython 3.13.
container-linux-x86_64-cp313	Linux	x86_64	CPython 3.13	container image (linux/amd64)	required	best-effort	source build only	Build the pinned Dockerfile from reviewed release source; GHCR is not enabled.
native-linux-arm64-cp313	Linux	arm64	CPython 3.13	native wheel (manylinux_aarch64)	required	unsupported	none	No native wheel is published. Use the source distribution as an unverified fallback or build from source until a dedicated runner is added.
native-windows-x86_64-cp313	Windows	x86_64	CPython 3.13	native wheel (win_amd64)	required	unsupported	none	No native wheel or isolated mutating-agent runtime is supported. Use the source distribution only for unverified read-only SDK/CLI experiments; use WSL or the Linux container for agent mutations.
native-linux-x86_64-cp312	Linux	x86_64	CPython 3.12	native wheel (manylinux_x86_64)	required	unsupported	none	Use the source distribution pure-Python fallback or CPython 3.13 for a supported native wheel.
native-linux-x86_64-cp314	Linux	x86_64	CPython 3.14	native wheel (manylinux_x86_64)	required	unsupported	none	Use the source distribution pure-Python fallback or CPython 3.13 for a supported native wheel.

The JSON policy remains authoritative when prose and policy differ. CI validates unique target IDs, required fields, support levels, verification workflow references, and actionable unsupported-target guidance.

Installing a GitHub Release artifact

List and download the assets for a tag:

gh release view <tag> --repo oaslananka/zaptrace
gh release download <tag> --repo oaslananka/zaptrace --dir /tmp/zaptrace-release

Create a clean environment and install the artifact that matches the matrix:

uv venv /tmp/zaptrace-env --python 3.13
uv pip install --python /tmp/zaptrace-env/bin/python /tmp/zaptrace-release/zaptrace-<version>-<tag>.whl
/tmp/zaptrace-env/bin/zaptrace --version
/tmp/zaptrace-env/bin/zaptrace --help

For the source distribution fallback, replace the wheel path with zaptrace-<version>.tar.gz. A source distribution may build a pure-Python package without zaptrace._core; native acceleration is not implied.

Clean-install evidence

The release workflow retains one report for every claimed package artifact:

• distribution-smoke-sdist-linux-x86_64-cp313.json and its Markdown summary;
• distribution-smoke-<target-id>.json and its Markdown summary for each native wheel;
• existing native-boundary-<rust-target>.json evidence for native behavior and resource limits;
• existing exact-image container provenance, SBOM, vulnerability, and Compose REST/MCP smoke evidence.

Each distribution report records:

• artifact filename, size, and SHA-256;
• exact source commit and uv.lock SHA-256;
• Python implementation/version, operating system, and architecture;
• installed package path and source-tree isolation result;
• zaptrace --version and zaptrace --help;
• SDK import and minimal public-model construction;
• required, optional, or absent native-extension state;
• loopback REST health/authentication checks;
• loopback MCP HTTP authentication, initialize identity, and session cleanup;
• deterministic evidence digest and explicit non-claims.

The JSON/Markdown evidence is downloaded into the release aggregation job before the release SBOM and SHA256SUMS are generated. Missing evidence blocks release creation.

Unsupported combinations

Unsupported does not mean a platform can never run ZapTrace. It means the project does not publish and continuously verify the named artifact. For Linux arm64, Windows x86_64, CPython 3.12 native, and CPython 3.14 native combinations:

1. prefer the source distribution pure-Python fallback;
2. treat local native builds as unverified local artifacts;
3. do not report a local successful build as project-supported;
4. retain the build logs, artifact hash, interpreter identity, and smoke results when proposing a new supported target.

A target becomes supported only after a dedicated CI runner builds the exact artifact, installs it in a clean environment, exercises the public entry points, and retains evidence on every tagged release.

Windows agent-runtime boundary

The isolated mutating-agent worker relies on POSIX process groups, private mode bits, and directory-relative IPC operations. Native Windows execution therefore rejects mutating agent and MCP tools before a worker starts, with the stable UNSUPPORTED_PLATFORM error. Read-only SDK/CLI experiments remain unverified; use WSL or the verified Linux container when agent mutations are required.

Container boundary

The Dockerfile produces a Linux x86_64 image with a locally built native wheel, hash-complete Python dependencies, exact Alpine packages, embedded source/base/dependency provenance, SBOM generation, vulnerability policy, and Compose REST/MCP smoke tests. This is strong source-build evidence, but it is best-effort distribution support because GHCR publication is not enabled.

Non-claims

Passing clean-install checks proves only the named artifact, interpreter, runner, and bounded entrypoint checks. It does not establish universal platform support, formal verification, production qualification, fabrication readiness, manufacturer approval, regulatory compliance, or immunity from platform-specific defects. Unsupported and best-effort targets remain outside the supported release contract until continuous evidence exists.