perfgate 0.1.0

data/SECURITY.md

@@ -0,0 +1,63 @@
+# Security Policy
+
+## Supported versions
+
+Baseline is pre-1.0. Security fixes are made against the latest release
+on the default branch; there is no long-term support branch yet.
+
+| Version | Supported |
+| ------- | --------- |
+| latest  | yes       |
+| < 0.1   | no        |
+
+## Reporting a vulnerability
+
+Please do not open a public GitHub issue for suspected security
+vulnerabilities. Instead, use GitHub's private
+[vulnerability reporting](https://github.com/baseline-oss/perfgate/security/advisories/new)
+feature, or email the maintainer directly at bendthe@gmail.com with:
+
+- a description of the issue and its potential impact;
+- steps to reproduce, or a minimal repro case;
+- the Baseline version, Ruby version, and Rails version involved.
+
+You should receive an acknowledgment within 5 business days. We'll work
+with you to understand and confirm the issue, agree on a disclosure
+timeline, and credit you in the release notes unless you'd prefer to
+stay anonymous.
+
+## What's in scope
+
+- The `baseline` gem's CLI, execution engine, comparison/policy logic,
+  and filesystem storage adapter.
+- Archive import handling (path traversal, malformed archives).
+- Anything that could cause Baseline to execute untrusted code,
+  deserialize untrusted data unsafely, or exfiltrate source code, SQL,
+  or environment values it isn't supposed to touch (see the data
+  handling guarantees in the technical specification, section 22).
+
+## What's out of scope
+
+- The example Rails application under `examples/`, which is
+  illustrative only and not meant to be run as a real service.
+- Vulnerabilities that require the attacker to already control
+  `baseline.yml` or the workload specs in a repository that has
+  chosen to run Baseline (i.e. arbitrary Ruby code a repository owner
+  chose to execute in their own CI).
+
+## Baseline's security posture
+
+By design, Baseline:
+
+- makes no mandatory network requests;
+- never sends source code, SQL text, bind values, or environment
+  values off the machine it runs on;
+- treats imported result bundles and archives as untrusted input,
+  parses them as JSON (never `Marshal` or other Ruby object
+  deserialization formats), and rejects path traversal in archive
+  entries;
+- keeps telemetry opt-in and disabled by default (see
+  [docs/telemetry.md](docs/telemetry.md)).
+
+A vulnerability report that Baseline violates one of these guarantees
+is always in scope, even if it wasn't listed above.

data/docs/README.md

@@ -0,0 +1,7 @@
+# Baseline Documentation
+
+This directory will hold user-facing documentation (installation, CLI
+reference, configuration reference, CI integration guides) as the gem is
+implemented. Until then, refer to
+[../baseline_oss_mvp_technical_spec_and_roadmap.md](../../baseline_oss_mvp_technical_spec_and_roadmap.md)
+for the authoritative specification.

data/docs/architecture.md

