nordisk/dwarves

status badge — design

Class: design · Function axis: f0 the badge feature (the whole) · f1 the pure renderer (brokkr::badge) · f2 the latest-run selector · f3 the Badge gRPC RPC · f4 the dwarves badge CLI verb (fat + thin) Strict: this file states only what the status badge IS — its parts and why they are shaped this way. Sibling how-to: status-badge-guide.md; zero-knowledge walkthrough: status-badge-for-idiots.md.

A status badge is the shields-style pill (⟨ pipeline │ passing ⟩) a README or dashboard <img>s to show a pipeline's health at a glance. dwarves already carried the renderer — brokkr::badge::svg — but it was orphaned: reachable only from its own unit test, wired to no CLI verb and no RPC. The parity spec flagged this twice (D2: "badge still pending its RPC"; D1 wishlist: Badge "remains open"). This feature closes both by making the primitive reachable fat (the local warehouse) and thin (over gRPC) through one shared renderer.

The system as one — the function map (f0)

Why it is shaped this way

• One renderer, both paths (Law #1). The SVG is produced by exactly one function, brokkr::badge::svg. The fat CLI, the thin CLI's optional --label re-render, and the server handler all call it — so a badge fetched over the wire is byte-identical to one rendered locally. No twin SVG string anywhere.
• A pure selector, testable in isolation. latest_status takes a &[PipelineRunRow] and returns the newest match's status. It knows nothing of files or gRPC, so its "newest wins / project filter / cold-start None" contract is asserted with a plain vec (red-when-broken), and both the server and the fat CLI feed it the rows they already read with store::read_runs.
• A badge never 404s. An unrecorded pipeline is not an error — it renders a grey "unknown" pill (found=false). Only an empty pipeline name is a hard InvalidArgument. This matches how shields.io behaves and means a README <img> never breaks while a pipeline is still cold.
• Every status has its own colour (additive correctness fix). The renderer now maps passed→green, running→amber, skipped→grey, failed→red, none→grey. Before, any non-green mapped to red — a still-running build read as "failing". The distinct arms fix that without changing the passed/failed/none colours the existing test pins, so no consumer (there were none) regresses.
• The exit code doubles as a gate. dwarves badge prints the SVG regardless, but exits 0 iff the latest run is green, 1 on a recorded non-green, 2 when no run exists — so the same verb is a scriptable latest-run status check, not only a renderer.
• Additive + gated. The renderer/selector live in the always-compiled brokkr module (no feature). The Badge RPC + thin_badge client compile only under --features server (the proto codegen + tonic), exactly like every other RPC; the fat verb needs neither. nornir's lean path-dep and the published forge pull nothing new.

Place in the nordisk constellation

The badge is a dwarves-owned forge surface (the CI half of the parity map). It reads dwarves' own historized runs (store::read_runs, the JSONL/Iceberg-shaped ledger) — no nornir dependency, no warehouse of its own beyond the run history it already keeps. A future nornir/holger dashboard embeds the same SVG over the Badge RPC (thin gRPC), the same cross-app pattern as nornir-funnel-embed.

Deferred

• No UI pane for the badge. The badge is a CLI + RPC surface; it is not yet mounted as an egui atom in dwarves-gui (so no robot row — the L4 obligation here is met by the pure-fn + handler drive-and-assert tests + the dwarves::server / badge testmatrix cell). A small "badge preview" strip in the Pipeline pane is a later slice.
• running is best-effort. A badge reflects the newest run row; a run mid-flight historizes as running and badges amber, but dwarves' Phase-0 runs are synchronous so this is rarely observed. No live-progress polling.
• SVG/PDF regen (assets/*.svg is committed; docs/*.pdf) is left for the Loki bencher's nornir docs book render on push, consistent with prior entries.