[actions] chore: explain profiling cache behavior

.github/workflows/codeprofiling.yml

@@ -16,6 +16,21 @@ jobs:
 
       - uses: dtolnay/rust-toolchain@stable
       - uses: Swatinem/rust-cache@v2
+        id: rust_cache
+        with:
+          shared-key: profiling
+
+      - name: Note cache status
+        env:
+          CACHE_HIT: ${{ steps.rust_cache.outputs.cache-hit }}
+        run: |
+          echo "### Build cache" >> "$GITHUB_STEP_SUMMARY"
+          echo >> "$GITHUB_STEP_SUMMARY"
+          if [ "$CACHE_HIT" = "true" ]; then
+            echo "Using cached cargo artifacts for hotpath profiling run." >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "Cache miss for hotpath profiling job. This is normal on the first run for a branch or after toolchain changes; the next run will populate the cache." >> "$GITHUB_STEP_SUMMARY"
+          fi
 
       - id: head_timing_metrics
         run: |
@@ -66,6 +81,69 @@ jobs:
           echo '${{ steps.base_alloc_metrics.outputs.metrics }}' > /tmp/metrics/base_alloc.json
           echo '${{ github.event.pull_request.number }}' > /tmp/metrics/pr_number.txt
 
+      - name: Publish metrics summary
+        env:
+          HEAD_TIMING: ${{ steps.head_timing_metrics.outputs.metrics }}
+          BASE_TIMING: ${{ steps.base_timing_metrics.outputs.metrics }}
+          HEAD_ALLOC: ${{ steps.head_alloc_metrics.outputs.metrics }}
+          BASE_ALLOC: ${{ steps.base_alloc_metrics.outputs.metrics }}
+        run: |
+          {
+            echo "## Hotpath profiling metrics"
+            echo
+            echo "### Timing"
+            echo
+            echo "<details><summary>Head</summary>"
+            echo
+            printf '```json\n'
+            if [ -n "$HEAD_TIMING" ]; then
+              printf '%s\n' "$HEAD_TIMING"
+            else
+              echo '{}'
+            fi
+            printf '```\n'
+            echo
+            echo "</details>"
+            echo
+            echo "<details><summary>Base</summary>"
+            echo
+            printf '```json\n'
+            if [ -n "$BASE_TIMING" ]; then
+              printf '%s\n' "$BASE_TIMING"
+            else
+              echo '{}'
+            fi
+            printf '```\n'
+            echo
+            echo "</details>"
+            echo
+            echo "### Allocation"
+            echo
+            echo "<details><summary>Head</summary>"
+            echo
+            printf '```json\n'
+            if [ -n "$HEAD_ALLOC" ]; then
+              printf '%s\n' "$HEAD_ALLOC"
+            else
+              echo '{}'
+            fi
+            printf '```\n'
+            echo
+            echo "</details>"
+            echo
+            echo "<details><summary>Base</summary>"
+            echo
+            printf '```json\n'
+            if [ -n "$BASE_ALLOC" ]; then
+              printf '%s\n' "$BASE_ALLOC"
+            else
+              echo '{}'
+            fi
+            printf '```\n'
+            echo
+            echo "</details>"
+          } >> "$GITHUB_STEP_SUMMARY"
+
       - uses: actions/upload-artifact@v4
         with:
           name: profile-metrics

.github/workflows/slsa-release.yml

@@ -71,9 +71,21 @@ jobs:
 
       - name: Package binaries
         run: |
+          set -euo pipefail
           mkdir -p dist
-          tar -czf dist/shadowmap-${GITHUB_REF_NAME}.tar.gz -C target/release shadowmap
-          sha256sum dist/* > dist/shadowmap-${GITHUB_REF_NAME}.sha256
+          umask 0022
+          GZIP=-n tar \
+            --sort=name \
+            --mtime='@0' \
+            --owner=0 \
+            --group=0 \
+            --numeric-owner \
+            -czf dist/shadowmap-${GITHUB_REF_NAME}.tar.gz \
+            -C target/release shadowmap
+          (
+            cd dist
+            sha256sum shadowmap-${GITHUB_REF_NAME}.tar.gz > shadowmap-${GITHUB_REF_NAME}.sha256
+          )
 
       - name: Generate SBOM
         uses: anchore/sbom-action@e812a0fdf0d83f33cd9ba7f8c4ce3e9e2f8d2c9d
@@ -140,9 +152,21 @@ jobs:
 
       - name: Package reproducibility outputs
         run: |
+          set -euo pipefail
           mkdir -p dist
-          tar -czf dist/shadowmap-${GITHUB_REF_NAME}.tar.gz -C target/release shadowmap
-          sha256sum dist/* > dist/shadowmap-${GITHUB_REF_NAME}.sha256
+          umask 0022
+          GZIP=-n tar \
+            --sort=name \
+            --mtime='@0' \
+            --owner=0 \
+            --group=0 \
+            --numeric-owner \
+            -czf dist/shadowmap-${GITHUB_REF_NAME}.tar.gz \
+            -C target/release shadowmap
+          (
+            cd dist
+            sha256sum shadowmap-${GITHUB_REF_NAME}.tar.gz > shadowmap-${GITHUB_REF_NAME}.sha256
+          )
 
       - name: Upload rebuild artifacts
         uses: actions/upload-artifact@c7d6c3d5c0f8b7b2e07c5e6c5a9a7d1e2b9db4c4

docs/hotpath-profiling-overview.md

@@ -0,0 +1,22 @@
+# Hotpath Profiling Workflow Overview
+
+The `hotpath-profile` GitHub Actions workflow runs a lightweight benchmark so we can quickly compare how the main execution path performs on a pull request versus the base branch.
+
+## What the workflow builds
+
+1. **Compile the binary** – We build the ShadowMap binary with the profiling feature flags enabled.
+2. **Run focused benchmarks** – The workflow runs the `examples/benchmark` target twice, once to measure timing data and once to record allocation counts.
+3. **Compare pull request vs. base branch** – After the pull request metrics are collected, the workflow checks out the base branch and repeats the measurements so we can spot regressions.
+4. **Publish the results** – The collected JSON metrics are uploaded as an artifact and rendered in the job summary so reviewers can read them without downloading anything.
+
+## Why the cache might be missing
+
+The workflow uses `Swatinem/rust-cache` to reuse compiled dependencies between runs. When the cache logs `Cache not found for keys ...`, it simply means we do not yet have a saved cache for that exact key. Common reasons include:
+
+- The workflow is running for the first time on a branch.
+- The toolchain or dependency lockfile changed, invalidating the previous cache.
+- GitHub rotated runners and the cache has not been restored yet.
+
+After the run completes, the job saves the new cache key so the next invocation should hit the cache and skip rebuilding unchanged dependencies.
+
+Share this explanation with anyone who sees the cache miss message—it is informational and does not indicate a failure in the profiling workflow.