@@ -0,0 +1,125 @@
+# Architecture
+
+Baseline is a layered pipeline: each layer has a single responsibility and hands
+off a well-typed value to the next. No layer reaches backwards.
+
+```
+RSpec examples
+     │
+     ▼
+┌─────────────┐
+│  Discovery  │  rspec/discovery.rb, rspec/workload_builder.rb
+│             │  Finds :baseline-tagged examples; builds Workload objects
+└──────┬──────┘
+       │  []Workload
+       ▼
+┌─────────────┐
+│  Execution  │  execution/runner.rb, execution/process_runner.rb
+│             │  Warmup → measured samples; isolates each run in a subprocess
+└──────┬──────┘
+       │  raw sample arrays (ns integers)
+       ▼
+┌──────────────────┐
+│ Instrumentation  │  instrumentation/{duration,sql_activity,allocations,gc}.rb
+│                  │  Wraps Perfgate.measure { } with collectors for each metric
+└────────┬─────────┘
+         │  SampleContext per metric
+         ▼
+┌────────────────┐
+│  Statistics    │  statistics/{summary,mann_whitney_u}.rb
+│                │  min/p50/p95/max; Mann-Whitney U for regression significance
+└───────┬────────┘
+        │  Summary structs
+        ▼
+┌──────────────────┐
+│  Fingerprints    │  fingerprints/{components,workload_definition,compatibility}.rb
+│                  │  Environment + workload hashes; compatibility gate that blocks
+│                  │  incomparable runs before any metric decision is made
+└────────┬─────────┘
+         │  FingerprintResult
+         ▼
+┌──────────────────────┐
+│  Comparison::Engine  │  comparison/{engine,workload_comparison,metric_decision,
+│                      │  statistical_metric_decision,deterministic_metric_decision,
+│                      │  diagnostics}.rb
+│                      │
+│  Per-metric:         │  Duration/allocations → statistical (Mann-Whitney + floor)
+│                      │  SQL count            → deterministic (exact delta)
+│                      │  GC                   → informational only
+└──────────┬───────────┘
+           │  ComparisonResult
+           ▼
+┌──────────────────┐
+│  Policy::Engine  │  policy/engine.rb
+│                  │  Maps workload-level PASS/WARN/FAIL/INCOMPARABLE →
+│                  │  overall status + exit code (0–5 per spec §21)
+└──────────┬───────┘
+           │  PolicyResult (status, exit_code)
+           ▼
+┌──────────────────┐
+│  Report          │  report/{console,markdown}.rb
+│                  │  Human-readable console table or GitHub-flavored Markdown
+└──────────┬───────┘
+           │  String
+           ▼
+        stdout / summary.md
+
+────────────────────────────────────────────────────────
+Cross-cutting concerns (not in the pipeline)
+────────────────────────────────────────────────────────
+
+Config          config/{schema,validator,defaults,env_overrides}.rb
+                Single Config object loaded once; env vars layer on top of YAML.
+
+Storage         storage/{adapter,filesystem,archive}.rb
+                Filesystem adapter writes versioned JSON bundles.
+                import/export_archive produce .tar.gz for CI artifact hand-off.
+
+Serialization   serialization/run_result.rb
+                RunResult ↔ JSON; forwards-compatible with schema versioning.
+
+CLI             cli/{run_command,compare_command,run_comparison_reporter}.rb
+                Thin dispatcher; each subcommand is a callable object.
+                `baseline run --compare PATH --format markdown` is the canonical
+                one-step CI command.
+
+Errors          errors.rb
+                Typed error hierarchy; CLI maps each class to an exit code.
+```
+
+## Key design decisions
+
+**Subprocess isolation.** Each workload runs in a forked child process (or a
+fresh subprocess when fork is unavailable). This prevents metric leakage between
+workloads and matches the Rails parallel-test-runner constraint that SQLite
+requires a file-backed database.
+
+**Fingerprint-first.** Compatibility is checked before any metric comparison. If
+the environment fingerprint is incompatible the whole comparison is INCOMPARABLE;
+if an individual workload's definition changed it is flagged as modified. This
+prevents silent comparisons across incompatible runs.
+
+**Two comparison strategies.** Continuous metrics (duration, allocations) use
+Mann-Whitney U so random OS noise does not produce false alarms. SQL query count
+is deterministic — it should not vary between runs on the same code, so any
+change is significant.
+
+**Practical floor beats statistics alone.** A statistically-significant
+difference that is smaller than `minimum_absolute_ms` (default 10 ms) is
+downgraded from FAIL to WARN. A sub-noise-ratio change is downgraded further
+to PASS. This prevents microscopic regressions from blocking PRs.
+
+**One source of truth for thresholds.** `baseline.yml` controls every
+comparison and policy knob. Environment variables may override values for CI
+parameterisation but cannot introduce new keys.
+
+## Adding a new metric
+
+1. Add a collector in `instrumentation/` that captures `before`/`after` values
+   and returns a delta in `SampleContext`.
+2. Register it in `Instrumentation` and add it to `RunResult`'s schema.
+3. Choose a comparison strategy (statistical or deterministic) and add a rule
+   to `Comparison::Engine`.
+4. Add a policy threshold key to `Config::Schema` with a safe default that
+   makes the metric informational-only until the user opts in.
+5. Update `Report::Console` and `Report::Markdown` to surface it.

data/docs/compatibility.md

