# Release platform and feature CI matrix

The release matrix is declared in [`ci/release-matrix.json`](../ci/release-matrix.json)
and validated and executed by the native Rust `metacrate-ci-matrix` tool. The
manifest is the single reviewed inventory of toolchains, targets, feature sets,
native prerequisites, Cargo commands, and explicit manual gates. The runner
does not execute shell fragments from the manifest: every entry is an
allow-listed Cargo subcommand and argument list.

## Platform boundary

Repository policy requires every Gitea Actions job to use `ubuntu-latest`.
Accordingly, the matrix runs the complete default, minimal, optional-feature,
test, example, and documentation surfaces natively on Linux. Windows GNU and
macOS use their official Rust standard-library targets from the same Ubuntu
host to compile the portable public crates with default features disabled.
Those cross-target profiles cover code selected by `cfg` without pretending to
run Windows or macOS executables or to possess an Apple SDK.

Platform-native Skia, OpenJPEG, Opus, Vorbis, and CPAL adapters are exercised
in isolated Linux profiles with their versions recorded. WASAPI, CoreAudio,
platform packaging, and physical-device behavior remain explicit release/manual
gates; a successful Ubuntu cross check is never reported as a native runtime
test on another operating system.

## Feature isolation

`libremetaverse` defaults to the pure-Rust `dds-bc67` feature. OpenJPEG-backed
JPEG 2000 and Vorbis encoding are independently selectable as `jpeg2000` and
`vorbis`; neither native codec is discovered or linked for a default library
consumer. Skia and CPAL remain isolated in their existing `skia` and
`real-audio` features. The matrix validates each feature independently before
checking workspace-wide `--all-features` unification.

The checked profiles cover:

- Rust 1.96.0 and current stable;
- native Linux default, no-default, individual optional features, and all
  features;
- all targets, test compilation and execution, doctests, shipped
  example-program binaries, and API documentation;
- portable Windows GNU and macOS cross-target compilation;
- exact OpenJPEG, Skia, Opus, ALSA, and Vorbis prerequisite declarations.

Dependency purpose, maintenance, license, advisory, source, and duplicate
review is the separate supply-chain gate documented in
[`dependency-policy.md`](dependency-policy.md). Changes to manifests or the
lockfile trigger both gates.

Release-file provenance, Linden CC BY-SA separation, complete locked package
notices, native redistribution obligations, and the source/binary notice set
are enforced by the companion
[`release provenance audit`](release-provenance.md). Its distribution manifest
hashes the full source tree, so the supply-chain workflow runs for every source
change rather than only dependency changes.

## Clean-build evidence

Each profile uses `target/ci/<profile>` and refuses to start if that directory
already exists. Incremental compilation is disabled. This makes an accidental
cache hit a hard failure instead of allowing it to hide a missing clean-build
dependency. Gitea may cache Cargo registry and Git downloads using a key derived
from the lockfile and toolchain; it never caches a `target` directory. Each
successful or failed run creates one JSON evidence file with the source commit,
requested toolchain and target, actual `rustc` and Cargo versions, feature sets,
native prerequisite versions, exact Cargo commands, completion count,
timestamp, and final status.

Run the audit locally with:

```sh
cargo run --locked -p metacrate-ci-matrix -- audit
```

Run one clean profile with:

```sh
cargo run --locked -p metacrate-ci-matrix -- \
  run linux-stable-minimal \
  --evidence /tmp/metacrate-linux-stable-minimal.json
```

Before rerunning the same profile, use Cargo's scoped cleanup command:

```sh
cargo clean --target-dir target/ci/linux-stable-minimal
```

Live-grid credentials, physical audio devices, and proprietary services remain
outside automatic CI and retain their dedicated opt-in gates.