Wave 1: eval-explain, shadow-mode, cli-distribution, editor-schemas, diff-fuzz-bench

.github/workflows/ci.yml

@@ -228,6 +228,72 @@ jobs:
       - name: Check cross-SDK roundtrip equivalence
         run: python3 scripts/check_cross_sdk_roundtrip.py
 
+  differential-fuzz:
+    name: Differential Fuzz
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.22'
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Build TypeScript package
+        run: npm run build
+
+      - name: Install Python package
+        run: pip install -e "packages/python[dev]"
+
+      - name: Run differential fuzz (PR budget, deterministic per commit)
+        run: |
+          cargo run --release -p hushspec-testkit --bin hushspec-difftest -- \
+            --seed-from-string "$GITHUB_SHA" \
+            --groups 500 --actions-per-group 4 \
+            --report target/difftest/report.json
+
+      - name: Upload divergence artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: difftest-artifacts
+          path: target/difftest/
+
+  bench-thresholds:
+    name: Bench Thresholds
+    runs-on: ubuntu-latest
+    env:
+      # CI runners are noisy; local defaults (10/2) encode the roadmap claim.
+      HUSHSPEC_BENCH_BUDGET_ENABLED_US: '25'
+      HUSHSPEC_BENCH_BUDGET_DISABLED_US: '5'
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Compile benches
+        run: cargo bench -p hushspec --bench evaluation --no-run
+
+      - name: Enforce receipt-overhead budgets
+        run: cargo test -p hushspec --release --test bench_thresholds -- --ignored --nocapture
+
   docs:
     name: Docs
     runs-on: ubuntu-latest
@@ -240,3 +306,8 @@ jobs:
 
       - name: Build book
         run: mdbook build docs