@@ -0,0 +1,49 @@
+# Compatibility Matrix
+
+Baseline's target support matrix, per the technical specification
+(section 23):
+
+| Component        | Target                                  |
+| ----------------- | ---------------------------------------- |
+| Ruby              | 3.2, 3.3, 3.4                            |
+| Rails              | 7.1, 7.2, 8.0                            |
+| RSpec Core         | 3.12+                                    |
+| Database           | PostgreSQL and MySQL, via Active Record  |
+| CI runner          | Linux (GitHub Actions)                   |
+| Local development  | macOS, best-effort                       |
+| Windows            | Not supported in the MVP                 |
+
+## What this repository's own CI currently exercises
+
+This is a gap to close before a public release, not a promise already
+kept. As of Milestone 5, this repository's own test suite
+(`.github/workflows/ruby.yml`) only runs:
+
+- Ruby 3.2.2
+- ActiveRecord 7.1 + SQLite (used by the SQL instrumentation specs,
+  which exercise real `ActiveSupport::Notifications` events rather
+  than stubs)
+- No MySQL, no PostgreSQL, no Rails 7.2/8.0, no Ruby 3.3/3.4
+
+Closing this gap means:
+
+- adding a Ruby version matrix (3.2, 3.3, 3.4) to the CI workflow;
+- adding a Rails version matrix (7.1, 7.2, 8.0) via Appraisal or a
+  similar Gemfile-matrix approach;
+- adding a PostgreSQL and a MySQL service to CI and running the SQL
+  instrumentation specs against both, not just SQLite;
+- verifying `perfgate doctor` (once implemented) correctly classifies
+  any of the above outside this matrix as incompatible rather than
+  silently comparing.
+
+## Fingerprint compatibility, not just supported versions
+
+Being in the target matrix is necessary but not sufficient for two
+runs to be compared. `Fingerprints::Compatibility` (Milestone 3) is
+the actual gate: it compares Ruby engine/version, Rails version,
+Baseline's own major version, database adapter/version, and the
+workload's own definition and dataset hashes, and marks a comparison
+`incompatible` if any of the "strict" fields differ. The matrix above
+describes what Baseline is *tested against* -- the fingerprint
+mechanism is what protects a specific comparison from ever silently
+running across incompatible environments.

data/docs/launch-article.md

@@ -0,0 +1,97 @@
+# Introducing Baseline: a CI-native performance gate for Rails, built on RSpec
+
+*Draft launch article. Adjust tone, add real screenshots/output, and
+link a public repository before publishing.*
+
+## The problem
+
+Most Rails teams find out about a performance regression one of two
+ways: a customer complains, or an on-call engineer gets paged. Load
+testing exists, but it's usually a separate, heavyweight process that
+runs occasionally, not on every pull request. The result is that a
+change that quietly adds an N+1 query, or turns a fast endpoint into a
+slow one, often ships and sits in production for weeks before anyone
+notices.
+
+Meanwhile, your team already writes RSpec examples that exercise the
+exact code paths that matter -- the checkout flow, the search endpoint,
+the background job that processes an order. Those examples know how to
+set up the right data and call the right code. What they don't do is
+tell you whether that code got slower.
+
+## What Baseline does
+
+Baseline turns selected RSpec examples into repeatable performance
+workloads. It runs each one several times in an isolated process,
+measures wall-clock duration, SQL query count and duration, and object
+allocations, and produces a versioned result bundle. On a pull request,
+it compares that bundle against a result from your default branch and
+answers one question:
+
+> Did this change introduce a material, reproducible performance
+> regression?
+
+The answer comes back as a clear PASS, WARN, or FAIL, with a
+console summary and a Markdown report explaining *why*:
+
+```text
+Baseline Performance Assurance
+
+Overall: FAIL
+Baseline: main@1a2b3c4
+Candidate: feature/checkout@9d8e7f6
+
+✗ checkout.create_order
+  Duration       281 ms → 337 ms   +19.9%   FAIL
+  SQL queries         14 → 19      +5       FAIL
+  SQL duration      51 ms → 73 ms  +43.1%   FAIL
+  Allocations      18.4k → 19.1k   +3.8%    PASS
+
+Likely signal:
+  SQL query count increased by 5.
+
+Compatibility: compatible
+Samples: 8 baseline / 8 candidate
+```
+
+## Why not just look at duration?
+
+Wall-clock duration on a shared CI runner is noisy. Two runs of
+identical code can easily differ by 10-20% just from scheduling noise.
+Baseline treats duration as one signal among several, downgrades
+low-confidence results instead of crying wolf, and refuses to compare
+runs from environments it isn't confident are equivalent -- a different
+Ruby or Rails version, a changed workload definition, or an
+incompatible dataset all mark a comparison `incompatible` rather than
+silently producing a misleading result.
+
+## Built for CI, not a hosted product
+
+There's no account to create and no dashboard to log into. Baseline
+stores its result bundles as plain, versioned JSON on your own
+filesystem or CI artifact storage. A documented GitHub Actions workflow
+downloads your default branch's last result, runs your workloads, and
+publishes a job summary -- all with `GITHUB_TOKEN`, no third-party
+service in the loop.
+
+## Try it
+
+```ruby
+# Gemfile
+gem "perfgate", group: :test
+```
+
+Tag an existing request spec or job spec with `baseline: true`, wrap the
+part you care about in `Perfgate.measure { ... }`, and you have your
+first workload. See
+[docs/onboarding.md](onboarding.md) for a full walkthrough, including
+wiring up the GitHub Actions workflow.
+
+## Where this is going
+
+Baseline is early. The MVP focuses on Rails + RSpec, GitHub Actions,
+and a conservative, explainable comparison engine over a broad feature
+set. We'd rather earn trust on a narrow surface than ship something
+that produces confusing or noisy results. If you try it and hit a
+false positive, a confusing report, or a missing feature, please open
+an issue -- that feedback is exactly what shapes the next milestone.

