Audit public API and SemVer surface (#103)

.gitea/workflows/api-surface.yml

@@ -0,0 +1,81 @@
+name: API and SemVer surface
+
+on:
+  push:
+    paths:
+      - ".gitea/workflows/api-surface.yml"
+      - "Cargo.lock"
+      - "Cargo.toml"
+      - "api/**"
+      - "ci/evidence/api-audit.json"
+      - "crates/**"
+      - "tests/api-compile/**"
+      - "tests/semver-port/**"
+      - "tools/check_api_coverage.py"
+      - "tools/generate_api_shims.py"
+      - "tools/generate_rust_mapping.py"
+      - "tools/ci-matrix/**"
+  pull_request:
+    paths:
+      - ".gitea/workflows/api-surface.yml"
+      - "Cargo.lock"
+      - "Cargo.toml"
+      - "api/**"
+      - "ci/evidence/api-audit.json"
+      - "crates/**"
+      - "tests/api-compile/**"
+      - "tests/semver-port/**"
+      - "tools/check_api_coverage.py"
+      - "tools/generate_api_shims.py"
+      - "tools/generate_rust_mapping.py"
+      - "tools/ci-matrix/**"
+
+jobs:
+  api-surface:
+    runs-on: ubuntu-latest
+    env:
+      CARGO_BUILD_JOBS: "1"
+      CARGO_INCREMENTAL: "0"
+      CARGO_PROFILE_DEV_DEBUG: "0"
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install native prerequisites
+        run: sudo apt-get update && sudo apt-get install -y libopus-dev pkg-config
+
+      - name: Install Rust 1.97
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          toolchain: "1.97.0"
+          components: rustfmt, clippy
+
+      - name: Verify deterministic mapping and export coverage
+        run: |
+          python3 tools/generate_rust_mapping.py --check
+          python3 tools/generate_api_shims.py --check
+          python3 tools/check_api_coverage.py
+
+      - name: Verify reviewed API baseline
+        run: |
+          cargo run --locked -p metacrate-ci-matrix -- api-baseline-write
+          git diff --exit-code -- api/SEMVER-BASELINE.json api/SEMVER-AUDIT.md
+          cargo run --locked -p metacrate-ci-matrix -- api-audit --evidence /tmp/metacrate-api-audit.json
+          cmp /tmp/metacrate-api-audit.json ci/evidence/api-audit.json
+
+      - name: Compile downstream API consumers
+        run: |
+          cargo check --locked --manifest-path tests/api-compile/Cargo.toml
+          cargo run --locked --manifest-path tests/semver-port/Cargo.toml
+
+      - name: Check formatting and lints
+        run: |
+          cargo fmt --all -- --check
+          cargo fmt --manifest-path tests/semver-port/Cargo.toml -- --check
+          cargo clippy --locked -p metacrate-ci-matrix --all-targets -- -D warnings
+          cargo clippy --locked --manifest-path tests/semver-port/Cargo.toml --all-targets -- -D warnings
+
+      - name: Upload audit evidence
+        uses: actions/upload-artifact@v4
+        with:
+          name: api-semver-audit
+          path: ci/evidence/api-audit.json