@intentius/behold 0.17.0 → 0.19.0

package/web/behaviour-scale.js

@@ -0,0 +1,380 @@
+// The colour-by modes' arithmetic (#399 M2, #401 M4 of #397) — everything the
+// behaviour overlay DECIDES, with no DOM and no fetch in it, so it can be unit
+// tested beside the file the way web/theme.js is.
+//
+// The one rule the whole module exists to keep: behold states no figure of its
+// own. Every number below arrives from a `attrs._behaviour` block a lexicon's
+// engine wrote (src/behaviour.ts validates it against #398's contract), and
+// what happens here is positioning on an axis, a min, a median, and a count.
+// Where a figure IS computed here rather than read — the headroom min and
+// median a box's totals row shows — the label says "computed", because
+// `meta.behaviour` carries only cost sums and the engine stated no headroom
+// aggregate for behold to quote.
+import { hexToOklch, oklchToHex } from "./theme.js";
+
+const clamp = (x, lo, hi) => (x < lo ? lo : x > hi ? hi : x);
+
+/** The block a node carries, or undefined. One reader, so a rename is one edit. */
+export function blockOf(node) {
+  return (node && node.attrs && node.attrs._behaviour) || undefined;
+}
+
+/**
+ * Headroom, as the mode paints it: **the lower of the axes present**.
+ *
+ * A missing axis is absent, never 0 (#398) — "the engine did not report cpu"
+ * and "there is no cpu left" are opposite claims. So a block with only
+ * `latency` is read on latency alone, and a block whose `headroom` somehow
+ * carries neither is not a headroom figure at all (the M1 validator already
+ * refuses one, so this returns undefined rather than inventing a floor).
+ */
+export function headroomOf(block) {
+  if (!block || !block.headroom) return undefined;
+  const axes = [block.headroom.cpu, block.headroom.latency].filter((v) => typeof v === "number");
+  return axes.length ? Math.min(...axes) : undefined;
+}
+
+/** The figure the active mode reads off one block. `drift` reads none. */
+export function figureOf(mode, block) {
+  if (mode === "cost") return block && block.cost ? block.cost.perHour : undefined;
+  if (mode === "headroom") return headroomOf(block);
+  return undefined;
+}
+
+/**
+ * The domain a mode's scale spans, over the entities that carry a figure.
+ *
+ * `cost` has no absolute range — a per-hour figure means nothing until you know
+ * what the rest of the estate costs — so its domain is the estate's own min and
+ * max. `headroom` is already a fraction of capacity, so its domain is fixed at
+ * 0..1: half free is half free whether the estate is one box or forty, and
+ * stretching it to the observed range would make a comfortable estate's best
+ * card read as its worst.
+ */
+export function domainFor(mode, values) {
+  const xs = values.filter((v) => typeof v === "number" && Number.isFinite(v));
+  if (mode === "headroom") return { min: 0, max: 1, n: xs.length, absolute: true };
+  if (!xs.length) return null;
+  return { min: Math.min(...xs), max: Math.max(...xs), n: xs.length, absolute: false };
+}
+
+/** Where a figure sits on its domain, 0..1. A flat domain (every entity the
+ * same price) puts everything mid-scale rather than at an end — an end would
+ * claim a spread the figures do not have. */
+export function positionOf(value, domain) {
+  if (!domain || typeof value !== "number" || !Number.isFinite(value)) return undefined;
+  if (domain.max === domain.min) return 0.5;
+  return clamp((value - domain.min) / (domain.max - domain.min), 0, 1);
+}
+
+/**
+ * A colour at `t` on a ramp of anchor colours, interpolated in OKLCH so the
+ * steps read as even brightness rather than as even RGB arithmetic — the same
+ * space theme.js already does its perceptual work in.
+ */
+export function rampColor(t, stops) {
+  if (!stops.length) return "#888888";
+  if (stops.length === 1) return stops[0];
+  const x = clamp(t, 0, 1) * (stops.length - 1);
+  const i = Math.min(Math.floor(x), stops.length - 2);
+  const f = x - i;
+  const a = hexToOklch(stops[i]);
+  const b = hexToOklch(stops[i + 1]);
+  // Hue takes the short way round the wheel, or a green→red ramp would swing
+  // backwards through blue on a palette whose two anchors straddle 0°.
+  let dH = b.H - a.H;
+  if (dH > 180) dH -= 360;
+  if (dH < -180) dH += 360;
+  return oklchToHex({ L: a.L + (b.L - a.L) * f, C: a.C + (b.C - a.C) * f, H: (a.H + dH * f + 360) % 360 });
+}
+
+/**
+ * The two modes' ramps, DERIVED from the active theme the way #229 derives the
+ * chrome — no mode owns a fixed colour, and all 552 palettes have to come out
+ * of here with a scale you can read low from high.
+ *
+ * `cost` is a SINGLE-HUE ramp on the accent's own hue and chroma, walked in
+ * lightness away from the theme's background: quiet and close to the ground at
+ * the cheap end, full strength at the expensive one. Deliberately not a
+ * green-to-red ramp — expensive is not a verdict, and behold has no standing to
+ * paint an estate's bill as a fault. Magnitude is all the engine stated, so
+ * magnitude is all the colour says.
+ *
+ * Anchored to the BACKGROUND's lightness rather than to the accent's own, for
+ * the reason #229 pushes `--active` off the panel: a palette whose blue slot
+ * happens to sit where a fixed offset would land (Hot Dog Stand's, on a red
+ * ground) otherwise derives two ends you cannot tell apart. Walking outward
+ * from the ground gives every one of the 552 palettes a spread, and it is the
+ * spread, not the offset, that the scale is for.
+ *
+ * `headroom` IS a good-to-bad axis — #399 says so in as many words — so it
+ * rides the three status hues the drift overlay already anchors across every
+ * palette: degraded at no headroom, foreign in the middle, managed at plenty.
+ * The card's drift bar keeps its own colour underneath, so the two never occupy
+ * the same pixel. Where a palette paints red and green alike (Retro, Hot Dog
+ * Stand's mustard), the drift overlay reads alike there too — that is the
+ * palette's own choice and not a thing this scale may overrule.
+ */
+export function rampFor(mode, tokens) {
+  if (mode === "cost") {
+    const { C, H } = hexToOklch(tokens.pending);
+    const ground = hexToOklch(tokens.bg).L;
+    const away = ground < 0.5 ? 1 : -1;
+    // How far there is to walk before the walk runs out of sRGB. A ground
+    // sitting almost exactly mid-lightness (Grass) has barely half the room a
+    // near-black one does, so the span is what's actually available rather than
+    // a constant that silently clips at one end.
+    const room = away > 0 ? 0.95 - ground : ground - 0.05;
+    const span = Math.min(0.62, room);
+    return [atLightness(ground + away * span * 0.32, C * 0.35, H), atLightness(ground + away * span, C, H)];
+  }
+  if (mode === "headroom") return [tokens.degraded, tokens.foreign, tokens.managed];
+  return [];
+}
+
+/**
+ * The colour at a requested OKLCH lightness, with chroma eased off until the
+ * result actually LANDS there in sRGB.
+ *
+ * Without this a saturated hue near either end of the range clips on the way
+ * out, and the ramp's two ends come back closer together than they were asked
+ * to be — which on one palette (Grass, whose background sits within a
+ * thousandth of mid-lightness) collapsed the scale to two shades of the same
+ * navy. Lightness is the thing the eye reads a sequential scale by, so
+ * lightness is the thing that is honoured and chroma is the thing that gives.
+ */
+function atLightness(L, C, H) {
+  const want = clamp(L, 0.05, 0.95);
+  let c = C;
+  let out = oklchToHex({ L: want, C: c, H });
+  for (let i = 0; i < 10 && Math.abs(hexToOklch(out).L - want) > 0.01; i++) {
+    c *= 0.75;
+    out = oklchToHex({ L: want, C: c, H });
+  }
+  return out;
+}
+
+/**
+ * The fill one card draws in a colour-by mode.
+ *
+ * An entity with no block draws the drift overlay's own neutral — pinhole's
+ * `neutralFill`, the ground a card rides when chant could not read it — and
+ * NEVER the zero end of the scale. The zero end of a cost ramp says "free" and
+ * the zero end of a headroom ramp says "saturated"; both are claims about an
+ * entity nothing priced. `unpriced` comes back beside the colour so a caller
+ * can mark the card rather than infer the state back out of a hex.
+ */
+export function fillFor(value, domain, ramp, neutralFill) {
+  const t = positionOf(value, domain);
+  if (t === undefined) return { fill: neutralFill, unpriced: true };
+  return { fill: rampColor(t, ramp), unpriced: false };
+}
+
+/** How many entities in a set carry a figure for this mode, and how many don't. */
+export function countFigures(mode, blocks) {
+  let priced = 0;
+  let unpriced = 0;
+  for (const b of blocks) {
+    if (figureOf(mode, b) === undefined) unpriced++;
+    else priced++;
+  }
+  return { priced, unpriced };
+}
+
+/** The middle value of a sorted set — the even case averages the two middles,
+ * which is the ordinary definition and the only place this module produces a
+ * number no engine stated. Its caller labels it "computed" for that reason. */
+export function median(values) {
+  const xs = values.filter((v) => typeof v === "number" && Number.isFinite(v)).sort((a, b) => a - b);
+  if (!xs.length) return undefined;
+  const i = xs.length >> 1;
+  return xs.length % 2 ? xs[i] : (xs[i - 1] + xs[i]) / 2;
+}
+
+/** A per-hour cost, at the precision a cost that small deserves. */
+export function fmtCost(perHour, currency) {
+  if (typeof perHour !== "number" || !Number.isFinite(perHour)) return "—";
+  const digits = Math.abs(perHour) >= 1 ? 2 : 4;
+  return `${perHour.toFixed(digits)} ${currency}/h`;
+}
+
+/** A headroom fraction as the percentage of capacity still free. */
+export function fmtHeadroom(v) {
+  return typeof v === "number" && Number.isFinite(v) ? `${Math.round(v * 100)}% free` : "—";
+}
+
+/**
+ * The totals row for one scope (a box, or the whole estate), in the active
+ * mode's own terms.
+ *
+ * `cost` quotes arithmetic the server already did — `meta.behaviour.sum` or
+ * `.boxes[key]`, both of which are additions of engine figures — and, when the
+ * ENGINE stated an estate total, quotes that instead and says whose it is.
+ * That is the #398 precedence rule: `total` is the engine's word, `sum` is
+ * behold's, and the engine outranks the arithmetic.
+ *
+ * `headroom` has no server-side aggregate at all, because no engine stated one
+ * and adding fractions of capacity would be meaningless. The SPA takes the
+ * worst card and the middle card of the scope and says, in the row, that it
+ * computed them.
+ *
+ * `drift` gets no row: the drift overlay counts states, and a count of states
+ * is what the Model tab's legend has always shown.
+ */
+export function totalsFor(mode, blocks, sum, engineTotal) {
+  if (mode === "drift") return null;
+  const counts = countFigures(mode, blocks);
+  if (mode === "cost") {
+    // The engine's own total wins, and says so. Otherwise the server's sum;
+    // otherwise nothing to quote — never a figure computed here, because a
+    // currency behold cannot convert is exactly why the sum was withheld.
+    if (engineTotal) {
+      return {
+        mode,
+        source: "engine total",
+        value: fmtCost(engineTotal.perHour, engineTotal.currency),
+        counts,
+        computed: false,
+      };
+    }
+    if (!sum) return { mode, source: "sum", value: "—", counts, computed: false, missing: true };
+    return {
+      mode,
+      source: "sum",
+      value: fmtCost(sum.perHour, sum.currency),
+      counts: { priced: sum.priced, unpriced: sum.unpriced },
+      computed: false,
+    };
+  }
+  const xs = blocks.map((b) => headroomOf(b)).filter((v) => v !== undefined);
+  if (!xs.length) return { mode, source: "computed", value: "—", counts, computed: true, missing: true };
+  return {
+    mode,
+    source: "computed",
+    value: `min ${fmtHeadroom(Math.min(...xs))} · median ${fmtHeadroom(median(xs))}`,
+    counts,
+    computed: true,
+  };
+}
+
+/** The `n priced · m unpriced` tail every totals row and every legend carries. */
+export function countsText(counts) {
+  return `${counts.priced} priced · ${counts.unpriced} unpriced`;
+}
+
+/** The whole totals row as one line of text — what the smoke asserts, and what
+ * a narrow panel row renders. */
+export function totalsText(totals) {
+  if (!totals) return "";
+  return `${totals.value} · ${countsText(totals.counts)}${totals.computed ? " · computed" : ""}`;
+}
+
+/**
+ * The provenance badge (#401): `{engine} {version} · {tolerance} · {basis}`,
+ * beside every figure rather than once per page.
+ *
+ * `provenance` is per ENTITY in #398's contract, because one estate can be
+ * priced by two engines — so a badge over a SET of entities can only say what
+ * that set agrees on. Where they disagree the badge says `mixed` on the field
+ * that disagrees rather than picking one, and the tooltip names the engines.
+ * A badge over one entity is just that entity's own four fields.
+ *
+ * `modeled` is spelled out on hover as "modeled, not billed": the whole of #397
+ * turns on a prediction never being presented as a bill, and the badge is where
+ * that sentence has to live.
+ */
+export function badgeFor(blocks, meta) {
+  const provs = blocks.map((b) => b && b.provenance).filter(Boolean);
+  if (!provs.length) {
+    // No entity provenance in scope: the graph-level engine, when the lexicon
+    // stated one, is all there is to show — and it carries no tolerance or
+    // basis, because #398 puts those on the entity.
+    if (meta && meta.engine) return { text: `${meta.engine} ${meta.version}`, title: engineTitle(meta), engines: [`${meta.engine} ${meta.version}`] };
+    return null;
+  }
+  const one = (pick) => {
+    const vs = [...new Set(provs.map(pick))];
+    return vs.length === 1 ? vs[0] : "mixed";
+  };
+  const engines = [...new Set(provs.map((p) => `${p.engine} ${p.version}`))].sort();
+  const enginePart = engines.length === 1 ? engines[0] : `${engines.length} engines`;
+  const tolerance = one((p) => p.tolerance);
+  const basis = one((p) => p.basis);
+  const parts = [];
+  if (engines.length === 1) parts.push(`${provs[0].engine} ${provs[0].version}`);
+  else parts.push(enginePart);
+  parts.push(tolerance);
+  parts.push(basis);
+  const bases = [...new Set(provs.map((p) => p.basis))];
+  const title =
+    (engines.length === 1 ? `Stated by ${engines[0]}` : `Stated by ${engines.join(", ")}`) +
+    `, tolerance ${tolerance === "mixed" ? [...new Set(provs.map((p) => p.tolerance))].join(" / ") : tolerance}. ` +
+    (bases.length === 1
+      ? bases[0] === "modeled"
+        ? "modeled, not billed — a prediction from list prices, never a bill."
+        : "validated against a bill."
+      : "mixed basis — some figures are modeled, not billed; some are validated against a bill.") +
+    (meta && meta.at && meta.at.traffic ? ` At ${meta.at.traffic}.` : provs[0] && blocks[0] && blocks[0].at ? ` At ${blocks[0].at.traffic}.` : "");
+  return { text: parts.join(" · "), title, engines };
+}
+
+function engineTitle(meta) {
+  return `Stated by ${meta.engine} ${meta.version}.${meta.at && meta.at.traffic ? ` At ${meta.at.traffic}.` : ""} Provenance rides each figure; this scope carries none.`;
+}
+
+/**
+ * Which colour-by modes this graph can offer, and why not.
+ *
+ * A refusal or an absence disables both behaviour modes and hands back the
+ * lexicon's own sentence for the tooltip — the disabled control is where a
+ * person asks "why not", so that is where the answer goes. `drift` is never
+ * disabled: it does not depend on an engine, which is the whole reason #401
+ * says the drift overlay keeps rendering through a refusal.
+ */
+export function modeAvailability(meta, mode) {
+  const b = (meta && meta.behaviour) || null;
+  const overlay = !!b;
+  if (!overlay) {
+    return { available: false, reason: "the behaviour overlay is only on a live overlay — pick an environment on the Scope tab", refusal: null };
+  }
+  if (b.refusal) {
+    return { available: false, reason: `${b.refusal.reason} ${b.refusal.remedy}`, refusal: b.refusal };
+  }
+  if (b.absent) return { available: false, reason: b.absent, refusal: null };
+  return { available: true, reason: "", refusal: null };
+}
+
+/** The mode the SPA may actually paint in, given what the overlay carries.
+ * A picked mode outlives an overlay that cannot serve it — switch envs back
+ * and the pick is still there — but it never paints a scale over figures that
+ * are not on the page. */
+export function effectiveMode(picked, meta) {
+  if (picked === "drift") return "drift";
+  return modeAvailability(meta, picked).available ? picked : "drift";
+}
+
+export const COLOUR_MODES = ["drift", "cost", "headroom"];
+
+/** The legend's own words for a mode. */
+export const MODE_LABEL = { drift: "drift", cost: "cost", headroom: "headroom" };
+
+/** The two ends of a mode's ramp, in words — the legend's axis labels. */
+export function scaleEnds(mode, domain, currency = "") {
+  if (mode === "cost") {
+    if (!domain) return null;
+    return { low: fmtCost(domain.min, currency), high: fmtCost(domain.max, currency) };
+  }
+  if (mode === "headroom") return { low: "0% free", high: "100% free" };
+  return null;
+}
+
+/** A colour-mix-free CSS gradient over a ramp — sampled, so the stops are the
+ * same OKLCH walk the cards took rather than the browser's own sRGB blend. */
+export function rampGradient(ramp, steps = 12) {
+  const stops = [];
+  for (let i = 0; i < steps; i++) {
+    const t = i / (steps - 1);
+    stops.push(`${rampColor(t, ramp)} ${(t * 100).toFixed(1)}%`);
+  }
+  return `linear-gradient(90deg, ${stops.join(", ")})`;
+}

