Add deployment phase and Traefik compose override

Insert a new Phase 1 (deployment: Compose + Traefik on a server, marked
Done) between the base project and the OTel concepts phase, and shift
the old phases 1-10 to 2-11. Update summary, intro, README and CLAUDE.md
references (spoiler rules now target Phase 9, the bottleneck hunt).

Add docker-compose.traefik.yml: an override that fronts the gateway with
Traefik and Let's Encrypt and removes all other published host ports.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

docs/roadmap/phase-7.md

@@ -1,91 +1,94 @@
-# Phase 7 — SLI, SLO, SLA, error budgets, RTO, RPO
+# Phase 7 — Load testing with k6, and percentiles
 
 *Part of `docs/roadmap/` — see [`intro.md`](intro.md) for platform/background context and [`summary.md`](summary.md) for how every phase fits together. Prev: [`phase-6.md`](phase-6.md) · Next: [`phase-8.md`](phase-8.md)*
 
 **Status:** Not started
 
-**Message:** Depends on Phase 6's load-test baseline (the latency SLO should
-come from measured numbers, not be picked from thin air).
+**Message:** Depends on Phase 5 (metrics to plot k6's output against) and
+benefits from Phase 6's dashboards existing.
 
-**Time-box:** 1–2 evenings. Mostly thinking, a little config.
+**Time-box:** 1–2 evenings.
 
-### Concepts
+### Concepts — P95 and P99 properly
 
-- **SLI** — a *measurement* of something users experience, expressed as a ratio of
-  good events to valid events. Not "CPU is at 60%". Rather: *the proportion of
-  `POST /api/transactions` requests that returned 2xx within 500 ms.*
-- **SLO** — an internal *target* on an SLI over a window. "99.5% of transaction
-  requests succeed within 500 ms, measured over a rolling 28 days."
-- **SLA** — an external, *contractual* promise, with consequences (refunds, credits).
-  Always **looser** than your SLO, so you have room to miss internally without
-  breaching commercially. If your SLA and SLO are the same number, you've made a
-  mistake.
-- **Error budget** — `1 − SLO`, expressed as an allowance. A 99.9% SLO gives a 0.1%
-  budget; over 30 days that's about **43 minutes**. The budget is the thing that
-  turns reliability from an argument into arithmetic: if there's budget left, ship
-  features and take risks; if it's spent, the policy says you stop feature work and
-  spend on reliability. That policy — agreed in advance by dev, ops and product — is
-  the whole point.
-- **Burn rate.** How fast you're consuming budget relative to the window.
-  Burn rate 1 = you'll exactly exhaust the budget at window end. The SRE Workbook's
-  multi-window, multi-burn-rate alerting (fast burn → page; slow burn → ticket)
-  is what stops you from either paging on every blip or noticing the slow bleed a
-  month late.
-- **RTO / RPO** — these are *disaster recovery* metrics, a different axis from SLOs,
-  and it's worth being precise because interviewers probe exactly here.
-  - **RTO (Recovery Time Objective)** — the maximum acceptable *downtime*: how long
-    from failure to restored service. It drives your architecture: replication,
-    warm standby, failover automation, runbook quality.
-  - **RPO (Recovery Point Objective)** — the maximum acceptable *data loss*, measured
-    in time: how far back can you afford to lose. It drives your **backup and
-    replication frequency**. RPO of 15 minutes means backups/WAL shipping at least
-    every 15 minutes.
-  - The relationship worth stating out loud: **SLO governs steady-state quality; RTO
-    and RPO govern catastrophe.** An SLO says "99.5% of requests are fast." RTO says
-    "if Postgres dies we're back within 30 minutes." RPO says "and we lose at most
-    5 minutes of transactions." Both feed the SLA.
-  - Both are **business decisions, not technical ones** — you derive them by asking
-    what an hour of downtime or an hour of lost data actually costs, then buying the
-    cheapest architecture that meets it. Tightening either is expensive and
-    non-linear.
+You asked about these specifically, and there's more to them than "the 95th
+percentile."
+
+- **A percentile is meaningless without a population and a window.** "p95 = 400 ms"
+  is not a fact; "p95 of `POST /api/transactions` over the last 5 minutes = 400 ms"
+  is.
+- **You cannot average percentiles.** Not across instances, not across time buckets.
+  `avg(p99)` is wrong and produces a number that looks plausible. The correct move is
+  to aggregate the *histogram buckets* and compute the quantile from the sum:
+  `histogram_quantile(0.95, sum(rate(..._bucket[5m])) by (le))`.
+- **Prometheus classic histograms give you an interpolated estimate**, bounded by
+  your bucket edges. If your buckets jump 0.5 s → 1 s and everything lands in that
+  bucket, your "p99" is a linear guess inside a 500 ms range. Choose buckets that
+  bracket your actual SLO threshold. (Native histograms largely solve this and are
+  worth knowing about.)
+- **Which population?** An overall p99 across all endpoints is dominated by whichever
+  endpoint has the most traffic. Slice by route, or you'll miss that
+  `/api/accounts/{id}/insights` is catastrophic while the aggregate looks fine.
+- **Tail latency amplification** — the most important idea here for a microservice
+  system. If one user request fans out to 10 backend calls, each with an independent
+  p99 of 1 s, then the chance the *user request* touches at least one slow call is
+  `1 − 0.99¹⁰ ≈ 9.6%`. Your user-facing p99 is worse than any individual service's
+  p99. This is Dean & Barroso's *The Tail at Scale*, and it's why "each service is
+  fine" and "the product is slow" coexist. Ledgerline's fan-out makes this
+  measurable — go measure it.
+- **p99 vs p99.9:** the users in the deep tail are often your heaviest, most valuable,
+  most data-rich accounts. Ledgerline's five hot accounts are a stand-in for exactly
+  that.
+- **Coordinated omission** — a load-generator trap. If your generator waits for a
+  response before sending the next request, then when the system stalls, the
+  generator stalls too and simply *doesn't record* the requests that would have been
+  slow. Your measured latency is systematically optimistic. Fix: use an **open
+  model** — a fixed *arrival rate* independent of response times. In k6 that means
+  the `constant-arrival-rate` / `ramping-arrival-rate` executors rather than
+  `constant-vus`. Knowing this is a genuine senior-level differentiator.
+
+### Concepts — k6
+
+- **Test types:** smoke (does it work at all), average-load (normal traffic),
+  stress (past normal, find the knee), spike (sudden surge, test recovery),
+  soak (hours, find leaks and lag drift), breakpoint (ramp until failure).
+  Your `unbounded_cache` and `slow_consumer` pathologies are only visible in a soak.
+- **Executors:** closed model (`constant-vus`, `ramping-vus`) vs open model
+  (`constant-arrival-rate`, `ramping-arrival-rate`). See coordinated omission above.
+- **`checks` vs `thresholds`:** checks are assertions that record pass/fail but don't
+  fail the run; **thresholds are SLOs expressed in code and they set the process exit
+  code**, which is what makes k6 a CI gate. `http_req_duration: ['p(95)<500']`.
+- **Output:** k6 can remote-write its own metrics to Prometheus, so the load test's
+  view and the application's view sit on the same Grafana time axis. That side-by-side
+  is the single most convincing screenshot you can show Babak.
+- k6 tests are JavaScript/TypeScript, which is fine — you're not learning JS, you're
+  writing 60 lines of it.
 
 ### Resources
 
-- Google SRE Workbook → *Implementing SLOs* (the SLI menu by service type is
-  immediately usable), then *Alerting on SLOs*, then *Error Budget Policy*. Free.
-- Google SRE — *The Art of SLOs*: slides plus participant and facilitator handbooks,
-  all free PDFs. Run the exercises solo with Ledgerline as the subject.
-- Optional: Coursera *Measuring and Managing Reliability* (Google Cloud) — auditable
-  free, self-paced, deeper.
-- For RTO/RPO: Splunk's *RPO vs RTO* explainer is a clean, vendor-neutral-enough
-  overview; pair it with your Postgres backup knowledge.
+- Grafana k6 docs → *Get started*, *Test types*, *Scenarios & executors*,
+  *Thresholds*. Free, genuinely well written; ~2 h to work through.
+- Grafana workshop — *Introduction to Performance Testing with Grafana k6* (free,
+  hands-on).
+- Udemy backbone (Aref Karimi's course) has a k6 section if you took that one.
+- Grafana docs → *k6 output to Prometheus remote write*.
 
 ### Build
 
-1. Write `docs/SLO.md`. For Ledgerline define, with justification:
-   - Availability SLI/SLO on `POST /api/transactions`
-   - Latency SLI/SLO on the same (pick the threshold from your Phase 6 baseline, not
-     from thin air)
-   - A freshness/lag SLI on the notifier consumer group
-   - A stated SLA that is deliberately looser than each SLO
-   - An RTO and RPO for the Postgres instance, with the backup cadence they imply
-   - An error budget policy: what happens at 50%, 75% and 100% consumed
-2. Implement recording rules for the SLIs and **multi-burn-rate alert rules**.
-   Your platform ships **Alertmanager** plus a Prometheus rules directory and the
-   sample rules `HostExporterDown` and `HostHighCPU`, so the grain is
-   *Prometheus rule files → Alertmanager*, templated by the Ansible role, with
-   `alertmanager_webhook_url` in `group_vars` for delivery. Follow the grain — but
-   be able to argue the alternative: Grafana unified alerting can evaluate across
-   datasources (including Loki queries) and lives with your dashboards, whereas
-   Alertmanager is metrics-only but is the ecosystem standard and gives you
-   grouping, deduplication, inhibition and silences for free. Note which you chose
-   and why in `docs/SLO.md`.
-3. Add an error-budget panel to the overview dashboard: budget remaining, current
-   burn rate, projected exhaustion.
-4. Prove it: run `chaos-nightmare` under load until you visibly burn budget, and
-   watch the fast-burn alert fire.
+1. `loadtest/` with four scripts: `smoke.js`, `average.js`, `stress.js`, `soak.js`,
+   sharing a `common.js` for setup and payload generation against random accounts.
+2. Use **arrival-rate executors** for `average` and `stress`. Write down why.
+3. Thresholds encoding your intended SLOs: `p(95)<500`, `p(99)<2000`,
+   `http_req_failed rate<0.01`.
+4. Pipe k6 metrics into Prometheus; add a k6 row to your overview dashboard.
+5. Run the same profile under `chaos-clean` and `chaos-nightmare`. Save both result
+   sets. This before/after pair is your baseline for Phase 9.
+6. Optional but impressive: have k6 send W3C trace context headers so load-test
+   requests appear as traces, letting you click from a k6 spike into a specific
+   trace. Check the current k6 docs for the tracing module's status — it has moved
+   between experimental and stable.
 
-**Done when:** you can explain, in one paragraph each and without notes, the
-difference between SLI/SLO/SLA, between SLO and RTO, and why RPO is a backup-schedule
-decision.
+**Done when:** `make load-stress` produces a Grafana view where you can see the
+arrival rate climb, p95 diverge from p50, error rate turn up, and you can name the
+service that broke first.