Establish release CI matrix (#99)

docs/release-ci-matrix.md

@@ -0,0 +1,78 @@
+# 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.
+
+## 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.