package/web/behaviour-scale.test.js

@@ -0,0 +1,307 @@
+// #399 M2 / #401 M4 of #397 — the colour-by modes' arithmetic, without a
+// browser. The smoke drives the same decisions through the real SPA; this pins
+// the rules that are easy to get subtly wrong and impossible to see in a
+// screenshot: an unpriced card never landing at the zero end of a scale, a
+// headroom axis the engine did not report never reading as a saturated one,
+// the engine's own total outranking behold's sum, and a badge over two engines
+// refusing to pick one of them.
+import { describe, it, expect } from "vitest";
+import { THEMES } from "./themes.js";
+import { tokensFor, hexToOklch } from "./theme.js";
+import {
+  badgeFor,
+  blockOf,
+  countFigures,
+  countsText,
+  domainFor,
+  effectiveMode,
+  figureOf,
+  fillFor,
+  fmtCost,
+  fmtHeadroom,
+  headroomOf,
+  median,
+  modeAvailability,
+  positionOf,
+  rampColor,
+  rampFor,
+  scaleEnds,
+  totalsFor,
+  totalsText,
+} from "./behaviour-scale.js";
+
+const prov = (over = {}) => ({ engine: "acme-sim", version: "1.4.2", tolerance: "±15%", basis: "modeled", ...over });
+const block = (over = {}) => ({
+  at: { traffic: "100 rps, p50" },
+  cost: { perHour: 0.05, currency: "USD" },
+  headroom: { cpu: 0.6, latency: 0.4 },
+  errorRate: 0.001,
+  resilience: { failure: "one zone lost", verdict: "survives" },
+  provenance: prov(),
+  ...over,
+});
+
+describe("reading a figure off a block", () => {
+  it("takes headroom as the LOWER of the axes present", () => {
+    expect(headroomOf(block({ headroom: { cpu: 0.6, latency: 0.4 } }))).toBe(0.4);
+    expect(headroomOf(block({ headroom: { cpu: 0.2, latency: 0.9 } }))).toBe(0.2);
+  });
+
+  it("reads a block with one axis on that axis alone — a missing axis is absent, not zero", () => {
+    // The whole point of #398's "a missing axis is absent, not 0": a block that
+    // reports only latency must not read as a card with no CPU left.
+    expect(headroomOf(block({ headroom: { latency: 0.8 } }))).toBe(0.8);
+    expect(headroomOf(block({ headroom: { cpu: 0.8 } }))).toBe(0.8);
+  });
+
+  it("has no figure at all for an entity with no block", () => {
+    expect(blockOf({ id: "a", attrs: {} })).toBeUndefined();
+    expect(figureOf("cost", undefined)).toBeUndefined();
+    expect(figureOf("headroom", undefined)).toBeUndefined();
+    expect(figureOf("drift", block())).toBeUndefined();
+  });
+});
+
+describe("the domain each mode spans", () => {
+  it("stretches cost over the estate's own min and max", () => {
+    const d = domainFor("cost", [0.01, 0.5, 0.25]);
+    expect(d).toMatchObject({ min: 0.01, max: 0.5, n: 3, absolute: false });
+  });
+
+  it("keeps headroom absolute at 0..1, so a comfortable estate's best card is not painted as its worst", () => {
+    const d = domainFor("headroom", [0.7, 0.8, 0.9]);
+    expect(d).toMatchObject({ min: 0, max: 1, absolute: true });
+    // 0.7 free is high on the axis, not the bottom of a 0.7..0.9 stretch.
+    expect(positionOf(0.7, d)).toBeCloseTo(0.7, 6);
+  });
+
+  it("has no cost domain when nothing in scope carries a price", () => {
+    expect(domainFor("cost", [])).toBeNull();
+    expect(positionOf(0.5, null)).toBeUndefined();
+  });
+
+  it("puts a flat domain mid-scale rather than at an end", () => {
+    expect(positionOf(4, domainFor("cost", [4, 4, 4]))).toBe(0.5);
+  });
+});
+
+describe("the neutral-not-zero rule (#399's own acceptance test)", () => {
+  const tokens = tokensFor(THEMES.Argonaut || Object.values(THEMES)[0]);
+  const NEUTRAL = "#3a3a3a";
+
+  it("draws an entity with no block in the drift overlay's neutral, never the zero end of the cost scale", () => {
+    const ramp = rampFor("cost", tokens);
+    const domain = domainFor("cost", [0.01, 0.5]);
+    const unpriced = fillFor(undefined, domain, ramp, NEUTRAL);
+    const cheapest = fillFor(0.01, domain, ramp, NEUTRAL);
+    expect(unpriced).toEqual({ fill: NEUTRAL, unpriced: true });
+    expect(cheapest.unpriced).toBe(false);
+    expect(cheapest.fill).not.toBe(NEUTRAL);
+    // The distinction the rule exists for: "nothing priced this" must not
+    // render as "this is the cheapest thing in the estate".
+    expect(unpriced.fill).not.toBe(cheapest.fill);
+  });
+
+  it("does the same in headroom mode, where the zero end would read as saturated", () => {
+    const ramp = rampFor("headroom", tokens);
+    const domain = domainFor("headroom", [0.4]);
+    expect(fillFor(undefined, domain, ramp, NEUTRAL)).toEqual({ fill: NEUTRAL, unpriced: true });
+    expect(fillFor(0, domain, ramp, NEUTRAL).fill).not.toBe(NEUTRAL);
+  });
+
+  it("counts the unpriced rather than dropping them", () => {
+    const blocks = [block(), undefined, block({ cost: { perHour: 1, currency: "USD" } })];
+    expect(countFigures("cost", blocks)).toEqual({ priced: 2, unpriced: 1 });
+    expect(countsText(countFigures("cost", blocks))).toBe("2 priced · 1 unpriced");
+  });
+});
+
+describe("the ramps, derived from the theme", () => {
+  it("no mode owns a fixed colour — every ramp stop comes out of the active palette", () => {
+    for (const name of ["Argonaut", "Builtin Solarized Light", "Hot Dog Stand"]) {
+      const th = THEMES[name];
+      if (!th) continue;
+      const t = tokensFor(th);
+      for (const mode of ["cost", "headroom"]) {
+        for (const stop of rampFor(mode, t)) expect(stop).toMatch(/^#[0-9a-f]{6}$/i);
+      }
+    }
+  });
+
+  it("gives every one of the 552 palettes a cost ramp you can tell low from high", () => {
+    const bad = [];
+    for (const th of Object.values(THEMES)) {
+      const ramp = rampFor("cost", tokensFor(th));
+      const low = rampColor(0, ramp);
+      const high = rampColor(1, ramp);
+      // The two ends have to differ perceptibly in lightness, or the scale is
+      // one flat colour and says nothing at all.
+      if (Math.abs(hexToOklch(low).L - hexToOklch(high).L) < 0.1) bad.push(th.name);
+    }
+    expect(bad).toEqual([]);
+  });
+
+  it("takes the headroom ramp's three stops from the drift overlay's own anchors, in every palette", () => {
+    // Not a separation assertion. A handful of palettes (Retro, Hot Dog Stand
+    // (Mustard)) paint slots 1 and 2 the same colour, so their red and their
+    // green ARE one colour — the drift legend reads alike on them too. That is
+    // the palette's choice; what this scale owes is that its ends are those
+    // anchors and nothing of its own invention.
+    const bad = [];
+    for (const th of Object.values(THEMES)) {
+      const t = tokensFor(th);
+      const ramp = rampFor("headroom", t);
+      if (rampColor(0, ramp) !== t.degraded || rampColor(1, ramp) !== t.managed || ramp[1] !== t.foreign) bad.push(th.name);
+    }
+    expect(bad).toEqual([]);
+  });
+
+  it("walks a hue the short way round, so a green-to-red ramp never swings through blue", () => {
+    // Two stops straddling 0°: red at ~29°, a green at ~145°. Midway must land
+    // in the yellows between them, not on the far side of the wheel.
+    const mid = hexToOklch(rampColor(0.5, ["#d02020", "#20b020"]));
+    expect(mid.H).toBeGreaterThan(29);
+    expect(mid.H).toBeLessThan(145);
+  });
+});
+
+describe("the totals row", () => {
+  const sum = { perHour: 0.5669, currency: "USD", priced: 41, unpriced: 4 };
+
+  it("is absent in drift mode — drift counts states, and the legend already does", () => {
+    expect(totalsFor("drift", [block()], sum, undefined)).toBeNull();
+  });
+
+  it("quotes the server's sum of engine figures, with its own priced/unpriced counts", () => {
+    const t = totalsFor("cost", [block()], sum, undefined);
+    expect(t.source).toBe("sum");
+    expect(t.computed).toBe(false);
+    expect(totalsText(t)).toBe("0.5669 USD/h · 41 priced · 4 unpriced");
+  });
+
+  it("lets the ENGINE's own total outrank behold's sum, and says whose it is", () => {
+    const t = totalsFor("cost", [block(), block()], sum, { perHour: 12.31, currency: "USD" });
+    expect(t.source).toBe("engine total");
+    expect(t.value).toBe("12.31 USD/h");
+  });
+
+  it("says nothing rather than adding figures the server withheld (mixed currencies)", () => {
+    const t = totalsFor("cost", [block()], undefined, undefined);
+    expect(t.missing).toBe(true);
+    expect(t.value).toBe("—");
+  });
+
+  it("computes headroom itself — no engine states an aggregate — and labels it computed", () => {
+    const blocks = [
+      block({ headroom: { cpu: 0.2, latency: 0.9 } }),
+      block({ headroom: { cpu: 0.6, latency: 0.7 } }),
+      block({ headroom: { cpu: 0.9, latency: 0.8 } }),
+      undefined,
+    ];
+    const t = totalsFor("headroom", blocks, sum, undefined);
+    expect(t.computed).toBe(true);
+    expect(t.value).toBe("min 20% free · median 60% free");
+    expect(totalsText(t)).toBe("min 20% free · median 60% free · 3 priced · 1 unpriced · computed");
+  });
+
+  it("takes the ordinary median of an even set", () => {
+    expect(median([0.1, 0.3, 0.5, 0.7])).toBeCloseTo(0.4, 6);
+    expect(median([])).toBeUndefined();
+  });
+
+  it("prints a small per-hour figure at four decimals and a large one at two", () => {
+    expect(fmtCost(0.0416, "USD")).toBe("0.0416 USD/h");
+    expect(fmtCost(12.3, "EUR")).toBe("12.30 EUR/h");
+    expect(fmtHeadroom(0.415)).toBe("42% free");
+  });
+
+  it("labels the cost scale's ends with the estate's own extremes", () => {
+    expect(scaleEnds("cost", domainFor("cost", [0.01, 0.5]), "USD")).toEqual({ low: "0.0100 USD/h", high: "0.5000 USD/h" });
+    expect(scaleEnds("headroom", domainFor("headroom", [0.5]))).toEqual({ low: "0% free", high: "100% free" });
+  });
+});
+
+describe("the provenance badge (#401)", () => {
+  it("reads {engine} {version} · {tolerance} · {basis} off one entity's own block", () => {
+    const b = badgeFor([block()], { engine: "acme-sim", version: "1.4.2", at: { traffic: "100 rps, p50" } });
+    expect(b.text).toBe("acme-sim 1.4.2 · ±15% · modeled");
+  });
+
+  it("spells `modeled` out as `modeled, not billed` on hover — the sentence #397 turns on", () => {
+    const b = badgeFor([block()], null);
+    expect(b.title).toContain("modeled, not billed");
+    expect(b.title).toContain("100 rps, p50");
+  });
+
+  it("says `validated against a bill` for a figure that was", () => {
+    const b = badgeFor([block({ provenance: prov({ basis: "validated" }) })], null);
+    expect(b.text).toContain("validated");
+    expect(b.title).toContain("validated against a bill");
+  });
+
+  it("refuses to pick one engine when a scope was priced by two", () => {
+    const b = badgeFor([block(), block({ provenance: prov({ engine: "other-sim", version: "2.0", tolerance: "±5%", basis: "validated" }) })], null);
+    expect(b.text).toBe("2 engines · mixed · mixed");
+    expect(b.engines).toEqual(["acme-sim 1.4.2", "other-sim 2.0"]);
+    expect(b.title).toContain("acme-sim 1.4.2, other-sim 2.0");
+  });
+
+  it("falls back to the graph-level engine when no entity in scope carries provenance", () => {
+    const b = badgeFor([], { engine: "acme-sim", version: "1.4.2" });
+    expect(b.text).toBe("acme-sim 1.4.2");
+    expect(b.title).toContain("Provenance rides each figure");
+  });
+
+  it("has nothing to badge when there is neither", () => {
+    expect(badgeFor([], null)).toBeNull();
+  });
+});
+
+describe("which modes a graph can offer", () => {
+  it("offers nothing off the overlay at all — there is no behaviour block on the source graph", () => {
+    const a = modeAvailability({ mode: "graph" }, "cost");
+    expect(a.available).toBe(false);
+    expect(a.reason).toContain("pick an environment");
+  });
+
+  it("keeps a picked mode alive when the overlay can serve it", () => {
+    const meta = { behaviour: { engine: "acme-sim", version: "1.4.2", sum: { perHour: 1, currency: "USD", priced: 2, unpriced: 0 } } };
+    expect(effectiveMode("cost", meta)).toBe("cost");
+    expect(effectiveMode("headroom", meta)).toBe("headroom");
+  });
+
+  it("falls back to drift rather than painting a scale over figures nobody sent — the PICK survives, so a live env that IS priced comes back in cost", () => {
+    expect(effectiveMode("cost", { behaviour: { absent: "…" } })).toBe("drift");
+    expect(effectiveMode("drift", null)).toBe("drift");
+  });
+});
+
+describe("what a refusal and an absence do to the modes (#401)", () => {
+  const refusal = { reason: "no behavioural engine is configured for this lexicon.", remedy: "Set CHANT_BEHAVIOUR_ENGINE." };
+
+  it("disables both behaviour modes on a refusal and hands back the lexicon's own words", () => {
+    // The reason a disabled control carries is the LEXICON's sentence, not a
+    // generic "unavailable" — that is the whole of #401's refusal half.
+    const meta = { behaviour: { refusal } };
+    for (const mode of ["cost", "headroom"]) {
+      const a = modeAvailability(meta, mode);
+      expect(a.available).toBe(false);
+      expect(a.reason).toContain("no behavioural engine is configured");
+      expect(a.reason).toContain("Set CHANT_BEHAVIOUR_ENGINE.");
+      expect(a.refusal).toEqual(refusal);
+    }
+  });
+
+  it("keeps drift painting through a refusal — drift never depended on an engine", () => {
+    expect(effectiveMode("drift", { behaviour: { refusal } })).toBe("drift");
+    expect(effectiveMode("cost", { behaviour: { refusal } })).toBe("drift");
+  });
+
+  it("disables the modes on an absence too, with the absent line as the reason and no refusal to print", () => {
+    const absent = "no behaviour block: no node carries attrs._behaviour, and no report document at monolith/behaviour.live.json";
+    const a = modeAvailability({ behaviour: { absent } }, "cost");
+    expect(a.available).toBe(false);
+    expect(a.reason).toBe(absent);
+    expect(a.refusal).toBeNull();
+  });
+});