katalyst-forge 5.3.0__tar.gz → 5.4.0__tar.gz

{katalyst_forge-5.3.0 → katalyst_forge-5.4.0}/CHANGELOG.md

@@ -16,6 +16,33 @@ PyPI package version. A breaking node-type/model change bumps `schema_version`.
 
 ---
 
+## [5.4.0] -- 2026-08-09
+
+### Added
+
+- **Per-dispatch model tier routing** (RIC-1580). A Forge dispatch can name the model tier it wants, and the orchestrator honours it through SDK child sessions rather than running every stage on the orchestrator model. Ships per-stage model and token telemetry alongside it, plus a containment and portability gate (`scripts/dispatch/check-dispatch.ts`) that reds on committed vendor model ids so a routing target cannot be hardcoded into the taxonomy.
+- **`quantity_kind` on every cost metric definition** (RIC-1645). The audited catalogue now declares what each figure IS (`spend`, `saving`, `counterfactual`, `ratio`), not only which catalogue priced it. Read by both renderers so presentation cannot disagree with the document the figure was computed from.
+
+### Fixed
+
+- **The run report no longer presents savings as money that was billed** (RIC-1645). Every USD metric was captioned `Metered spend` and charted under "Metered spend per metric, in dollars actually billed", including three that the report itself described as savings: `cache-savings` ("Net spend avoided"), `routing-headroom` ("not yet captured this run") and `routing-savings-realized` ("Saving actually captured"). One figure put $14.17 of bars on an axis labelled dollars actually billed for a run that billed $1.66. `BillingMode` answers which catalogue priced a figure, not whether it was billed; for `agent-run-cost` and `cost-per-stage` the two coincide, which is why rendering the basis tag as the label read correctly and the conflation survived the whole RIC-1615..1629 series. Billed spend now has an axis of its own, savings and modelled figures have theirs, and neither is scaled against or totalled with the other.
+- **The run report survives an unreadable message list instead of writing nothing** (RIC-1634). The cost path read each session's messages through an unguarded fetch while run health read the same endpoint through a degrading reader, so a persistent 500 on one session killed the whole report at the same moment run health was recording that session as degraded. Both halves now read through one path: the session degrades to its provider rollup, the run still reports, and the degraded-session panel names it. A transport failure is named (`ProviderTransportError` carries the endpoint) rather than surfacing as a traceback ending in a bare status code, and deliberately is not a `MetricsAdapterError`, so a host-level failure cannot be downgraded into a quietly missing source.
+- **A rate no longer borrows an endpoint it never reached** (RIC-1635). A 99.998% cache hit rate rendered as `100.00%`, which reads as every token served from cache. A rate strictly inside its range keeps a comparator, and the denominator it is computed over is stated in the metric definition the report renders.
+- **An absent measurement states itself** (RIC-1636). An unmeasured metric rendered as a numbered card with an empty body, which reads as a render bug, while `$0.00` would have read as measured and zero. It now carries the same explicit "not measured" marker the tiles use, and a billing-mode caption only ever appears under a money value, never under a ratio.
+- **The report self-identifies** (RIC-1637). It carries a UTC generation timestamp, the installed generator version, and the pricing catalogue the figures were priced against, the last only once a price was actually looked up.
+- **Rollup spend from a session that named no model is stated rather than left to vanish** (RIC-1638). It still gets no per-model row, because a fabricated model beside measured ones is worse than a gap, but the total is carried and both the tile and the detail note say so out loud.
+- **Money-mixing guards hardened** (RIC-1639). The billing-mode tag used to fall away the moment a value left `MetricResult`, so a one-line sum over `items()` produced exactly the cross-mode total the type exists to prevent. Values now leave tagged and refuse addition, `combine()` refuses to merge a result with itself, and a threshold band judges one billing mode instead of any figure that happens to share its unit.
+- **Message truncation is detected rather than silently shortening a run** (RIC-1631), and the RIC-1624 feature files are committed.
+- **`opencode.json` points at agents that exist** (RIC-1643). Every agent prompt referenced `./.opencode/agents/<name>.md`, but nothing is tracked under `.opencode/` and all 40 agents live in `agents/`. OpenCode validates `{file:...}` references when it loads a config, so it refused to start from the repo root and the repository was unusable as an OpenCode working directory. `scripts/validate.sh` had been checking that each declared agent KEY had a matching file, never the prompt reference OpenCode actually resolves, so it stayed green throughout; it now resolves every `{file:...}` reference.
+- **`kata-tax-validator-fixer` uses real kata commands** (RIC-1567). It invoked `kata tax json` and a `--path` flag, neither of which exists.
+- **The practice resolver probe fails loud** (#41). A failed probe returned the same empty result as a genuine zero, so a gate whose probe never ran reported a clean pass.
+
+### Changed
+
+- Minor rather than patch: RIC-1580 is additive and RIC-1645 adds a metric-definition field with a backward-compatible default. No node-type or model contract broke, so the bundle `schema_version` is unchanged.
+
+---
+
 ## [5.3.0] -- 2026-08-08
 
 ### Added

{katalyst_forge-5.3.0 → katalyst_forge-5.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: katalyst-forge
-Version: 5.3.0
+Version: 5.4.0
 Summary: Katalyst Forge: the delivery-lifecycle bundle (node kinds, wings, agents, templates, schemas)
 Author: eSimplicity
 License: Proprietary

{katalyst_forge-5.3.0 → katalyst_forge-5.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-forge"
-version = "5.3.0"
+version = "5.4.0"
 description = "Katalyst Forge: the delivery-lifecycle bundle (node kinds, wings, agents, templates, schemas)"
 license = { text = "Proprietary" }
 requires-python = ">=3.12"

{katalyst_forge-5.3.0 → katalyst_forge-5.4.0}/src/katalyst_forge/metrics/core.py

@@ -31,6 +31,44 @@ from katalyst_forge.metrics.protocols import (
 )
 
 
+class ModeTaggedMoney(Decimal):
+    """A figure that remembers the billing mode it came from, and refuses addition.
+
+    MetricResult refuses to total across modes, but the tag used to disappear the
+    moment a value left it, so a plain `sum()` over `items()` produced exactly the
+    cross-mode total the class exists to prevent. Tagging the leaf keeps the
+    guarantee where the numbers actually travel.
+
+    Only addition is blocked. Comparison, division, quantizing and formatting all
+    still work, because addition is the single operation that silently merges two
+    quantities into a third one that describes neither.
+    """
+
+    __slots__ = ("billing_mode",)
+
+    def __new__(cls, value: Decimal, mode: BillingMode) -> ModeTaggedMoney:
+        instance = super().__new__(cls, value)
+        instance.billing_mode = mode
+        return instance
+
+    def _refuse(self, other: object) -> ModeTaggedMoney:
+        other_mode = getattr(other, "billing_mode", None)
+        detail = (
+            f"{self.billing_mode.value} + {other_mode.value}"
+            if isinstance(other_mode, BillingMode)
+            else f"a {self.billing_mode.value} figure with {type(other).__name__}"
+        )
+        raise CrossBillingModeError(
+            f"cannot add {detail}; read one mode at a time, or combine() within a mode"
+        )
+
+    def __add__(self, other: object) -> ModeTaggedMoney:
+        return self._refuse(other)
+
+    def __radd__(self, other: object) -> ModeTaggedMoney:
+        return self._refuse(other)
+
+
 class MetricResult:
     """An immutable, mode-partitioned metric value. No cross-mode total exists."""
 
@@ -38,16 +76,21 @@ class MetricResult:
 
     def __init__(self, metric_name: str, by_mode: Mapping[BillingMode, Decimal]) -> None:
         self.metric_name = metric_name
-        self._by_mode: Mapping[BillingMode, Decimal] = MappingProxyType(dict(by_mode))
+        # Stored untagged so internal within-mode arithmetic (combine) stays
+        # ordinary; the tag is applied on the way out, where values escape.
+        self._by_mode: Mapping[BillingMode, Decimal] = MappingProxyType(
+            {mode: Decimal(value) for mode, value in by_mode.items()}
+        )
 
     def modes(self) -> tuple[BillingMode, ...]:
         return tuple(self._by_mode.keys())
 
-    def for_mode(self, mode: BillingMode) -> Decimal | None:
-        return self._by_mode.get(mode)
+    def for_mode(self, mode: BillingMode) -> ModeTaggedMoney | None:
+        value = self._by_mode.get(mode)
+        return None if value is None else ModeTaggedMoney(value, mode)
 
-    def items(self) -> tuple[tuple[BillingMode, Decimal], ...]:
-        return tuple(self._by_mode.items())
+    def items(self) -> tuple[tuple[BillingMode, ModeTaggedMoney], ...]:
+        return tuple((mode, ModeTaggedMoney(value, mode)) for mode, value in self._by_mode.items())
 
     def combine(self, other: MetricResult) -> MetricResult:
         """Merge two results of the same metric, within each billing mode only."""
@@ -55,6 +98,14 @@ class MetricResult:
             raise CrossBillingModeError(
                 f"cannot combine different metrics {self.metric_name!r} and {other.metric_name!r}"
             )
+        if self is other:
+            # Merging a result with itself doubles the run inside each mode, which
+            # is the same double count the cross-mode guard blocks, just wearing a
+            # different hat. Nothing legitimate combines a figure with itself.
+            raise CrossBillingModeError(
+                f"cannot combine metric {self.metric_name!r} with itself; "
+                "that would count the same spend twice"
+            )
         merged: dict[BillingMode, Decimal] = dict(self._by_mode)
         for mode, value in other._by_mode.items():  # noqa: SLF001 - same class
             merged[mode] = merged.get(mode, ZERO_USD) + value

{katalyst_forge-5.3.0 → katalyst_forge-5.4.0}/src/katalyst_forge/metrics/dashboard.py

@@ -16,10 +16,12 @@ from collections.abc import Mapping, Sequence
 from decimal import ROUND_HALF_UP, Decimal
 from typing import Final, cast
 
-from katalyst_forge.metrics.billing import BillingMode
+from katalyst_forge.metrics.billing import BillingMode, parse_billing_mode
 from katalyst_forge.metrics.core import MetricResult
 
 CENTS: Final[Decimal] = Decimal("0.01")
+ZERO_PERCENTAGE: Final[Decimal] = Decimal("0")
+FULL_PERCENTAGE: Final[Decimal] = Decimal("100")
 
 METERED_LABEL: Final[str] = "Metered spend"
 NOTIONAL_LABEL: Final[str] = "Subscription notional (not money spent)"
@@ -29,8 +31,62 @@ _MODE_LABELS: Final[Mapping[BillingMode, str]] = {
     BillingMode.SUBSCRIPTION_NOTIONAL: NOTIONAL_LABEL,
 }
 
+# What a figure IS, as distinct from the price basis it was computed on
+# (RIC-1645). BillingMode answers "which catalogue priced this"; it does not
+# answer "was this money billed". For a spend metric the two coincide, so the
+# basis label reads correctly. For a saving it does not: cache-savings is spend
+# avoided and routing-headroom was never incurred at all, yet both were captioned
+# "Metered spend" and charted under "dollars actually billed".
+QUANTITY_SPEND: Final[str] = "spend"
+QUANTITY_SAVING: Final[str] = "saving"
+QUANTITY_COUNTERFACTUAL: Final[str] = "counterfactual"
+QUANTITY_RATIO: Final[str] = "ratio"
+
+# An undeclared metric keeps the old caption, so a third-party bundle does not
+# silently change meaning on upgrade. The shipped catalogue cannot rely on that:
+# a test asserts every metric it ships declares a kind.
+DEFAULT_QUANTITY_KIND: Final[str] = QUANTITY_SPEND
+
+QUANTITIES_NOT_BILLED: Final[frozenset[str]] = frozenset({QUANTITY_SAVING, QUANTITY_COUNTERFACTUAL})
+
+_QUANTITY_LABELS: Final[Mapping[tuple[str, BillingMode], str]] = {
+    (QUANTITY_SPEND, BillingMode.METERED): METERED_LABEL,
+    (QUANTITY_SPEND, BillingMode.SUBSCRIPTION_NOTIONAL): NOTIONAL_LABEL,
+    (QUANTITY_SAVING, BillingMode.METERED): "Metered basis, spend avoided (not billed)",
+    (QUANTITY_SAVING, BillingMode.SUBSCRIPTION_NOTIONAL): (
+        "Notional basis, allocation avoided (not money spent)"
+    ),
+    (QUANTITY_COUNTERFACTUAL, BillingMode.METERED): (
+        "Metered basis, modelled and not captured (not billed)"
+    ),
+    (QUANTITY_COUNTERFACTUAL, BillingMode.SUBSCRIPTION_NOTIONAL): (
+        "Notional basis, modelled and not captured (not money spent)"
+    ),
+}
+
+
+def is_billed(quantity_kind: str | None) -> bool:
+    """Whether a figure of this kind is money that actually left the account."""
+    return (quantity_kind or DEFAULT_QUANTITY_KIND) not in QUANTITIES_NOT_BILLED
+
+
+def mode_label(mode: BillingMode, quantity_kind: str | None = None) -> str:
+    """Label a figure by what it is, not only by the catalogue that priced it.
+
+    Falls back to the bare basis label for any mode/kind pair not enumerated, so
+    a new billing mode degrades to naming its basis rather than asserting spend.
+    """
+    kind = quantity_kind or DEFAULT_QUANTITY_KIND
+    fallback = _MODE_LABELS.get(mode, str(mode))
+    return _QUANTITY_LABELS.get((kind, mode), fallback)
+
+
 _OPERATORS: Final[Mapping[str, str]] = {"<": "<", "<=": "<=", ">": ">", ">=": ">="}
 
+# A band with no declared mode is a spend threshold, because that is the only
+# quantity a dollar ceiling can sensibly police.
+_DEFAULT_BAND_MODE: Final[BillingMode] = BillingMode.METERED
+
 
 UNIT_USD: Final[str] = "usd"
 UNIT_PERCENTAGE: Final[str] = "percentage"
@@ -53,7 +109,20 @@ def format_usd(value: Decimal) -> str:
 
 
 def format_percentage(value: Decimal) -> str:
-    return f"{to_cents(value)}%"
+    """Render a rate without letting rounding claim an endpoint it never reached.
+
+    A 99.998% cache hit rate quantizes to 100.00, which reads as "every billable
+    input token came from cache". The gap between nearly all and all is the whole
+    reason the rate is reported, so a value strictly inside the range keeps a
+    comparator instead of borrowing the endpoint. An exact 0 or 100 still prints
+    as itself.
+    """
+    rounded = to_cents(value)
+    if rounded >= FULL_PERCENTAGE > value:
+        return f">{FULL_PERCENTAGE - CENTS}%"
+    if rounded <= ZERO_PERCENTAGE < value:
+        return f"<{CENTS}%"
+    return f"{rounded}%"
 
 
 def format_value(value: Decimal, unit: str | None) -> str:
@@ -118,11 +187,27 @@ def _as_sequence(value: object) -> Sequence[object]:
     return ()
 
 
+def _entry_judges_mode(entry: Mapping[str, object], billing_mode: BillingMode | None) -> bool:
+    """A band judges one billing mode, and by default that mode is real money.
+
+    A threshold written for dollars actually billed must not stamp a verdict on a
+    subscription-notional allocation, which is a different quantity that happens
+    to share a unit. A caller that does not say which mode it is judging is not
+    filtered, so text callers keep their existing behaviour.
+    """
+    if billing_mode is None:
+        return True
+    declared = entry.get("billing_mode")
+    expected = parse_billing_mode(declared) if isinstance(declared, str) else _DEFAULT_BAND_MODE
+    return expected is billing_mode
+
+
 def evaluate_band(
     *,
     metric_name: str,
     value: Decimal,
     threshold_profile_doc: Mapping[str, object],
+    billing_mode: BillingMode | None = None,
     breach_bands: frozenset[str] = frozenset({"amber", "red"}),
 ) -> BandVerdict:
     """Find the band a value falls in and flag a breach (AC5).
@@ -137,6 +222,8 @@ def evaluate_band(
         entry_mapping = _as_mapping(entry)
         if entry_mapping.get("metric") != metric_name:
             continue
+        if not _entry_judges_mode(entry_mapping, billing_mode):
+            continue
         for band in _as_sequence(entry_mapping.get("bands")):
             band_mapping = _as_mapping(band)
             operator = band_mapping.get("operator")
@@ -160,7 +247,11 @@ def evaluate_band(
     )
 
 
-def render_savings_panel(result: MetricResult, unit: str | None = UNIT_USD) -> tuple[str, ...]:
+def render_savings_panel(
+    result: MetricResult,
+    unit: str | None = UNIT_USD,
+    quantity_kind: str | None = None,
+) -> tuple[str, ...]:
     """Render one line per billing mode, never a combined figure (AC10).
 
     Returns a line per mode rather than a total. There is deliberately no
@@ -169,7 +260,7 @@ def render_savings_panel(result: MetricResult, unit: str | None = UNIT_USD) -> t
     """
     lines: list[str] = []
     for mode, value in result.items():
-        label = _MODE_LABELS.get(mode, str(mode))
+        label = mode_label(mode, quantity_kind)
         lines.append(f"{label}: {format_value(value, unit)}")
     return tuple(lines)
 
@@ -180,24 +271,29 @@ def render_dashboard(
     results: Sequence[MetricResult],
     threshold_profile_doc: Mapping[str, object],
     units: Mapping[str, str] | None = None,
+    quantity_kinds: Mapping[str, str] | None = None,
 ) -> str:
     """Render the whole dashboard as text, per metric and per billing mode.
 
     `units` maps a metric name to its declared unit so a ratio is never
-    rendered with a dollar sign.
+    rendered with a dollar sign. `quantity_kinds` maps a metric name to what its
+    figure is, so a saving is not captioned as spend.
     """
     unit_by_metric = units or {}
+    kind_by_metric = quantity_kinds or {}
     lines: list[str] = [f"Run: {run_id}", ""]
 
     for result in results:
         unit = unit_by_metric.get(result.metric_name, UNIT_USD)
+        kind = kind_by_metric.get(result.metric_name)
         lines.append(result.metric_name)
         for mode, value in result.items():
-            label = _MODE_LABELS.get(mode, str(mode))
+            label = mode_label(mode, kind)
             verdict = evaluate_band(
                 metric_name=result.metric_name,
                 value=value,
                 threshold_profile_doc=threshold_profile_doc,
+                billing_mode=mode,
             )
             suffix = ""
             if verdict.band_name is not None:
@@ -219,3 +315,21 @@ def units_from_metric_definitions(
         if isinstance(unit, str):
             units[name] = unit
     return units
+
+
+def quantity_kinds_from_metric_definitions(
+    metric_definitions: Mapping[str, Mapping[str, object]],
+) -> dict[str, str]:
+    """Read each metric's declared quantity kind from the audited catalogue.
+
+    Kept in the definitions rather than the renderer for the same reason units
+    are: whether a figure is spend or a saving is a property of the metric, and a
+    renderer that decided it locally could disagree with the document the figure
+    was computed from.
+    """
+    kinds: dict[str, str] = {}
+    for name, doc in metric_definitions.items():
+        kind = _as_mapping(doc.get("spec")).get("quantity_kind")
+        if isinstance(kind, str):
+            kinds[name] = kind
+    return kinds

{katalyst_forge-5.3.0 → katalyst_forge-5.4.0}/src/katalyst_forge/metrics/errors.py

@@ -120,3 +120,23 @@ class ProviderPayloadError(MetricsAdapterError):
 
     def __init__(self, *, field: str, value: object) -> None:
         super().__init__(f"unparseable provider payload for {field!r}: {redact(value)}")
+
+
+class ProviderTransportError(Exception):
+    """Raised when a provider request fails before any payload exists.
+
+    Deliberately NOT a MetricsAdapterError. The per-source and per-metric
+    handlers skip a MetricsAdapterError and carry on, which is right for a
+    source that cannot be computed but wrong for a host that cannot be reached:
+    that leaves a hole of unknown size, so it has to stay a hard failure and
+    reach the entry point.
+
+    Carries the endpoint rather than a bare status line, because an operator
+    reading the failure needs to know which request died. Only the URL and the
+    exception type are used; no response body reaches the message.
+    """
+
+    def __init__(self, *, url: str, detail: str) -> None:
+        self.url = url
+        self.detail = detail
+        super().__init__(f"request to {url} failed: {detail}")

{katalyst_forge-5.3.0 → katalyst_forge-5.4.0}/src/katalyst_forge/metrics/generate_dashboard.py

@@ -12,10 +12,12 @@ keeps its no-I/O guarantee. Credentials are read from the environment only.
 from __future__ import annotations
 
 import argparse
+import importlib.metadata
 import os
 import sys
 import time
 from collections.abc import Callable, Iterator, Mapping, Sequence
+from datetime import datetime, timezone
 from decimal import Decimal
 from pathlib import Path
 from typing import Final, cast
@@ -24,8 +26,12 @@ import yaml
 
 from katalyst_forge.metrics.batch import CanonicalSignalBatch
 from katalyst_forge.metrics.core import MetricResult, compute, resolve
-from katalyst_forge.metrics.dashboard import render_dashboard, units_from_metric_definitions
-from katalyst_forge.metrics.errors import MetricsAdapterError
+from katalyst_forge.metrics.dashboard import (
+    quantity_kinds_from_metric_definitions,
+    render_dashboard,
+    units_from_metric_definitions,
+)
+from katalyst_forge.metrics.errors import MetricsAdapterError, ProviderTransportError
 from katalyst_forge.metrics.html_report import render_html_report
 from katalyst_forge.metrics.protocols import PriceCatalogue, RoutingPolicy
 from katalyst_forge.metrics.registry import SignalProviderRegistry
@@ -246,6 +252,14 @@ def build_run_health(
     return None
 
 
+def _catalogue_source(signal_sources: Mapping[str, Document]) -> str | None:
+    """Name the endpoint prices are read from, for the report's provenance line."""
+    source = signal_sources.get("opencode-session-cost", {})
+    query_config = _as_mapping(_as_mapping(source.get("spec")).get("query_config"))
+    endpoint = query_config.get("providers_endpoint")
+    return endpoint if isinstance(endpoint, str) else None
+
+
 def _opencode_catalogue(
     *, signal_sources: Mapping[str, Document], provider_env: Mapping[str, str]
 ) -> PriceCatalogue:
@@ -258,6 +272,14 @@ def _opencode_catalogue(
     return provider.price_catalogue(query_config)
 
 
+def _generator_identity() -> str:
+    """Name the generator so a rendered report can be traced to a release."""
+    try:
+        return f"katalyst-forge {importlib.metadata.version('katalyst-forge')}"
+    except importlib.metadata.PackageNotFoundError:
+        return "katalyst-forge (working copy)"
+
+
 class LazyPriceCatalogue:
     """Defers building the live catalogue until a price is actually needed.
 
@@ -271,9 +293,20 @@ class LazyPriceCatalogue:
     needs a price never silently reads as free.
     """
 
-    def __init__(self, build: Callable[[], PriceCatalogue]) -> None:
+    def __init__(self, build: Callable[[], PriceCatalogue], *, source: str | None = None) -> None:
         self._build = build
         self._delegate: PriceCatalogue | None = None
+        self._source = source
+
+    @property
+    def priced_source(self) -> str | None:
+        """The catalogue this run was actually priced against, or None if unused.
+
+        Reported only once a price has really been looked up. A run that needed
+        no price was not priced against anything, and claiming a source it never
+        read would be a provenance line that means nothing.
+        """
+        return self._source if self._delegate is not None else None
 
     def unit_price_usd(self, model_key: str, token_kind: str) -> Decimal | None:
         if self._delegate is None:
@@ -307,34 +340,53 @@ def main(argv: Sequence[str] | None = None) -> int:
 
     provider_env: Mapping[str, str] = dict(os.environ)
     catalogue = LazyPriceCatalogue(
-        lambda: _opencode_catalogue(signal_sources=signal_sources, provider_env=provider_env)
+        lambda: _opencode_catalogue(signal_sources=signal_sources, provider_env=provider_env),
+        source=_catalogue_source(signal_sources),
     )
 
-    health = build_run_health(
-        run_id=run_id,
-        signal_sources=signal_sources,
-        provider_env=provider_env,
-        catalogue=catalogue,
-        now_ms=int(time.time() * 1000),
-    )
+    try:
+        health = build_run_health(
+            run_id=run_id,
+            signal_sources=signal_sources,
+            provider_env=provider_env,
+            catalogue=catalogue,
+            now_ms=int(time.time() * 1000),
+        )
 
-    results = build_results(
-        run_id=run_id,
-        metric_definitions=metric_definitions,
-        signal_sources=signal_sources,
-        provider_env=provider_env,
-        catalogue=catalogue,
-        policy=build_policy(env=provider_env, catalogue=catalogue),
-    )
+        results = build_results(
+            run_id=run_id,
+            metric_definitions=metric_definitions,
+            signal_sources=signal_sources,
+            provider_env=provider_env,
+            catalogue=catalogue,
+            policy=build_policy(env=provider_env, catalogue=catalogue),
+        )
+    except ProviderTransportError as exc:
+        # Still a hard failure, and still nothing written. What changes is that
+        # the operator is told which endpoint died instead of reading a traceback
+        # whose last line is a status code with no subject.
+        print(
+            f"cannot report on run {run_id}: {exc}. "
+            "No report was written, because a request that fails outright leaves "
+            "a gap of unknown size rather than a measurable one.",
+            file=sys.stderr,
+        )
+        return 1
 
     units = units_from_metric_definitions(metric_definitions)
+    quantity_kinds = quantity_kinds_from_metric_definitions(metric_definitions)
     if args.format == "html":
         rendered = render_html_report(
             run_id=run_id,
             results=results,
             threshold_profile_doc=threshold_profile,
             units=units,
+            generated=datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC"),
+            generator=_generator_identity(),
+            pricing_source=catalogue.priced_source,
             health=health,
+            metric_docs=metric_definitions,
+            quantity_kinds=quantity_kinds,
         )
     else:
         rendered = render_dashboard(
@@ -342,6 +394,7 @@ def main(argv: Sequence[str] | None = None) -> int:
             results=results,
             threshold_profile_doc=threshold_profile,
             units=units,
+            quantity_kinds=quantity_kinds,
         )
 
     out_path = cast("str | None", args.out)