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

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

@@ -16,6 +16,49 @@ PyPI package version. A breaking node-type/model change bumps `schema_version`.
 
 ---
 
+## [5.4.1] -- 2026-08-09
+
+### Fixed
+
+- **The practice resolver reads the schema the taxonomy actually authors** (RIC-1532). It instructed agents to read three things that do not exist: `spec.practice.applicableTo`, a `skill_ref` on a practice, and an enforcement ladder of required/recommended/optional. Two TODO blocks admitted the schema was unresolved and asked callers not to depend on the paths, which left the practice-compliance gate documented against a contract no taxonomy can honour. Resolved by reading the shipped `wings/practices.py` and probing a real taxonomy rather than the docs example, which turns out not to match what is authored: `practice` is a real kind, no applicability field exists on it or on `practice_area` so context can only scope which areas are in play, `enforcement` lives on the `standard` node valued automated/review/advisory, and pillars live at `spec.pillars`. The graph cannot serve any of it, because `kata tax show --format json` reduces a `practice_area` spec to the generic envelope, so identity now comes from the probe and content from the source file the probe reports. The fail-loud probe contract from #41 is intact and gains one case: no resolved source is inconclusive, not a clean zero.
+- **The auditor and reporter agree on what blocks** (RIC-1532). Both consumers of the resolver were corrected in the same change, because leaving them would have had the resolver grade every finding advisory while the reporter printed "Non-compliant (required)" and "Blocks: Yes" for that same finding. Blocking now originates only from a standard with `enforcement: automated` or from an NFR, and an inconclusive probe can no longer surface as a pass.
+- **`kata-code-reviewer` no longer installs with unrestricted shell and dispatch** (RIC-1648). The agent shipped in `agents/` and did install globally, because `install-opencode.mjs` enumerates that directory rather than reading `opencode.json`, but it was absent from `opencode.json`'s agent map entirely. That absence was not cosmetic: `opencode.json` is the only place the per-agent permission blocks live in full, and the installer mirrors `permission` from it so an installed agent is no more privileged than its in-repo counterpart. With no entry to mirror, the installed reviewer carried only the `external_directory` rule from its own frontmatter, leaving `tools.bash` and `tools.task` true with no corresponding `permission` blocks, the one agent in the installed set with unbounded shell and unbounded sub-agent dispatch. It now carries an entry bounded to what its prompt does: `permission.task` names only `kata-forge-architect` and `kata-forge-security`, and `bash` is an allowlist over a `"*": "deny"` floor. NFR-023 recorded this agent as the live example of its fourth caller state, absent from the agent map, and the same NFR fails closed for unbounded callers until each carries an explicit entry, so a bounded entry satisfies the gate rather than widening it. Unbounded callers drop from three to two.
+
+### Changed
+
+- The fourth caller state in the NFR-023 differential gate is still tested, now built from a synthetic caller name instead of asserting that a real shipped agent is broken, which is what made that assertion fail the moment the agent was fixed.
+- `kata-code-reviewer` is counted where it had been uncounted: `validate.sh`'s agent list, and a new `review` family in `openpackage.yml` rather than the `forge` family, since it is a standalone reviewer and not a Forge stage agent.
+- Patch rather than minor: both changes correct a contract that was already published, and neither touches `src/` or `schemas/`, so the PyPI wheel and the JSON Schemas are unchanged from 5.4.0 and the bundle `schema_version` stays put. What moves is agent, skill and configuration content.
+
+---
+
+## [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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: katalyst-forge
-Version: 5.3.0
+Version: 5.4.1
 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.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-forge"
-version = "5.3.0"
+version = "5.4.1"
 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.1}/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.1}/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.1}/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.1}/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)