loopmath 0.2.1__tar.gz → 0.2.2__tar.gz

{loopmath-0.2.1 → loopmath-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: loopmath
-Version: 0.2.1
+Version: 0.2.2
 Summary: Plan agent workflows, record how they went, and learn from your own Claude Code and Codex logs
 Author: QKV Labs
 License-Expression: MIT

{loopmath-0.2.1 → loopmath-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "loopmath"
-version = "0.2.1"
+version = "0.2.2"
 description = "Plan agent workflows, record how they went, and learn from your own Claude Code and Codex logs"
 readme = "README.md"
 license = "MIT"

{loopmath-0.2.1 → loopmath-0.2.2}/src/loopmath/__init__.py

@@ -5,4 +5,4 @@ The command line (`loopmath`, or its alias `loop`) is the interface; see the
 README and `loopmath --help`.
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

{loopmath-0.2.1 → loopmath-0.2.2}/src/loopmath/belief/design.py

@@ -13,7 +13,7 @@ A term is `(node_id, parent_id, value)`. Rows:
 from __future__ import annotations
 
 import math
-from collections.abc import Iterable
+from collections.abc import Iterable, Mapping
 from dataclasses import dataclass, field
 from datetime import datetime
 from functools import lru_cache
@@ -25,6 +25,7 @@ from ..types import (
     Workflow,
 )
 from .forest import canonical_model_id, canonical_role, model_path
+from .pricing import price_term
 
 Term = tuple[str, "str | None", float]
 
@@ -324,12 +325,15 @@ def _effort_scaled(terms: tuple[Term, ...], weight: float) -> tuple[Term, ...]:
 
 
 def cost_rest(st: Structure, piece: str, k: int, setting: Setting | None = None, *,
-              source: str | None = None, effort: float = 1.0) -> tuple[Term, ...]:
+              source: str | None = None, effort: float = 1.0,
+              prices: Mapping[str, float] | None = None) -> tuple[Term, ...]:
     """Cost and tokens rows without the task part: setting, role, topology, position, round, control,
     and with a `source` the position x source node `psrc:<shape>#<pos>|<source>` and the family x source
     node `fsrc:<family>|<source>` (spec 04 section 1). `effort` is the value of the terms a timebox caps, the
     effort and shape (topology, position) terms (`effort_weight`: below 1 under a timebox); the role, psrc and
-    fsrc terms stay at 1."""
+    fsrc terms stay at 1. `prices` is a fit's price offsets (`FitState.price_offsets`, spec 04 section 2): the
+    model's `price:offset` term goes last. The cost head has that node and the tokens head does not, so a
+    prediction's shared row prices only its cost."""
     s = setting or st.settings[piece]
     h, m, e = _s(s)
     shape = st.shape or st.workflow_id
@@ -343,7 +347,8 @@ def cost_rest(st: Structure, piece: str, k: int, setting: Setting | None = None,
         fam = model_path(m)[1]
         terms += ((f"psrc:{position}|{source}", f"position:{position}", 1.0),
                   (f"fsrc:{fam}|{source}", f"family:{fam}", 1.0))
-    return terms + tuple(round_terms(k)) + tuple(_control_terms(st.k_max, st.widths[piece]))
+    return (terms + tuple(round_terms(k)) + tuple(_control_terms(st.k_max, st.widths[piece]))
+            + price_term(prices, m))
 
 
 def gate_rest(st: Structure, gate: GateInfo, k: int) -> tuple[Term, ...]:
@@ -421,6 +426,7 @@ class AttemptObs:
     weight: float
     setting: Setting
     repriced: bool = True  # False: the recorded dollars, not the current tariff
+    streams: tuple[float, ...] = ()  # input, cache read, cache write, output tokens (pricing.STREAMS order)
 
 
 @dataclass
@@ -458,8 +464,10 @@ def source_label(doc: dict) -> str:
     ext = run.get("ext") or {}
     share = ext.get("dev.loopmath.share")
     if isinstance(share, dict):
-        org = share.get("org") or share.get("org_hash") or (run.get("task") or {}).get("org") or "shared"
-        return f"shared:{org}"
+        # the importer writes `source` and `task.org` as `shared:<org_hash>` already: never prefix twice
+        org = (share.get("source") or share.get("org") or share.get("org_hash") or (run.get("task") or {}).get("org")
+               or "shared")
+        return "shared:" + str(org).removeprefix("shared:")
     src = (run.get("task") or {}).get("source")
     kind = src.get("kind") if isinstance(src, dict) else src
     kind = str(kind or "").strip().lower()
@@ -761,7 +769,9 @@ def parse_run(doc: dict, *, now: datetime | None = None, rule: AcceptanceRule |
         if weight <= 0 or ((usd is None or usd <= 0) and not tokens):
             dropped["attempt without usable cost"] = dropped.get("attempt without usable cost", 0) + 1
             continue
-        attempts.append(AttemptObs(piece, k, usd if usd and usd > 0 else None, tokens, weight, setting, repriced))
+        streams = tuple(_ocp_fields(cost)[name] for name in _OCP_TOKEN_FIELDS)
+        attempts.append(AttemptObs(piece, k, usd if usd and usd > 0 else None, tokens, weight, setting, repriced,
+                                   streams))
 
     gates = _gate_observations(doc, st, by_piece_round)
     use_rule = rule or rule_from_doc(doc)

{loopmath-0.2.1 → loopmath-0.2.2}/src/loopmath/belief/fit.py

@@ -36,6 +36,7 @@ from .design import (DESIGN_VERSION, Term, Unusable, cost_row, gate_row, parse_r
 from .features import FeatureTally, add_horizon, drop_features, horizon_nodes, horizon_specs
 from .block import leaf_split
 from .forest import Forest, default_scale, fixed_sd, scale_group
+from .pricing import PRICE_NODE, PRICE_PRIOR_SD, STREAMS, fit_offsets, price_term
 from .gaussian import N_DRAWS, Factors, GaussianHead, HeadFit, LogisticHead, Prior
 from .state import SCORE_CLAMP, inverse_transform, transform  # noqa: F401  (re-exported)
 
@@ -163,6 +164,7 @@ class HeadRows:
     sources: list[str] = field(default_factory=list)
     types: list[str] = field(default_factory=list)
     not_repriced: int = 0  # cost rows on recorded dollars, not the current tariff
+    prices: dict = field(default_factory=dict)  # cost head: the fit's price offsets (pricing.fit_offsets)
 
     def add(self, terms, y, w, run, source, ttype):
         self.rows.append(terms)
@@ -213,6 +215,8 @@ def collect_rows(docs: Iterable[dict | tuple[str | None, dict]], *, without: tup
     stored: set[str] = set()  # run ids of the user's store, whose copy wins
     overlap: Counter = Counter()
     labels: Counter = Counter()
+    model_runs: dict[str, set[str]] = defaultdict(set)  # the price offset's inputs (spec 04 section 2)
+    model_streams: dict[str, list[float]] = defaultdict(lambda: [0.0] * len(STREAMS))
     for item in docs:
         origin, doc = item if isinstance(item, tuple) else (None, item)
         if origin is not None and _excluded(origin, without):
@@ -258,6 +262,10 @@ def collect_rows(docs: Iterable[dict | tuple[str | None, dict]], *, without: tup
             if a.usd:
                 heads["cost"].add(terms, math.log(a.usd), a.weight, pr.run_id, pr.source, ttype)
                 heads["cost"].not_repriced += not a.repriced
+                model_runs[a.setting.model].add(pr.run_id)
+                acc = model_streams[a.setting.model]
+                for i, v in enumerate(a.streams):
+                    acc[i] += v
             if a.tokens:
                 heads["tokens"].add(terms, math.log(a.tokens), a.weight, pr.run_id, pr.source, ttype)
         for gi, k, passed in pr.gates:
@@ -289,10 +297,34 @@ def collect_rows(docs: Iterable[dict | tuple[str | None, dict]], *, without: tup
     coding = tally.horizon_coding()  # the horizon terms need every run's horizon first (spec 04 section 1)
     for hr in heads.values():
         hr.rows = add_horizon(drop_features(hr.rows, tally.nodes), hr.runs, tally.run_horizon, coding)
+    add_prices(heads["cost"], {m: len(r) for m, r in model_runs.items()}, model_streams)
     return (heads, score_info, dict(dropped), dict(runs_by_source), {c: dict(n) for c, n in config_support.items()},
             dict(checks), dict(overlap), dict(labels), tally)
 
 
+def add_prices(hr: HeadRows, runs: dict[str, int], streams: dict[str, list[float]]) -> None:
+    """The price offset (spec 04 section 2): the fit's offsets from its runs and token mix under the current price
+    table, and each cost row with its model's `price:offset` term (`pricing.price_term`, as at prediction)."""
+    hr.prices = fit_offsets(runs, streams, design_rows._price_table())
+    offsets = hr.prices["models"]
+    if not offsets:
+        return
+    rows = []
+    for row in hr.rows:
+        model = next((n[len("model:"):] for n, _, _ in row if n.startswith("model:")), None)
+        term = price_term(offsets, model) if model else ()
+        rows.append(row + list(term) if term else row)
+    hr.rows = rows
+
+
+def price_spec(hr: HeadRows) -> list:
+    """The prior that holds `price:offset` at 1, on the cost head of a fit with offsets, --no-prior included."""
+    if not hr.prices.get("models"):
+        return []
+    return [prior_data.FactorSpec("cost", [(PRICE_NODE, None, 1.0)], 1.0, PRICE_PRIOR_SD ** 2,
+                                  f"{PRICE_NODE} held at 1, prior N(1, {PRICE_PRIOR_SD}^2)")]
+
+
 # ---------------------------------------------------------------- matrices and priors
 
 def build_matrix(rows: list[list[Term]], forest: Forest, extra_nodes: Iterable[tuple[str, str | None]] = ()):
@@ -532,6 +564,8 @@ def fit(home: Path, *, no_prior: bool = False, without: tuple[str, ...] = (), fu
             nodes = horizon_nodes(hr.rows)
             if nodes:  # the horizon priors, --no-prior included (spec 04 section 1)
                 head_specs += horizon_specs(name, hr.kind, nodes)
+            if name == "cost":  # the price offset (spec 04 section 2)
+                head_specs += price_spec(hr)
             fitted[name] = fit_head(hr, forest, head_specs, eb=eb)
         fit_id = new_fit_id(fits, now)
         partial = fits / f"{fit_id}.partial"
@@ -592,6 +626,7 @@ def fit(home: Path, *, no_prior: bool = False, without: tuple[str, ...] = (), fu
             "design_version": DESIGN_VERSION,
             "features": {**tally.report, **({"error": features_error} if features_error else {})},
             "horizons": tally.horizon_report(),
+            "price_offsets": heads_rows["cost"].prices,
         }
         if full:
             meta["full"] = _full_check(fitted)

{loopmath-0.2.1 → loopmath-0.2.2}/src/loopmath/belief/forest.py

@@ -55,6 +55,7 @@ FIXED_SD: dict[str, tuple[float, float, float]] = {
     "round": (2.0, 2.0, 2.0),
     "control": (1.0, 1.0, 1.0),
     "horizon": (10.0, 10.0, 10.0),  # wide: the informative prior is a FactorSpec in fit() (spec 04 section 1)
+    "price": (10.0, 10.0, 10.0),  # wide: fit() holds `price:offset` at 1 by a FactorSpec (spec 04 section 2)
 }
 
 HYPER_SD = 0.7  # sd of the log-normal hyperprior on each phi, around the defaults above

loopmath-0.2.2/src/loopmath/belief/pricing.py

@@ -0,0 +1,142 @@
+"""The price offset on the cost head (spec 04 section 2, 0.2.2, lane 22C).
+
+A model's run cost moves with its list price. Every cost row of a model version `m` (not the tokens, gate,
+success or score rows) carries the fixed term `price:offset` with the value
+
+    o_m = s_m * log(P_m / R_m),   s_m = n0 / (n0 + n_m),
+
+and the node's coefficient is held at 1 by a tight prior, so the term is a fixed offset on the log cost scale,
+the same at fit and at prediction:
+
+- `P_m` is m's blended list price ($/Mtok, the current price table) under the token mix (the shares of input,
+  cache read, cache write and output tokens) of the cost rows of m's family in the fit.
+- `R_m` is the run-weighted geometric mean of the blended prices, under the same mix, of the family's models
+  with cost rows. A family with no cost rows anchors on its provider the same way (the provider's mix and
+  models). No anchor, or no price for m, gives no term.
+- `n_m` is m's runs with a cost row in the fit; `PRICE_OFFSET_RUNS` is n0: the price counts like n0 of the
+  model's own runs, and its share of the prediction shrinks as they accumulate.
+
+`fit_offsets` computes the offset of every model with cost rows and of every model in the price table once per
+fit; `meta.json` `price_offsets` stores them, and prediction and the workflow search read them from there.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Iterable, Mapping
+
+from .forest import canonical_model_id, model_path
+
+PRICE_NODE = "price:offset"
+PRICE_LEVEL = "price"
+# n0: the list price counts like this many of the model's own runs (as one benchmark result counts like
+# BENCHMARK_PRIOR_WEIGHT = 5 runs). A heuristic, to tune when stores have new versions with a few runs.
+PRICE_OFFSET_RUNS = 5.0
+PRICE_PRIOR_SD = 1e-3  # the coefficient's prior N(1, sd^2): a fixed offset, not a learned elasticity
+STREAMS = ("input", "cache_read", "cache_write", "output")  # price table rate keys, in the order of `streams`
+
+
+def mix_of(totals: Iterable[float]) -> tuple[float, ...] | None:
+    """Token shares per stream (STREAMS order), or None without tokens."""
+    t = [max(0.0, float(x)) for x in totals]
+    s = sum(t)
+    return tuple(x / s for x in t) if s > 0 else None
+
+
+def blended(rate: Mapping[str, float] | None, mix: tuple[float, ...] | None) -> float | None:
+    """$/Mtok under `mix`, or None when the model has no rate, no mix, or a blended price of 0 (free)."""
+    if rate is None or mix is None:
+        return None
+    p = sum(share * float(rate.get(stream) or 0.0) for share, stream in zip(mix, STREAMS))
+    return p if p > 0 else None
+
+
+def shrink(runs: float, n0: float = PRICE_OFFSET_RUNS) -> float:
+    return n0 / (n0 + max(0.0, float(runs)))
+
+
+def _add(acc: dict[str, list[float]], key: str, values: Iterable[float]) -> None:
+    cur = acc.setdefault(key, [0.0] * len(STREAMS))
+    for i, v in enumerate(values):
+        cur[i] += float(v)
+
+
+def fit_offsets(runs: Mapping[str, int], streams: Mapping[str, Iterable[float]], table, *,
+                n0: float = PRICE_OFFSET_RUNS) -> dict:
+    """The fit's `price_offsets`: {n0, models: {model: offset}, detail, anchors}.
+
+    `runs`: model (canonical id) to its runs with a cost row; `streams`: model to its token totals over those
+    rows (STREAMS order); `table`: a price.PriceTable, or None (no offsets). Offsets of 0 are left out of
+    `models`; `detail` says for each priced model which anchor it used, or why it has none."""
+    out: dict = {"n0": n0, "models": {}, "detail": {}, "anchors": {}}
+    if table is None:
+        return out
+    fam_tok: dict[str, list[float]] = {}
+    prov_tok: dict[str, list[float]] = {}
+    fam_models: dict[str, dict[str, int]] = {}
+    prov_models: dict[str, dict[str, int]] = {}
+    for model, n in sorted(runs.items()):
+        if n <= 0:
+            continue
+        prov, fam, _ = model_path(model)
+        fam_models.setdefault(fam, {})[model] = int(n)
+        prov_models.setdefault(prov, {})[model] = int(n)
+        values = list(streams.get(model) or [0.0] * len(STREAMS))
+        _add(fam_tok, fam, values)
+        _add(prov_tok, prov, values)
+    candidates = set(runs) | {canonical_model_id(k) for k in table.rates}
+    anchors: dict[str, dict | None] = {}
+
+    def anchor(key: str, members: dict[str, int], tokens: list[float] | None) -> dict | None:
+        if key in anchors:
+            return anchors[key]
+        mix = mix_of(tokens or [])
+        priced = {m: (n, blended(table.rate(m), mix)) for m, n in members.items()}
+        priced = {m: (n, p) for m, (n, p) in priced.items() if p is not None}
+        found = None
+        if mix is not None and priced:
+            total = sum(n for n, _ in priced.values())
+            log_ref = sum(n * math.log(p) for n, p in priced.values()) / total
+            found = {"mix": mix, "log_ref": log_ref,
+                     "reference_usd_per_mtok": round(math.exp(log_ref), 6),
+                     "models": {m: n for m, (n, _) in sorted(priced.items())},
+                     "todo": sorted(m for m in priced if table.is_todo(m))}
+        anchors[key] = found
+        return found
+
+    for model in sorted(candidates):
+        prov, fam, _ = model_path(model)
+        a, key = None, None
+        if fam in fam_models:
+            key = f"family:{fam}"
+            a = anchor(key, fam_models[fam], fam_tok.get(fam))
+        if a is None and prov in prov_models and fam not in fam_models:
+            key = f"provider:{prov}"
+            a = anchor(key, prov_models[prov], prov_tok.get(prov))
+        if a is None:
+            out["detail"][model] = {"runs": int(runs.get(model, 0)), "note": "no anchor with runs and prices"}
+            continue
+        p = blended(table.rate(model), a["mix"])
+        if p is None:
+            out["detail"][model] = {"runs": int(runs.get(model, 0)), "anchor": key, "note": "no price"}
+            continue
+        n = int(runs.get(model, 0))
+        s = shrink(n, n0)
+        offset = s * (math.log(p) - a["log_ref"])
+        out["detail"][model] = {"runs": n, "anchor": key, "usd_per_mtok": round(p, 6), "shrink": round(s, 6),
+                                "log_ratio": round(math.log(p) - a["log_ref"], 6), "offset": round(offset, 6),
+                                **({"todo": True} if table.is_todo(model) else {})}
+        if offset != 0.0:
+            out["models"][model] = offset
+    out["anchors"] = {k: {**{kk: vv for kk, vv in v.items() if kk != "log_ref"}, "mix": [round(x, 6) for x in v["mix"]]}
+                      for k, v in sorted(anchors.items()) if v}
+    return out
+
+
+def price_term(offsets: Mapping[str, float] | None, model: str) -> tuple[tuple[str, None, float], ...]:
+    """The cost row's price term for `model` (a canonical id) under a fit's offsets: none for an offset of 0 or
+    a fit without offsets."""
+    if not offsets:
+        return ()
+    o = offsets.get(model)
+    return ((PRICE_NODE, None, float(o)),) if o else ()

{loopmath-0.2.1 → loopmath-0.2.2}/src/loopmath/belief/state.py

@@ -67,7 +67,7 @@ MIN_SCORE_SWITCH = 5  # spec 04 section 2: g = p_reach once the score head has 5
 BASE_HEADS = {"cost": ("gaussian", "cost"), "tokens": ("gaussian", "cost"), "gate": ("logistic", "logit"),
               "success": ("logistic", "logit")}
 TASK_CHAIN = ("task", "subtype", "repo", "type")
-FIXED_LEVELS = ("fixed", "round", "control")
+FIXED_LEVELS = ("fixed", "round", "control", "price")
 SCORE_CLAMP = (0.005, 0.995)
 _CACHE_LIMIT = 200_000
 MEAN_NODES = 12  # Gauss-Hermite nodes over an unseen normal effect
@@ -339,6 +339,8 @@ class FitState:
         self.sim_seed = _seed(self.seed_key, "simulate")
         # spec 04 section 1: the value of the timebox-capped terms (effort, shape) in a timeboxed task's cost rows
         self.timebox_effort = float(self.meta.get("timebox_effort", 1.0))
+        # spec 04 section 2: the fit's price offset per model (log scale); none in fits before 0.2.2
+        self.price_offsets: dict[str, float] = dict((self.meta.get("price_offsets") or {}).get("models") or {})
         if heads is None:
             heads = {}
             for name, hmeta in (self.meta.get("heads") or {}).items():
@@ -418,7 +420,8 @@ class FitState:
         for piece in st.pieces:
             rounds = st.k_max if st.piece_loop.get(piece) is not None else 1
             for k in range(1, rounds + 1):
-                cost[(piece, k)] = cost_rest(st, piece, k, source=PREDICT_SOURCE, effort=effort)
+                cost[(piece, k)] = cost_rest(st, piece, k, source=PREDICT_SOURCE, effort=effort,
+                                             prices=self.price_offsets)
         gate = {}
         for gi, g in enumerate(st.gates):
             for k in range(1, (st.k_max if st.gate_loop.get(gi) is not None else 1) + 1):

{loopmath-0.2.1 → loopmath-0.2.2}/src/loopmath/builder/context.py

@@ -21,7 +21,8 @@ from typing import Any
 from ..output import EXIT_NOT_FOUND, EXIT_OK, fail, home as home_dir
 from ..recommend import commands as C
 from ..recommend import engine, storeread
-from ..recommend.engine import Recommendation
+from ..recommend.curve import accepted_within
+from ..recommend.engine import Recommendation, r6
 from ..recommend.storeread import Conf
 from ..types import AcceptanceRule, Configuration, Task
 
@@ -45,6 +46,8 @@ class Session:
     cache: OrderedDict = field(default_factory=OrderedDict)  # config id -> predict answer
     context: dict[str, Any] | None = None
     models: dict[str, int] | None = None  # `known_models`, read once
+    home: Any = None  # the store, for the runs behind each model
+    offered: list[str] = field(default_factory=list)  # `commands.offered_models`: the models the page offers
 
 
 # ---------------------------------------------------------------- start
@@ -70,6 +73,13 @@ def asked_task(task: Task, id_given: bool, belief: Any, rule: AcceptanceRule, co
     return C.question_task(task, key_of(belief) if callable(key_of) else belief.fit_id, rule, configs)
 
 
+def offered_kw(models: list[str]) -> dict[str, Any]:
+    """`offered=` for `engine.recommend` when it takes it (0.2.2), so the builder asks what `recommend` asks."""
+    import inspect
+
+    return {"offered": models} if "offered" in inspect.signature(engine.recommend).parameters else {}
+
+
 def build_session(args: argparse.Namespace) -> tuple[Session | None, int]:
     """The session, or None and the exit code after the message `recommend` would print."""
     home = home_dir(getattr(args, "home", None))
@@ -98,6 +108,7 @@ def build_session(args: argparse.Namespace) -> tuple[Session | None, int]:
         spend, cap = C.budget(home, conf)
         settings = C.settings_from(conf, args, spend, cap)
         models = C.model_list(getattr(args, "models", None))
+        offered = C.offered_models(conf, models)
     except C.NotFound as exc:
         return None, fail(str(exc), EXIT_NOT_FOUND)
     except ValueError as exc:
@@ -125,12 +136,12 @@ def build_session(args: argparse.Namespace) -> tuple[Session | None, int]:
         asked = asked_task(task, id_given, belief, rule, [usual, *(c for c, _ in configs)])
         rec = engine.recommend(belief, asked, rule, usual=usual, usual_from=usual_from, configs=configs,
                                settings=settings, diff=C.diff_fn(), keep=[*(u.id for u in user),
-                                                                        *(r.id for r in recorded)])
+                                                                        *(r.id for r in recorded)],
+                               **offered_kw(offered))
         rec.task = task
         start = None
         if getattr(args, "start", None):
-            found = rec.by_id(args.start)
-            start = found.config if found is not None else storeread.find_config(home, args.start)
+            start = rec_config(rec, args.start) or storeread.find_config(home, args.start)
             if start is None:
                 raise C.NotFound(f"configuration {args.start} not found in this recommendation, earlier "
                                  f"recommendations or stored runs")
@@ -139,7 +150,20 @@ def build_session(args: argparse.Namespace) -> tuple[Session | None, int]:
     except ValueError as exc:
         return None, fail(str(exc))
     fit = {**C.fit_info(belief, now), "runs": int(getattr(belief, "n_runs", 0) or 0)}
-    return Session(belief, asked, rule, rec, fit, rec_id=getattr(args, "rec", None), start=start), EXIT_OK
+    return Session(belief, asked, rule, rec, fit, rec_id=getattr(args, "rec", None), start=start,
+                   home=home, offered=offered), EXIT_OK
+
+
+def rec_config(rec: Recommendation, cfg_id: str) -> Configuration | None:
+    """A configuration of the recommendation by id: a candidate (every choice is one), the reference or the
+    rescue workflow."""
+    found = rec.by_id(cfg_id)
+    if found is not None:
+        return found.config
+    for cfg in (rec.usual.config, rec.rescue_config):
+        if cfg is not None and cfg.id == cfg_id:
+            return cfg
+    return None
 
 
 # ---------------------------------------------------------------- catalog
@@ -161,32 +185,93 @@ def rec_configs(rec: Recommendation) -> list[Configuration]:
 
 
 def known_models(session: Session) -> dict[str, int]:
-    """Model id -> runs behind it: the fit's models and any a candidate uses (0 runs when the fit has no node)."""
+    """Model id -> runs the fit has behind it, for the offered models (0.2.2: `recommend`'s list, so a retired
+    model is not offered), in offered order; without a list, the fit's models and any a candidate uses."""
     if session.models is None:
-        out = fit_models(session.belief)
-        for cfg in rec_configs(session.rec):
-            for s in cfg.settings.values():
-                out.setdefault(s.model, 0)
+        fit = fit_models(session.belief)
+        if session.offered:
+            out = {m: fit.get(m, 0) for m in session.offered}
+        else:
+            out = fit
+            for cfg in rec_configs(session.rec):
+                for s in cfg.settings.values():
+                    out.setdefault(s.model, 0)
         session.models = out
     return session.models
 
 
+def retired_ids(rec: Recommendation) -> dict[str, list[str]]:
+    return dict(getattr(rec, "retired", None) or {})
+
+
+def recorded_runs(home: Any) -> list[tuple[Configuration, int]]:
+    """Every configuration the store's runs used, with its number of runs (one run document read per
+    configuration, as `storeread.recorded_configs` reads them)."""
+    from collections import Counter
+
+    if home is None:
+        return []
+    counts: Counter = Counter()
+    run_of: dict[str, str] = {}
+    for row in storeread.run_rows(home):
+        cfg = row.get("config")
+        if cfg:
+            counts[str(cfg)] += 1
+            if row.get("run"):
+                run_of[str(cfg)] = str(row["run"])
+    out = []
+    for cfg_id, n in counts.items():
+        doc = storeread.read_json(home / "runs" / f"{run_of[cfg_id]}.ocp.json") if cfg_id in run_of else None
+        conf = doc.get("run", {}).get("configuration") if isinstance(doc, dict) else None
+        cfg = storeread.config_from_any(conf) if conf else None
+        if cfg is not None:
+            out.append((cfg, n))
+    return out
+
+
+def runs_behind(home: Any) -> tuple[dict[str, dict[str, Any]], dict[str, int]]:
+    """(by model: `{total, by_role, by_effort}`, by role: runs) from the user's recorded runs. A run counts
+    once per model, once per (model, role), once per (model, role, effort) and once per role."""
+    models: dict[str, dict[str, Any]] = {}
+    roles: dict[str, int] = {}
+    for cfg, n in recorded_runs(home):
+        used: set[tuple[str, str, str]] = set()
+        for p in cfg.workflow.pieces:
+            s = cfg.settings.get(p.id)
+            if s is not None and s.model:
+                used.add((s.model, p.role, s.effort or ""))
+        for role in {p.role for p in cfg.workflow.pieces}:
+            roles[role] = roles.get(role, 0) + n
+        for model in {m for m, _, _ in used}:
+            m = models.setdefault(model, {"total": 0, "by_role": {}, "by_effort": {}})
+            m["total"] += n
+            for role in {r for mm, r, _ in used if mm == model}:
+                m["by_role"][role] = m["by_role"].get(role, 0) + n
+            for _, role, effort in (u for u in used if u[0] == model):
+                e = m["by_effort"].setdefault(role, {})
+                e[effort] = e.get(effort, 0) + n
+    return models, roles
+
+
 def catalog(session: Session) -> dict[str, Any]:
     from ..workflows.format import KNOWN_ROLES, catalog as shapes
     from ..workflows.models import DEFAULT_EFFORTS, efforts_for, family_of, harness_for, sort_efforts
 
     seen = [s for cfg in rec_configs(session.rec) for s in cfg.settings.values()]
     harnesses = list(dict.fromkeys([*DEFAULT_EFFORTS, *(s.harness for s in seen)]))
-    models = sorted(known_models(session).items(), key=lambda kv: (-kv[1], kv[0]))
+    behind, role_runs = runs_behind(session.home)
+    empty = {"total": 0, "by_role": {}, "by_effort": {}}
+    order = {m: i for i, m in enumerate(known_models(session))}
+    models = sorted(order, key=lambda m: (-behind.get(m, empty)["total"], order[m]))
     by_harness = {h: list(efforts_for(h)) for h in harnesses}
     efforts = sort_efforts([e for v in by_harness.values() for e in v] + [s.effort for s in seen])
     return {
         "harnesses": harnesses,
-        "models": [{"id": m, "family": family_of(m), "harness": harness_for(m), "runs_behind": n}
-                   for m, n in models],
+        "models": [{"id": m, "family": family_of(m), "harness": harness_for(m),
+                    "runs_behind": behind.get(m, empty)} for m in models],
         "efforts": list(efforts),
         "efforts_by_harness": by_harness,
-        "roles": list(KNOWN_ROLES),
+        "roles": [{"id": r, "runs": role_runs.get(r, 0)} for r in dict.fromkeys([*KNOWN_ROLES, *role_runs])],
         "shapes": [{"id": wf.id, "title": wf.title,
                     "pieces": [{"id": p.id, "role": p.role, "width": p.width} for p in wf.pieces],
                     "edges": [list(e) for e in wf.edges],
@@ -196,8 +281,27 @@ def catalog(session: Session) -> dict[str, Any]:
 
 
 # ---------------------------------------------------------------- the context
+def within_bands(bands: dict[str, Any], rescue: Any) -> dict[str, Any]:
+    """`bands` with `p_accepted_within`, mapped end by end from the chance band (`g + (1 - g) p_fix` is
+    increasing in `g`, as `Recommendation.within` reads its interval)."""
+    chance = bands.get("chance") if isinstance(bands, dict) else None
+    if not isinstance(chance, dict):
+        return bands
+
+    def f(g: Any) -> float | None:
+        return None if g is None else r6(accepted_within(float(g), rescue))
+
+    return {**bands, "p_accepted_within": {lv: [f(v[0]), f(v[1])] for lv, v in chance.items()}}
+
+
+def numbers_of(rec: Recommendation, pred: Any) -> dict[str, Any]:
+    """`Recommendation.numbers()` with the `p_accepted_within` band."""
+    n = rec.numbers(pred)
+    return {**n, "bands": within_bands(n["bands"], rec.rescue)}
+
+
 def candidate_entry(rec: Recommendation, c: Any) -> dict[str, Any]:
-    return {"config": c.config.to_dict(), "label": rec.label(c.config), "numbers": rec.numbers(c.prediction),
+    return {"config": c.config.to_dict(), "label": rec.label(c.config), "numbers": numbers_of(rec, c.prediction),
             "origin": c.origin, **rec.search_fields(c.config.id)}
 
 
@@ -210,12 +314,20 @@ def context_payload(session: Session) -> dict[str, Any]:
     choices = []
     for ch in core["choices"]:
         c = rec.by_id(ch["config"])
-        choices.append({**ch, "configuration": c.config.to_dict() if c is not None else None})
+        choices.append({**ch, "bands": within_bands(ch["bands"], rec.rescue),
+                        "configuration": c.config.to_dict() if c is not None else None})
     reference = {k: v for k, v in core["reference"].items() if k != "prediction"}
-    top = rec.candidates[:TOP_CANDIDATES]
+    reference["numbers"] = numbers_of(rec, rec.usual.prediction)
+    retired = retired_ids(rec)  # 0.2.2: a workflow on a retired model is the reference at most, never a candidate
+    offer = [c for c in rec.candidates if c.config.id not in retired]
+    top = offer[:TOP_CANDIDATES]
     ids = {c.config.id for c in top}
-    wanted = {rec.usual.config.id, *(ch["config"] for ch in core["choices"])}
-    top += [c for c in rec.candidates[TOP_CANDIDATES:]
+    # every option's workflows (the pair's exploration one too) and the rescue workflow, whatever the cutoff (22R B3)
+    wanted = {rec.usual.config.id, *(i for ch in core["choices"]
+                                     for i in (ch["config"], *ch.get("members", ()), ch.get("explore_config")) if i)}
+    if rec.rescue_config is not None:
+        wanted.add(rec.rescue_config.id)
+    top += [c for c in offer[TOP_CANDIDATES:]
             if c.config.id not in ids and (c.origin in KEEP_ORIGINS or c.config.id in wanted)]
     session.context = {
         "schema": SCHEMA,
@@ -223,6 +335,7 @@ def context_payload(session: Session) -> dict[str, Any]:
         "rule": core["rule"],
         "fit": session.fit,
         "rec": session.rec_id,
+        "goal_config_id": rec.goal.config.id,
         "rescue": core["rescue"],
         "reference": reference,
         "choices": choices,