feat: add cairo-metrics benchmark harness + CI tracking

- Introduce `cairo-metrics`: a small CLI that currently checks wall-clock regressions from main.
- Persist results in `repo_root/results.db` (git-ignored), currently SQLite keyed by run
id (defaults to current git SHA). This enables caching and tracking results across time locally by
checking out builds starting from this commit, and having the tool populate the db.
The tool then allows comparisons based on the db results. Future work can easily extend this to
a stateful DB machine (like RDS), since the DB is behind a trait.
- Add a GitHub Actions workflow that benchmarks baseline vs PR, reuses cached baseline results
via artifacts (saves ci runtime for multiple PR runs over the same base branch), and posts a
“Benchmark Comparison” PR comment, not blocking, the reviewer decided.
- Seed initial benchmark suites (corelib + OpenZeppelin): corelib uses local src, and openzepplin
is bundeled as a vendored release (not a submodule for simplicity).
- Walltime engine is either home-brewed timed comparison of the compiler library,
or via `hyperfine` which uses the binary. It uses hyperfine by
default if available (need to install with `apt`) otherwise the builtin.
This is useful locally, to debug the builtin engine itself
(results are similar since hyperfine cancels out shell overhead), and since
hyperfine outputs useful statistical anomaly messages.
But if hyperfine is a pain to maintain it can be removed.

Author: Gilad Chase

.github/workflows/benchmarks.yml

@@ -0,0 +1,121 @@
+name: Benchmarks
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  merge_group:
+    types: [checks_requested]
+
+jobs:
+  # Run cairo-metrics and post a non-blocking comment on the PR if spotted regressions.
+  benchmark:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: '0'
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: Swatinem/rust-cache@v2
+      - name: Get SHAs
+        id: shas
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            BASE_SHA=$(git rev-parse origin/${{ github.base_ref }})
+          else
+            BASE_SHA=$(git rev-parse HEAD~1 || echo "")
+          fi
+          echo "base_sha=$BASE_SHA" >> $GITHUB_OUTPUT
+          echo "pr_sha=${{ github.sha }}" >> $GITHUB_OUTPUT
+
+      - name: Restore cached baseline
+        if: steps.shas.outputs.base_sha != ''
+        id: cache-baseline
+        uses: actions/cache/restore@v4
+        with:
+          path: results.db
+          key: benchmark-${{ steps.shas.outputs.base_sha }}
+
+      - name: Build cairo-metrics
+        run: cargo build --profile=ci-dev -p cairo-metrics
+
+      - name: Benchmark baseline
+        if: steps.shas.outputs.base_sha != '' && steps.cache-baseline.outputs.cache-hit != 'true'
+        run: |
+          git checkout ${{ steps.shas.outputs.base_sha }}
+          ./target/ci-dev/cairo-metrics run ${{ steps.shas.outputs.base_sha }}
+          git checkout -
+
+      - name: Cache baseline results
+        if: steps.shas.outputs.base_sha != '' && steps.cache-baseline.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v4
+        with:
+          path: results.db
+          key: benchmark-${{ steps.shas.outputs.base_sha }}
+
+      - name: Benchmark current
+        run: ./target/ci-dev/cairo-metrics run
+
+      - name: Cache current results (current can be base of stacked PR)
+        uses: actions/cache/save@v4
+        with:
+          path: results.db
+          key: benchmark-${{ steps.shas.outputs.pr_sha }}
+
+      - name: Compare
+        if: github.event_name == 'pull_request' && steps.shas.outputs.base_sha != ''
+        id: compare
+        run: |
+          ./target/ci-dev/cairo-metrics compare \
+            ${{ steps.shas.outputs.base_sha }} \
+            ${{ steps.shas.outputs.pr_sha }} \
+            > comparison.txt 2>&1 || true
+          cat comparison.txt
+
+      - name: Post comparison comment
+        if: github.event_name == 'pull_request' && steps.shas.outputs.base_sha != ''
+        continue-on-error: true
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require('fs');
+            let output = '';
+            try {
+              output = fs.readFileSync('comparison.txt', 'utf8');
+            } catch (e) { return; }
+
+            const body = `## Benchmark Comparison
+
+            \`\`\`
+            ${output}
+            \`\`\`
+            `;
+
+            const comments = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const botComment = comments.data.find(c =>
+              c.user.type === 'Bot' && c.body.includes('Benchmark Comparison')
+            );
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body
+              });
+            }

.gitignore

@@ -6,6 +6,7 @@ node_modules
 .DS_Store
 perf.data*
 flamegraph.svg
+results.db*
 
 ensure-no_std/Cargo.lock
 ensure-no_std/target/