data/docs/onboarding.md

@@ -0,0 +1,122 @@
+# Design-Partner Onboarding Guide
+
+This is the walkthrough for an early adopter team installing Baseline
+for the first time, aimed squarely at Milestone 5's exit criterion:
+completing installation without the maintainer touching your repo.
+
+It reflects what's actually implemented today. `perfgate init`,
+`report`, `doctor`, and `schema` are not built yet -- everything below
+uses only `perfgate run` and `perfgate compare`.
+
+## 1. Add the gem
+
+```ruby
+# Gemfile
+gem "perfgate", path: "../baseline", group: :test # or a git ref, until published
+```
+
+```bash
+bundle install
+```
+
+No `baseline.yml` is required to get started -- a missing config file
+is treated as pure defaults (8 samples, 2 warmup iterations, all
+metrics enabled). Add one later once you want to tune thresholds or
+policy.
+
+## 2. Tag your first workload
+
+Pick one existing request spec, job spec, or similar RSpec example
+that exercises a code path you care about. Add `baseline: true` to its
+metadata, and wrap only the part you want measured in
+`Perfgate.measure`:
+
+```ruby
+RSpec.describe "Checkout", type: :request, baseline: true do
+  it "creates an order" do
+    sign_in(create(:user))
+    cart = create(:cart, :with_line_items)
+
+    Perfgate.measure do
+      post "/checkout", params: { cart_id: cart.id }
+    end
+
+    expect(response).to have_http_status(:created)
+  end
+end
+```
+
+Only code inside `Perfgate.measure` is timed and has its SQL/allocation
+metrics collected -- sign-in, fixture creation, and response assertions
+outside the block are excluded on purpose (spec section 9.3).
+
+See [examples/rails-rspec-app/spec/requests/checkout_spec.rb](../examples/rails-rspec-app/spec/requests/checkout_spec.rb)
+and [.../spec/jobs/invoice_job_spec.rb](../examples/rails-rspec-app/spec/jobs/invoice_job_spec.rb)
+for a request-spec and a job-spec example side by side.
+
+## 3. Run it locally
+
+```bash
+bundle exec baseline run --output .baseline/current
+```
+
+This discovers every `baseline: true`-tagged example, runs its warmup
++ samples in an isolated process, and writes a versioned result bundle
+to `.baseline/current/runs/<run-id>/`.
+
+## 4. Compare two runs
+
+Run it again (ideally after making a change you'd expect to matter),
+then compare:
+
+```bash
+bundle exec baseline compare \
+  --baseline .baseline/current \
+  --candidate .baseline/new-run \
+  --output .baseline/comparisons
+```
+
+You'll get a console report with a PASS/WARN/FAIL decision per metric,
+an overall decision, and a nonzero exit code on FAIL -- see the report
+format in the main [README](../README.md#usage).
+
+## 5. Wire up CI
+
+Copy [examples/rails-rspec-app/.github/workflows/baseline.yml](../examples/rails-rspec-app/.github/workflows/baseline.yml)
+into `.github/workflows/` in your repository. It:
+
+1. downloads the last `baseline-main` artifact (if one exists yet);
+2. runs `baseline run --compare .baseline/reference --format markdown`,
+   which runs your workloads and compares them in one step;
+3. publishes the resulting `summary.md` to the GitHub job summary;
+4. re-uploads the artifact when building `main`, so the next PR has
+   something to compare against.
+
+The very first run on a repository will have nothing to compare
+against yet -- `baseline run --compare` detects the missing baseline
+and reports it as a warning rather than failing the build. After the
+first successful `main` build, every subsequent PR compares against
+it.
+
+## 6. Reading your first result
+
+- **PASS**: no metric regressed beyond its configured threshold with
+  statistical confidence. Merge as usual.
+- **WARN**: something changed, but not enough to be treated as a
+  blocking regression (e.g. a metric moved but wasn't statistically
+  significant, or the workload/environment changed in a way the
+  default policy doesn't block on). Worth a look, not a blocker.
+- **FAIL**: a metric both changed by more than its practical threshold
+  *and* is statistically significant given the sample noise. The
+  console/Markdown report's "Likely signal" line names the most
+  probable contributing metric (e.g. "SQL query count increased by
+  5") -- it's a deterministic hint, not a root-cause diagnosis.
+
+## Getting help
+
+If something doesn't work as described here, or the report doesn't
+make sense, please open an issue (see
+[CONTRIBUTING.md](../CONTRIBUTING.md)) rather than working around it
+silently -- unclear reports and rough edges in exactly this kind of
+first-run experience are the most valuable thing for us to hear about
+right now.

data/docs/telemetry.md

@@ -0,0 +1,81 @@
+# Telemetry Specification
+
+Baseline collects **no telemetry by default**. This document specifies
+the opt-in telemetry payload as designed in the technical specification
+(section 22), so that anyone considering enabling it -- or auditing
+whether Baseline is safe to run in a sensitive environment -- can see
+exactly what would be sent and what never would be, before any
+transmission code exists.
+
+## Current status
+
+As of this release, telemetry is **not implemented**. The
+`telemetry.enabled` configuration key exists and defaults to `false`
+(see `lib/baseline/config/defaults.rb`), but no code path currently
+reads it to make a network request. This document describes the
+contract that any future telemetry implementation must honor.
+
+## Opt-in only
+
+- Telemetry is off unless a user explicitly sets `telemetry.enabled:
+  true` in `baseline.yml`, or an equivalent explicit environment
+  override.
+- There is no implicit opt-in through usage, installation, or CI
+  execution.
+- Baseline must function identically, with no missing features and no
+  degraded behavior, whether telemetry is enabled or not.
+- A telemetry send failure (network error, timeout, malformed
+  response) must never affect Baseline's exit code, comparison result,
+  or CLI output. Telemetry is best-effort and fire-and-forget.
+
+## Permitted payload fields
+
+If enabled, a telemetry event may only ever contain:
+
+- Baseline version
+- Ruby version
+- Rails version
+- RSpec version
+- operating system
+- CI provider
+- number of workloads
+- enabled metric names
+- command success/failure category
+- an anonymous installation ID (randomly generated, not derived from
+  any repository or organization identifier)
+
+## Never transmitted, under any configuration
+
+- repository name or URL
+- organization name
+- source file names
+- workload names
+- metric *values* (durations, SQL counts, allocation counts, etc.)
+- SQL text or bind values
+- environment variable values
+- commit SHA
+- IP-derived geolocation, beyond whatever is inherent to receiving an
+  HTTP request (Baseline itself never resolves or stores this)
+
+## Why this split
+
+The permitted fields are enough to answer aggregate product questions
+("which Ruby/Rails versions are people actually running Baseline
+against?", "does the CLI usually succeed or fail?") without being able
+to reconstruct anything about a specific codebase, its performance
+characteristics, or its data. This mirrors the broader security and
+privacy requirements in spec section 22: no source code leaves the
+process, and no mandatory network requests exist regardless of the
+telemetry setting.
+
+## Implementing telemetry (future work)
+
+When telemetry transmission is implemented, it must:
+
+1. Be added behind the existing `telemetry.enabled` flag, defaulting
+   to `false`.
+2. Serialize only the permitted fields above, ideally validated by a
+   JSON schema the way run/comparison results already are.
+3. Fail silently (log at most, never raise) on any transmission error.
+4. Be documented in this file, including the exact endpoint and
+   retention policy, before it ships in a release.

data/examples/rails-rspec-app/.github/workflows/baseline.yml

@@ -0,0 +1,48 @@
+name: Baseline
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  baseline:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      # The MVP has no artifact-lookup helper (spec 19.1), so this just
+      # grabs whatever the main branch's most recent workflow run
+      # uploaded under this fixed artifact name. continue-on-error
+      # covers the very first run on a repository, where no such
+      # artifact exists yet -- baseline run then falls back to treating
+      # the comparison as a missing baseline instead of failing.
+      - name: Download default-branch Baseline
+        if: github.event_name == 'pull_request'
+        uses: actions/download-artifact@v4
+        with:
+          name: baseline-main
+          path: .baseline/reference
+        continue-on-error: true
+
+      - name: Run Baseline
+        run: |
+          bundle exec baseline run \
+            --output .baseline/current \
+            --compare .baseline/reference \
+            --format markdown
+
+      - name: Publish summary
+        if: always()
+        run: cat .baseline/current/summary.md >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Upload default-branch Baseline
+        if: github.ref == 'refs/heads/main'
+        uses: actions/upload-artifact@v4
+        with:
+          name: baseline-main
+          path: .baseline/current

data/examples/rails-rspec-app/README.md

@@ -0,0 +1,38 @@
+# Example Rails + RSpec App
+
+Placeholder for the example Rails application used to demonstrate and
+integration-test Baseline (see section 8 and Prompt 2 of the technical
+specification). The full app is not yet scaffolded.
+
+`spec/requests/checkout_spec.rb` and `spec/jobs/invoice_job_spec.rb`
+are illustrative workload examples (Milestone 2 deliverables: a
+request-spec example and a job-spec example, spec section 13.7). They
+show the intended `baseline:`-tagged, `Perfgate.measure`-wrapped shape
+once a real Rails app backs this directory; they are not executed by
+CI yet since there's no app for them to run against.
+
+## CI usage
+
+`.github/workflows/baseline.yml` reproduces the conceptual workflow
+from spec section 19.1: it downloads whatever `baseline-main` artifact
+the last successful main-branch build published, runs the current
+branch's workloads and compares them against it in one step (`baseline
+run --output .baseline/current --compare .baseline/reference --format
+markdown`), publishes the resulting `summary.md` to the job summary,
+and re-uploads the artifact when building main itself.
+
+This is deliberately the MVP-level version the spec calls for:
+
+- No GitHub App or API-based artifact lookup -- just the fixed
+  `baseline-main` artifact name via `actions/download-artifact`.
+  `continue-on-error: true` covers the very first run, before any such
+  artifact exists; `baseline run --compare` then reports a missing
+  baseline instead of crashing.
+- No provenance checking (spec 19.3) beyond what
+  `actions/download-artifact` already gives you for free -- there's no
+  verification here that the artifact came from a successful run, the
+  configured default branch, or a commit at or before the PR's base.
+  A real deployment should tighten this with a small composite action
+  once one exists.
+- Job summary only (spec 19.2); no sticky PR comment or check
+  annotation yet.

data/examples/rails-rspec-app/spec/jobs/invoice_job_spec.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+# Illustrative job-spec workload (spec section 13.7): explicit in-process
+# job execution, with per-example overrides of the default sample/warmup
+# counts (spec section 9.3) for a more expensive workload. See the note
+# in ../requests/checkout_spec.rb about this file's placeholder status.
+RSpec.describe InvoiceJob, type: :job, perfgate: { samples: 5, warmup: 1 } do
+  it "generates an invoice for a completed order" do
+    order = create(:order, :completed, line_item_count: 50)
+
+    Perfgate.measure { described_class.perform_now(order.id) }
+
+    expect(order.reload.invoice).to be_present
+  end
+end

data/examples/rails-rspec-app/spec/requests/checkout_spec.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Illustrative request-spec workload (spec sections 9.1 and 13.7). This
+# file is not currently run by CI: examples/rails-rspec-app is a
+# placeholder until a real Rails app is scaffolded (see the top-level
+# README in this directory). It shows the intended shape of a
+# request-spec workload once that app exists.
+#
+# `baseline: true` opts the example into measurement with the project's
+# default samples/warmup/metrics (spec section 9.3). `Perfgate.measure`
+# scopes SQL/allocation/GC collection to exactly the request under test,
+# excluding sign-in, fixture setup, and response-body assertions.
+RSpec.describe "Checkout", type: :request, baseline: true do
+  it "creates an order" do
+    sign_in(create(:user))
+    cart = create(:cart, :with_line_items)
+
+    Perfgate.measure do
+      post "/checkout", params: { cart_id: cart.id }
+    end
+
+    expect(response).to have_http_status(:created)
+  end
+end