feat(samples): measurable, production-realistic sample with a control group

[FranRuiz98]

Turns the sample from something that demonstrates the library into something that measures it, and makes it impossible to rot.

Why

The sample worked, but it had three problems:

• It could not measure anything. There was no control group, so "caching helps" was an assertion, not a number.
• Several features were invisible. /greetings existed but nothing ever called it, so v2.2.0's headline Vary support was never exercised. Per-request policies, CoalesceKeyHeaders, only-if-cached, immutable and the size ceiling had no demonstration at all.
• Nothing built it. The sample projects were not in Stampede.Http.slnx and no CI job touched them, so they could stop compiling — or stop working — silently.

What changed

Measurement

• client-baseline: the same image, workload and Polly pipeline with Sample:Pipeline:Enabled=false, which removes the two Stampede.Http handlers and nothing else.
• The origin now exports Prometheus metrics, counting every request that actually reached it, tagged by endpoint and by the X-Client header the clients send. The with/without comparison is one PromQL query.
• The Grafana dashboard is rebuilt around that: origin req/s per client, origin load avoided as a percentage, and a per-endpoint breakdown — plus caching and coalescing sections keyed on a client label rather than the scrape instance.

Feature coverage

A narrated feature tour: 12 scenarios, each verified against the origin's own request counters rather than the client's opinion of what happened. Covers Vary variants, CoalesceKeyHeaders, conditional pass-through, ForceRevalidate / BypassCache / NoStore / BypassCoalescing, only-if-cached, immutable, MaxBodySizeBytes, NormalizeQueryParameters and Last-Modified revalidation. The origin gains the endpoints those need (/tenants/data, /assets/{id}, /ledger, /docs/{id}, /bulk, /search, /health, POST /stats/reset).

Realism

• The client goes from a console script to an ASP.NET Core service: typed client, IOptions with validation, ILogger, endpoints under /api so load can be driven by real inbound HTTP, IHostedService with graceful shutdown.
• /metrics is served on the application port, which removes the HttpListener host-binding workaround the old side-channel exporter needed (METRICS__HOST and its long explanatory comment are gone).
• k6 profile driving identical arrival patterns at both pipelines.
• OTLP traces + Jaeger: a coalesced burst is one outgoing span, which no counter can show.
• config/ bind-mounted with reloadOnChange to demonstrate IOptionsMonitor, plus GET /api/config to read the effective options.

Hygiene

• Both sample projects added to Stampede.Http.slnx, so CI compiles them.
• scripts/smoke-test.sh and a CI job that brings the whole stack up and asserts what the README claims.
• Real healthchecks and depends_on conditions instead of a 30-attempt retry loop.
• *.sh / Dockerfile / *.yml pinned to LF in .gitattributes — a CRLF shell script fails in a Linux container.
• The root README links the sample, which it never mentioned.

Things found by actually running it

Three of these were only visible once the stack was up, and each is fixed in place:

1. The coalescer's MaxResponseBodyBytes fires before the cache's MaxBodySizeBytes, and throws. The /bulk scenario killed the process. The two ceilings fail differently — the cache declines silently, the coalescer throws for every waiter — so the sample now sets the coalescer's limit above the cache's, with a comment explaining why.
2. Grafana silently ignored dashboard edits. The JSON pinned "version": 2, and the file provisioner skips a provisioned dashboard whose version has not increased. Removed.
3. The "deduplicated requests" panel sat at zero forever. The metric was correct; the workload was not. Phase 3 issued its probes sequentially, so no two requests overlapped and the coalescer correctly had nothing to do. Added a burst of 8 concurrent GET /slow every 5 iterations. It targets /slow, which is excluded from the comparison selector, so the headline percentage stays a floor rather than a figure inflated by choosing favourable traffic.

For reviewers

The headline "origin load avoided" reads about 40%, and the README now spends a section explaining why that number is honest but pessimistic rather than just printing it:

• /flaky accounts for most of what is not avoided, because a failure cannot be cached ahead of time — stale-if-error rescues the caller after the origin has failed.
• The sample runs 5–10 s TTLs against a ~3 s poll so expiry is visible in a 90-second demo. The ceiling is 1 − interval / max-age; /catalog and /feed land within a few points of it.
• The per-client normalisation hides the best result: because client-a and client-b share one Redis cache they share the refresh work, so together they cost the origin less than the single uncached client on /catalog and /feed. On /flaky the opposite holds — uncacheable failures scale with replica count.
• On /slow, where the burst lands, the saving is ~95% (0.30 req/s at the origin for the control client vs 0.00–0.02 with the library).

No library code changed — this is entirely samples/, plus the solution file, CI, .gitattributes and a link from the root README.

Verification

• 343 tests pass; solution builds warning-free.
• scripts/smoke-test.sh green from a clean stack: feature tour 12/12, a 20-caller burst costs 0 origin calls against the control client's 28.
• k6 run completes: p95 1.37 ms against the Stampede.Http client.
• Prometheus scraping all four targets; Jaeger receiving from sample-api and sample-client; hot reload confirmed end to end.