+
+      - name: Publish schemas at their $id URLs
+        run: |
+          mkdir -p docs/book/schemas
+          cp schemas/*.json docs/book/schemas/

.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: peaceiris/actions-mdbook@v2
+        with:
+          mdbook-version: latest
+
+      - name: Build book
+        run: mdbook build docs
+
+      - name: Publish schemas at their $id URLs
+        run: |
+          mkdir -p docs/book/schemas
+          cp schemas/*.json docs/book/schemas/
+
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/book
+
+      - id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/fuzz-nightly.yml

@@ -0,0 +1,58 @@
+name: Nightly Fuzz
+
+on:
+  schedule:
+    - cron: '17 3 * * *'
+  workflow_dispatch:
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  differential-deep:
+    name: Differential Deep Fuzz
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: dtolnay/rust-toolchain@stable
+
+      - uses: Swatinem/rust-cache@v2
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.22'
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Build TypeScript package
+        run: npm run build
+
+      - name: Install Python package
+        run: pip install -e "packages/python[dev]"
+
+      - name: Deep differential fuzz (random seed, minimized fixture candidates)
+        run: |
+          cargo run --release -p hushspec-testkit --bin hushspec-difftest -- \
+            --chunks 100 --max-seconds 1500 \
+            --groups 250 --actions-per-group 4 \
+            --minimize \
+            --emit-fixtures target/difftest/fixture-candidates \
+            --report target/difftest/report.json
+
+      - name: Upload run artifacts (bundles, report, fixture candidates)
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: nightly-difftest
+          path: target/difftest/

.github/workflows/release.yml

@@ -0,0 +1,140 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Existing tag to (re)build artifacts for"
+        required: true
+
+env:
+  TAG: ${{ github.event.inputs.tag || github.ref_name }}
+
+jobs:
+  build:
+    strategy:
+      fail-fast: true
+      matrix:
+        include:
+          - { target: x86_64-unknown-linux-gnu,  os: ubuntu-latest,   cross: false }
+          - { target: aarch64-unknown-linux-gnu, os: ubuntu-latest,   cross: true }
+          - { target: x86_64-apple-darwin,       os: macos-15-intel,  cross: false }
+          - { target: aarch64-apple-darwin,      os: macos-14,        cross: false }
+          - { target: x86_64-pc-windows-msvc,    os: windows-latest,  cross: false }
+    runs-on: ${{ matrix.os }}
+    steps:
+      - name: Validate tag format
+        shell: bash
+        run: |
+          [[ "$TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[A-Za-z0-9.]+)?$ ]] || { echo "::error::TAG must look like v<semver>: $TAG"; exit 1; }
+      - uses: actions/checkout@v4
+        with:
+          ref: ${{ env.TAG }}
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+      - uses: Swatinem/rust-cache@v2
+      - name: Install cross
+        if: matrix.cross
+        run: cargo install cross --locked
+      - name: Build
+        shell: bash
+        run: |
+          if [ "${{ matrix.cross }}" = "true" ]; then
+            cross build -p hushspec-cli --release --locked --target ${{ matrix.target }}
+          else
+            cargo build -p hushspec-cli --release --locked --target ${{ matrix.target }}
+          fi
+      - name: Package
+        shell: bash
+        run: |
+          bin="h2h"; [ "${{ runner.os }}" = "Windows" ] && bin="h2h.exe"
+          stage="h2h-${TAG}-${{ matrix.target }}"
+          mkdir "$stage"
+          cp "target/${{ matrix.target }}/release/${bin}" LICENSE README.md "$stage/"
+          tar -czf "${stage}.tar.gz" "$stage"
+      - uses: actions/upload-artifact@v4
+        with:
+          name: h2h-${{ matrix.target }}
+          path: h2h-*.tar.gz
+          retention-days: 3
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          merge-multiple: true
+      - name: Checksums
+        run: sha256sum h2h-*.tar.gz > SHA256SUMS
+      - uses: actions/attest-build-provenance@v2
+        with:
+          subject-path: "h2h-*.tar.gz"
+      - name: Ensure release exists
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release view "$TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1 || \
+            gh release create "$TAG" --repo "$GITHUB_REPOSITORY" --verify-tag --generate-notes
+      - name: Upload to release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh release upload "$TAG" h2h-*.tar.gz SHA256SUMS --repo "$GITHUB_REPOSITORY" --clobber
+
+  homebrew:
+    needs: release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          merge-multiple: true
+      - name: Regenerate checksums locally
+        run: sha256sum h2h-*.tar.gz > SHA256SUMS
+      - name: Render and PR formula
+        env:
+          GH_TOKEN: ${{ secrets.TAP_GITHUB_TOKEN }}
+        run: |
+          bash scripts/render_formula.sh "$TAG" SHA256SUMS > h2h.rb
+          gh repo clone backbay-labs/homebrew-tap tap
+          gh auth setup-git
+          cd tap
+          git checkout -b "h2h-${TAG}"
+          mkdir -p Formula && cp ../h2h.rb Formula/h2h.rb
+          git add Formula/h2h.rb
+          git -c user.name=hushspec-release -c user.email=noreply@backbay-labs.dev \
+            commit -m "h2h ${TAG}"
+          git push origin "h2h-${TAG}"
+          gh pr create --repo backbay-labs/homebrew-tap \
+            --title "h2h ${TAG}" --body "Automated formula update for ${TAG}."
+
+  npm-cli:
+    needs: release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          merge-multiple: true
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: "https://registry.npmjs.org"
+      - name: Generate packages
+        run: node scripts/gen_npm_cli.mjs "$TAG" . out/
+      - name: Publish (platform packages, then meta)
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          for d in out/cli-*; do (cd "$d" && npm publish --access public --provenance); done
+          (cd out/cli && npm publish --access public --provenance)

.gitignore

@@ -15,6 +15,10 @@ dist/
 *.wasm
 docs/book/
 
+# Generated npm packages (scripts/gen_npm_cli.mjs release output; not a
+# workspace member -- keep out of both git and npm's workspace globs)
+/out/
+
 # IDE
 .idea/
 .vscode/

CLAUDE.md

@@ -97,6 +97,10 @@ h2h lint rulesets/default.yaml
 # Run evaluation test suites
 h2h test --fixtures fixtures/core/evaluation
 
+# One-shot action evaluation with decision trace
+h2h eval rulesets/default.yaml --type egress --target api.example.com
+h2h explain rulesets/default.yaml --type egress --target api.example.com
+
 # Scaffold a new policy project
 h2h init --preset default
 
@@ -119,6 +123,25 @@ h2h verify policy.yaml --key h2h.pub
 cargo run -p hushspec-testkit -- --fixtures fixtures
 ```
 
+### Differential Fuzzing & Benchmarks
+
+```bash
+# Generate a portable differential case bundle
+cargo run -p hushspec-testkit --bin hushspec-gen -- --seed 42 --groups 50 --out bundle.json
+
+# Differential fuzz across all four SDKs (requires npm run build + pip install first)
+cargo run --release -p hushspec-testkit --bin hushspec-difftest -- --seed 42 --groups 250
+
+# Replay a saved bundle artifact
+cargo run --release -p hushspec-testkit --bin hushspec-difftest -- --bundle target/difftest/bundle-42.json
+
+# Criterion benchmarks
+cargo bench -p hushspec --bench evaluation
+
+# Receipt-overhead CI gate (release mode only)
+cargo test -p hushspec --release --test bench_thresholds -- --ignored --nocapture
+```
+
 ## Conventions
 
 - **`deny_unknown_fields`** on all serde struct types -- unknown YAML/JSON keys are parse errors