loopmath 0.2.2__py3-none-any.whl → 0.2.4__py3-none-any.whl

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.2"
+__version__ = "0.2.4"

loopmath/adapters/atrium.py

@@ -470,7 +470,7 @@ class AtriumAdapter(Adapter):
         return {
             "ocp": "0.2",
             "producer": {
-                "name": "dagr-adapter-atrium",
+                "name": "loopmath/adapter-atrium",
                 "framework": "atrium",
                 "source_contract": "atrium/timeline+task-run-segments",
                 "capabilities": {

loopmath/adapters/bb.py

@@ -408,7 +408,7 @@ class BbAdapter(Adapter):
         )
         ignored_snapshots = sum(thread["ignored_token_snapshots"] for thread in selected)
         producer: dict[str, Any] = {
-            "name": "dagr-adapter-bb",
+            "name": "loopmath/adapter-bb",
             "framework": "bb",
             "source_contract": "bb/sqlite",
             "capabilities": {

loopmath/adapters/opencode.py

@@ -386,7 +386,7 @@ def _emit_document(
     else:
         source_contract = "opencode export"
     producer: dict[str, Any] = {
-        "name": "dagr-adapter-opencode",
+        "name": "loopmath/adapter-opencode",
         "framework": "opencode",
         "source_contract": source_contract,
         "capabilities": {

loopmath/adapters/orca.py

@@ -458,7 +458,7 @@ class OrcaAdapter(Adapter):
         return {
             "ocp": "0.2",
             "producer": {
-                "name": "dagr-adapter-orca",
+                "name": "loopmath/adapter-orca",
                 "framework": "orca",
                 "source_contract": "orca/orchestration.db",
                 "capabilities": {

loopmath/adapters/otel_genai.py

@@ -383,7 +383,7 @@ class OtelGenAIAdapter(Adapter):
         return {
             "ocp": "0.2",
             "producer": {
-                "name": "dagr-adapter-otel-genai",
+                "name": "loopmath/adapter-otel-genai",
                 "framework": "+".join(harnesses) if harnesses else "unknown",
                 "source_contract": "OTLP/JSON file exporter",
                 "capabilities": {

loopmath/adapters/paseo.py

@@ -418,7 +418,7 @@ class PaseoAdapter(Adapter):
         return {
             "ocp": "0.2",
             "producer": {
-                "name": "dagr-adapter-paseo",
+                "name": "loopmath/adapter-paseo",
                 "framework": "paseo",
                 "source_contract": "paseo/agent-json",
                 "capabilities": {

loopmath/belief/check_pymc.py

@@ -21,9 +21,13 @@ from __future__ import annotations
 import time
 
 import numpy as np
-import pymc as pm
-import pytensor
-import pytensor.tensor as pt
+
+from ..fit_bayes import use_store_compiledir
+
+use_store_compiledir()  # before pytensor is imported: its compile folder goes in the store's cache
+import pymc as pm  # noqa: E402
+import pytensor  # noqa: E402
+import pytensor.tensor as pt  # noqa: E402
 
 from .gaussian import HYPER_SD, SIGMA_PRIOR_SD, GaussianHead
 

loopmath/belief/commands.py

@@ -121,6 +121,36 @@ def _print_summary(s: dict) -> None:
                   f"(table in pymc_check.json)")
 
 
+def _in_pymc_check(exc: BaseException) -> bool:
+    """Whether `exc` was raised inside the `--full` PyMC check (check_pymc, pymc or pytensor)."""
+    tb = exc.__traceback__
+    while tb is not None:
+        if tb.tb_frame.f_globals.get("__name__") == "loopmath.belief.check_pymc":
+            return True
+        tb = tb.tb_next
+    return False
+
+
+def _pymc_check_failed(home: Path, exc: BaseException) -> int:
+    """`fit --full` whose PyMC check failed (a compiler error, say): remove the unfinished fit
+    folder and say what happened in one line, without a traceback."""
+    from .fit import FitBusy, fit_lock, remove_partials
+
+    try:
+        with fit_lock(home, LOCK_WAIT_S):  # under the lock every .partial is from a fit that stopped
+            remove_partials(home)
+    except FitBusy:
+        pass  # the next fit removes it
+    lines = [ln.strip() for ln in str(exc).splitlines() if ln.strip()]
+    said = ([ln for ln in lines if ln.startswith("ld:")]  # the linker's reason, then the first compiler error
+            or [ln for ln in lines if ln.startswith("error:") or " error: " in ln])
+    detail = (said[0] if said else (lines or [type(exc).__name__])[-1])[:200]
+    kind = "could not compile its model on this machine" if type(exc).__name__ == "CompileError" else "stopped"
+    return output.fail(f"fit --full: the PyMC check {kind} ({type(exc).__name__}: {detail}). No fit was "
+                       "written and fits/latest did not move; loopmath fit without --full fits as usual.",
+                       output.EXIT_USER)
+
+
 def fit(args: argparse.Namespace) -> int:
     home = output.home(getattr(args, "home", None))
     without = tuple(getattr(args, "without", None) or ())
@@ -140,10 +170,16 @@ def fit(args: argparse.Namespace) -> int:
         else:
             print(f"fit queued: {started.get('reason', 'a fit is running')}")
         return output.EXIT_OK
+    import contextlib
+    import sys
+
     from .fit import FitBusy, NothingToFit, UnknownSource, fit as run_fit
 
+    # --full: a failed compile makes pytensor print where it left the C code on stdout, which is for the result
+    quiet = contextlib.redirect_stdout(sys.stderr) if full else contextlib.nullcontext()
     try:
-        path = run_fit(home, no_prior=no_prior, without=without, full=full, wait_s=LOCK_WAIT_S)
+        with quiet:
+            path = run_fit(home, no_prior=no_prior, without=without, full=full, wait_s=LOCK_WAIT_S)
     except FitBusy:
         return output.fail(f"another fit has held {home / 'fits'} for more than {int(LOCK_WAIT_S)} s; "
                            "try again later or use --background", output.EXIT_LOCKED)
@@ -151,6 +187,10 @@ def fit(args: argparse.Namespace) -> int:
         return output.fail(str(exc), output.EXIT_NOT_FOUND)
     except NothingToFit as exc:
         return output.fail(str(exc), output.EXIT_USER)
+    except Exception as exc:
+        if not (full and _in_pymc_check(exc)):
+            raise
+        return _pymc_check_failed(home, exc)
     summary = _summary(path)
     if as_json:
         output.emit_json(SCHEMA, summary)

loopmath/belief/design.py

@@ -464,10 +464,12 @@ def source_label(doc: dict) -> str:
     ext = run.get("ext") or {}
     share = ext.get("dev.loopmath.share")
     if isinstance(share, dict):
-        # the importer writes `source` and `task.org` as `shared:<org_hash>` already: never prefix twice
+        # the importer writes `source` and `task.org` as `shared:<org_hash>` already: never prefix twice. With no
+        # org at all the source is `shared`, the name `fit --without shared` takes (0.2.3, 22X review N1)
         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:")
+               or "")
+        name = str(org).removeprefix("shared:")
+        return f"shared:{name}" if name and name != "shared" else "shared"
     src = (run.get("task") or {}).get("source")
     kind = src.get("kind") if isinstance(src, dict) else src
     kind = str(kind or "").strip().lower()

loopmath/belief/fit.py

@@ -72,7 +72,7 @@ REASON_NOTES = {
     "attempt without usable cost": "crashed or no usage reported",
     "attempt outside the workflow": "a model attempt at no piece of the run's workflow",
     "duplicate run id": "the same run found twice",
-    SHIPPED_COPY: "your store has the same run id; your copy is used",
+    SHIPPED_COPY: "this run ships with loopmath and is also in your store, so it counts once, as yours",
     "no configuration": "the run records no workflow and settings",
     "workflow ref not resolved": "a workflow this version does not know",
     "workflow has no pieces": "an empty workflow",
@@ -526,7 +526,8 @@ def fit(home: Path, *, no_prior: bool = False, without: tuple[str, ...] = (), fu
     with fit_lock(home, wait_s):
         remove_partials(home)
         config = _read_config(home)
-        weight = float(config.get("benchmark_prior_weight", prior_data.BENCHMARK_PRIOR_WEIGHT))
+        raw_weight = config.get("benchmark_prior_weight")  # unset: each benchmark's own weight (spec 04 section 5)
+        weight = None if raw_weight is None else float(raw_weight)
         try:
             features, features_error = FeatureSet.from_config(config.get("features")), None
         except FeatureConfigError as exc:  # a hand-edited config.toml: fit with the built-ins, say why
@@ -550,9 +551,10 @@ def fit(home: Path, *, no_prior: bool = False, without: tuple[str, ...] = (), fu
             raise UnknownSource(unknown_source_message(unknown, known))
         if not any(hr.rows for hr in heads_rows.values()):
             raise NothingToFit(_nothing_to_fit(no_prior, without, dropped))
-        specs = []
+        specs, bench_weights = [], {}
         if not no_prior and "benchmark" not in without:
             specs = prior_data.benchmark_factors(benchmarks, weight=weight)
+            bench_weights = prior_data.benchmark_weights(benchmarks, weight=weight)
         seed_key = input_key(heads_rows, specs, {"no_prior": no_prior, "without": sorted(without), "eb": eb,
                                                   "benchmark_prior_weight": weight})
         forest = Forest()
@@ -604,7 +606,7 @@ def fit(home: Path, *, no_prior: bool = False, without: tuple[str, ...] = (), fu
             "seed_key": seed_key, "timebox_effort": design_rows.TIMEBOX_EFFORT_COST,
             "timebox_terms": list(design_rows.TIMEBOX_LEVELS),
             "options": {"no_prior": no_prior, "without": list(without), "full": full, "eb": eb,
-                        "benchmark_prior_weight": weight},
+                        "benchmark_prior_weight": weight, "benchmark_weights": bench_weights},
             "runs_by_source": runs_by_source,
             "n_runs": {"prior": sum(v for k, v in runs_by_source.items() if k != "user"),
                        "user": runs_by_source.get("user", 0)},

loopmath/belief/priors.py

@@ -10,8 +10,11 @@
   version nodes: success head, the logit gap to the benchmark's reference model with variance
   `1 / (w p (1 - p))`; cost head, the log cost ratio with variance `1 / w`; tokens head
   (`kind = "tokens"`, published total tokens for the evaluation), the log token ratio
-  with variance `1 / w`. `w` is config `benchmark_prior_weight` (default 5): one benchmark
-  result counts like about 5 runs.
+  with variance `1 / w`. `w` is one model's share of the benchmark's weight `w_b` (0.2.3,
+  lane 23K): the `weight` of its `[[benchmark]]` table (default 5, about 5 runs), shared by
+  the model's k results on that benchmark, so each gets `w_b / k` and a model with five
+  efforts pulls as hard in total as a model with one. Config `benchmark_prior_weight`, when
+  set, is one `w_b` for every benchmark; 0 turns the factors off.
 """
 
 from __future__ import annotations
@@ -91,8 +94,30 @@ def _model_terms(model: str, effort: str | None, sign: float) -> list[tuple[str,
     return terms
 
 
-def benchmark_factors(path: Path | None = None, *, weight: float = BENCHMARK_PRIOR_WEIGHT) -> list[FactorSpec]:
-    """Prior factors from `benchmarks.toml`. A missing file gives no factors."""
+def benchmark_weights(path: Path | None = None, *, weight: float | None = None) -> dict[str, float]:
+    """Each benchmark's weight `w_b`: `weight` for every benchmark when it is given (config
+    `benchmark_prior_weight`), else the benchmark's own `weight` field, else 5. Empty for a missing file."""
+    path = path or benchmark_path()
+    if not path.is_file():
+        return {}
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    return {str(b["id"]): _weight_of(b, weight) for b in data.get("benchmark") or [] if b.get("id")}
+
+
+def _weight_of(bench: dict, weight: float | None) -> float:
+    if weight is not None:
+        return float(weight)
+    own = bench.get("weight")
+    return float(own) if isinstance(own, (int, float)) and not isinstance(own, bool) else BENCHMARK_PRIOR_WEIGHT
+
+
+def benchmark_factors(path: Path | None = None, *, weight: float | None = None) -> list[FactorSpec]:
+    """Prior factors from `benchmarks.toml`. A missing file gives no factors.
+
+    `weight` (config `benchmark_prior_weight`) overrides every benchmark's own weight; None reads
+    each benchmark's `weight`. A model's k results on one benchmark share its weight: each factor
+    has weight `w_b / k` (B1). A benchmark with weight 0 or less gives no factors.
+    """
     path = path or benchmark_path()
     if not path.is_file():
         return []
@@ -103,11 +128,15 @@ def benchmark_factors(path: Path | None = None, *, weight: float = BENCHMARK_PRI
     for bid, bench in benches.items():
         kind = str(bench.get("kind") or "success")
         ref = canonical_model_id(str(bench.get("reference") or ""))
+        w_b = _weight_of(bench, weight)
+        if w_b <= 0:
+            continue
         rows = [r for r in results if r["benchmark"] == bid]
         ref_rows = [r for r in rows if canonical_model_id(str(r["model"])) == ref]
         if not ref_rows:
             continue
         ref_value = float(ref_rows[0]["value"])
+        by_model: dict[str, list[tuple[str, list, float, dict]]] = {}  # model -> (head, terms, mean, row) per result
         for r in rows:
             model = canonical_model_id(str(r["model"]))
             if model == ref:
@@ -117,14 +146,24 @@ def benchmark_factors(path: Path | None = None, *, weight: float = BENCHMARK_PRI
             terms = _cancel(terms)
             if not terms:
                 continue
-            note = f"{bid}: {model} {value} against {ref} {ref_value} ({r.get('url', '')}, {r.get('date', '')})"
             if kind == "success":
                 p = min(max(value, 0.01), 0.99)
                 p_ref = min(max(ref_value, 0.01), 0.99)
                 gap = math.log(p / (1 - p)) - math.log(p_ref / (1 - p_ref))
-                out.append(FactorSpec("success", terms, gap, 1.0 / (weight * p * (1 - p)), note))
+                by_model.setdefault(model, []).append(("success", terms, gap, r))
             elif kind in ("cost", "tokens") and value > 0 and ref_value > 0:  # Tokens feed the tokens head only
-                out.append(FactorSpec(kind, terms, math.log(value / ref_value), 1.0 / weight, note))
+                by_model.setdefault(model, []).append((kind, terms, math.log(value / ref_value), r))
+        for model, items in by_model.items():
+            w = w_b / len(items)  # one budget per model and benchmark (B1)
+            share = f"weight {w_b:g} over {len(items)}" if len(items) > 1 else f"weight {w_b:g}"
+            for head, terms, mean, r in items:
+                note = (f"{bid}: {model} {float(r['value'])} against {ref} {ref_value} ({share}; "
+                        f"{r.get('url', '')}, {r.get('date', '')})")
+                if head == "success":
+                    p = min(max(float(r["value"]), 0.01), 0.99)
+                    out.append(FactorSpec("success", terms, mean, 1.0 / (w * p * (1 - p)), note))
+                else:
+                    out.append(FactorSpec(head, terms, mean, 1.0 / w, note))
     return out
 
 

loopmath/belief/state.py

@@ -792,10 +792,13 @@ class FitState:
                                    gate_pass=res[hg] if hg is not None else None, rounds=res[hr],
                                    cost_per_round=Money(usd=res[hpr[0]], tokens=res[hpr[1]]) if hpr else None)
             for piece, (hu, ht, hg, hr, hpr) in handles.items()}
+        # The typical run (0.2.3): the median of the same simulated runs, one per draw, the 80% range is read from
+        run_usd = dataclasses.replace(res[h_run[1]], median=float(np.median(rd.sim_usd)))
+        run_tokens = dataclasses.replace(res[h_run[2]], median=float(np.median(rd.sim_tokens)))
         pred = Prediction(
             config=cfg.id,
             p_success=res[h_run[0]],
-            cost=Money(usd=res[h_run[1]], tokens=res[h_run[2]]),
+            cost=Money(usd=run_usd, tokens=run_tokens),
             ell=Money(usd=res[h_run[3]], tokens=res[h_run[4]]),
             rounds=res[h_run[5]],
             per_piece=per_piece,

loopmath/builder/context.py

@@ -21,6 +21,7 @@ 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 ..store import run_names
 from ..recommend.curve import accepted_within
 from ..recommend.engine import Recommendation, r6
 from ..recommend.storeread import Conf
@@ -137,7 +138,7 @@ def build_session(args: argparse.Namespace) -> tuple[Session | None, int]:
         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)],
-                               **offered_kw(offered))
+                               own_runs=storeread.own_runs(home), **offered_kw(offered))
         rec.task = task
         start = None
         if getattr(args, "start", None):
@@ -221,7 +222,7 @@ def recorded_runs(home: Any) -> list[tuple[Configuration, int]]:
                 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
+        doc = storeread.read_json(home / "runs" / run_names.file_name(run_of[cfg_id])) 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:
@@ -305,6 +306,17 @@ def candidate_entry(rec: Recommendation, c: Any) -> dict[str, Any]:
             "origin": c.origin, **rec.search_fields(c.config.id)}
 
 
+def rescue_entry(session: Session, cfg: Configuration) -> dict[str, Any]:
+    """The rescue workflow as a candidate when the search did not offer it (22W N1, 0.2.3): predicted as a
+    candidate is, under the recommendation's task, rule and rescue, with origin `rescue`."""
+    rec = session.rec
+    bands: dict[str, Any] = {}
+    preds, medians = engine.predict_with_medians(session.belief, session.task, [cfg], session.rule, rec.rescue, bands)
+    view = with_numbers(rec, medians=medians, bands=bands)
+    return {"config": cfg.to_dict(), "label": rec.label(cfg), "numbers": numbers_of(view, preds[0]),
+            "origin": "rescue", **rec.search_fields(cfg.id)}
+
+
 def context_payload(session: Session) -> dict[str, Any]:
     """`GET /api/context` (spec 02, `builder`), built once per session."""
     if session.context is not None:
@@ -329,6 +341,10 @@ def context_payload(session: Session) -> dict[str, Any]:
         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)]
+    candidates = [candidate_entry(rec, c) for c in top]
+    fix = rec.rescue_config
+    if fix is not None and fix.id not in retired and rec.by_id(fix.id) is None:
+        candidates.append(rescue_entry(session, fix))
     session.context = {
         "schema": SCHEMA,
         "task": C.task_block(rec.task, session.belief),
@@ -339,9 +355,10 @@ def context_payload(session: Session) -> dict[str, Any]:
         "rescue": core["rescue"],
         "reference": reference,
         "choices": choices,
-        "candidates": [candidate_entry(rec, c) for c in top],
+        "candidates": candidates,
         "catalog": catalog(session),
         "start": session.start.to_dict() if session.start is not None else None,
+        "own_runs": rec.own_runs,  # 0.2.3: the user's recorded runs; 0 leads each run cost with the typical run
     }
     return session.context
 

loopmath/builder/predict.py

@@ -136,6 +136,12 @@ def clean(obj: dict[str, Any]) -> tuple[dict[str, Any], list[dict[str, Any]]]:
     return {**obj, "id": None, "settings": settings}, notes
 
 
+# P3-21 (0.2.4): a review gate that names a repairer at a round limit of 1 is one of loopmath's own shapes (reviewed
+# once; the search builds it and may recommend it). The workflow file check warns about it; the builder page instead
+# says on the gate what 1 round means, so that warning is not shown here.
+REVIEW_ONCE = "budget_rounds is 1"
+
+
 def parse_config(obj: Any, models: dict[str, int]
                  ) -> tuple[Configuration | None, list[dict[str, Any]], list[dict[str, Any]]]:
     """(configuration, errors, warnings); the configuration is None when it does not read at all."""
@@ -158,7 +164,8 @@ def parse_config(obj: Any, models: dict[str, int]
             errors.append(err(p.id, f"piece {p.id!r}: model {s.model!r} is a retired or unknown model; "
                                     f"pick one of {known}"))
     if not errors:
-        warnings += notes_of(workflow_warnings(cfg.workflow) + settings_warnings(cfg.settings), cfg)
+        shown = [w for w in workflow_warnings(cfg.workflow) if REVIEW_ONCE not in w]
+        warnings += notes_of(shown + settings_warnings(cfg.settings), cfg)
     return cfg, errors, warnings
 
 

loopmath/cli.py

@@ -5,27 +5,26 @@ Verbs:
   scan             explain where implicit scanning occurs
   adapt            emit OCP v0.2 from a registered ADE adapter
   validate-prices  check a price table's schema, staleness and todo flags
-  analyze-e0       the frozen E0 corpus walkdown
   prices           show the active price table
   graph            the workflow graph of one or more workspaces (ocp, json, dot, run, html: self-contained interactive HTML viewer)
-  research         E1 v2 cost model: research fit, research transfer-test (needs the [bayes] extra)
-  verify-receipts  verify an E2 spend ledger and frozen preregistration
+  research         research data folders: research fit, research transfer-test (the bayes extra), research analyze-e0 (the e0 extra)
+  verify-receipts  check that the receipts in your store are whole and scored right (or give a research ledger file)
 
 0.1.0 verbs (design/0.1/02-commands.md, registered in cli_registry.py):
-  plan:    task-types  workflows  recommend  plan
-  record:  run start|attempt|artifact|finish|import  outcome  budget  config
+  plan:    task-types  workflows  recommend  builder  plan
+  record:  run start|record|import|attempt|artifact|finish|sessions  outcome  budget  config
   learn:   fit  onboard  share
   view:    runs  posterior  status  report  doctor  skill  ocp
 
-No verb in this CLI makes a network call. Verbs write only to the store
-($LOOPMATH_HOME, default ~/.loopmath, which also holds the parse cache) and to
-paths the user names.
+No verb in this CLI connects to another machine; builder serves on 127.0.0.1 only.
+Verbs write only to the store ($LOOPMATH_HOME, default ~/.loopmath, which also
+holds the parse cache and the fit --full compile folder), to the skill folders
+skill install names, and to paths the user names.
 """
 
 from __future__ import annotations
 
 import argparse
-import importlib.util as _importlib_util
 import sys
 import time
 from types import ModuleType
@@ -79,6 +78,7 @@ class _CliModule(ModuleType):
 sys.modules[__name__].__class__ = _CliModule
 
 DEFAULT_SINCE_DAYS = 14.0
+_ANALYZE_SCHEMA = "loopmath.analyze/1"
 
 
 def _counted_noun(count: int, singular: str, plural: str | None = None) -> str:
@@ -185,6 +185,18 @@ def analyze(args: argparse.Namespace) -> int:
         ci=args.ci,
     )
     result["ratio_pair"] = _extremes_ratio(df, result, price_mod)
+    result["min_n"] = args.min_n
+
+    if getattr(args, "json", False):
+        from .output import emit_json
+
+        grading = list(grade_mod.grading_report(records, coverage)) if args.grading else None
+        emit_json(_ANALYZE_SCHEMA, _cli_support.analyze_payload(
+            result, diag=diag, coverage=coverage, price_lines=price_lines, grading=grading,
+            walkdown=surface_mod.walkdown(result)))
+        if not args.quiet:
+            print(f"ran in {time.time() - t0:.1f} s", file=sys.stderr)
+        return 0
 
     print(
         terminal.render(
@@ -246,7 +258,7 @@ def _add_graph(sub) -> None:
     p.add_argument("--workspace", action="append", default=[], help="native workspace name to include (repeatable; required unless --ocp is used)")
     p.add_argument("--ocp", action="append", default=[], metavar="FILE", help="read an OCP document (v0.2 or later) as a graph source (repeatable)")
     p.add_argument("--format", type=_cli_support._graph_format, choices=GRAPH_FORMATS, default="ocp", help="ocp (OCP v0.3, default), json (internal dagr_graph), dot (Graphviz), run (herdr-dagr contract v3 run file), html (self-contained interactive HTML viewer)")
-    p.add_argument("--out", default=None, help="write here instead of stdout (must be inside the git worktree of the current directory; parent directories are created)")
+    p.add_argument("--out", default=None, help="write here instead of stdout (any path; missing folders are created; an existing file is replaced)")
     p.add_argument("--privacy", choices=("metadata_only", "full"), default="metadata_only", help="OCP privacy profile (default metadata_only)")
     p.add_argument("--logs", default=None, help="parse this path instead of the default log roots")
     p.add_argument(
@@ -259,7 +271,8 @@ def _add_graph(sub) -> None:
     p.add_argument("--limit", type=int, default=None, help="stop after N files per harness")
     p.add_argument("--no-cache", action="store_true", help="reparse everything, ignoring the cache")
     p.add_argument("--prices", default=None, help="price table to use instead of the packaged one")
-    p.add_argument("--quiet", action="store_true", help="suppress progress output on stderr; exclusion counters always print")
+    p.add_argument("--quiet", action="store_true", help="suppress progress output on stderr")
+    p.add_argument("--verbose", action="store_true", help="also print every count of what was skipped, excluded or could not be placed")
     p.set_defaults(func=graph_verb)
 
 
@@ -279,7 +292,7 @@ def adapt_verb(args: argparse.Namespace) -> int:
 
     out_path = None
     if args.out:
-        out_path, err = _resolve_out(args.out)
+        out_path, err = _resolve_out(args.out, "out.ocp.json")
         if err:
             print(err, file=sys.stderr)
             return 2
@@ -302,9 +315,18 @@ def adapt_verb(args: argparse.Namespace) -> int:
 
     adapter = adapter_type()
     adapter.configure_services(default_adapter_services())
-    doc = adapter.emit(selection)
+    try:
+        doc = adapter.emit(selection)
+    except (OSError, ValueError) as exc:  # a store path it cannot read: say so, no traceback
+        print(f"error: adapt {args.name}: {exc}", file=sys.stderr)
+        return 1
     if not isinstance(doc, dict):
         raise TypeError(f"adapter {args.name!r} emit() must return a dict")
+    if not doc.get("nodes") and not doc.get("attempts"):
+        where = ", ".join(str(p) for p in selection.stores) if selection.stores else "its default location"
+        print(f"error: adapt {args.name} found no sessions in {where}; nothing written. Point --store at the "
+              f"{args.name} data, or widen --since, --until, --session and --workspace", file=sys.stderr)
+        return 1
     from .ocp import version_at_least
 
     if not version_at_least(doc, "0.2"):
@@ -323,7 +345,7 @@ def adapt_verb(args: argparse.Namespace) -> int:
 def _add_adapt(sub) -> None:
     p = sub.add_parser("adapt", help="emit OCP v0.2 from an ADE store (loopmath ocp migrate converts it to v0.3)")
     p.add_argument("name", metavar="NAME", help="registered adapter name")
-    p.add_argument("--out", default=None, help="write here instead of stdout (must be inside the git worktree of the current directory; parent directories are created)")
+    p.add_argument("--out", default=None, help="write here instead of stdout (any path; missing folders are created; an existing file is replaced)")
     p.add_argument("--store", action="append", default=[], metavar="PATH", help="use this store path instead of discovery (repeatable)")
     p.add_argument("--session", action="append", default=[], metavar="ID", help="include this session id (repeatable; default: all)")
     p.add_argument("--workspace", action="append", default=[], metavar="WORKSPACE", help="include this workspace (repeatable; default: all)")
@@ -371,6 +393,9 @@ def _add_analyze(sub) -> None:
     p.add_argument("--tokens", action="store_true", help="rank by output tokens instead of dollars")
     p.add_argument("--grading", action="store_true", help="print which rule graded what")
     p.add_argument("--quiet", action="store_true", help="suppress progress and timing on stderr")
+    p.add_argument("--home", default=None, metavar="PATH", help="store root whose cache/ holds the log parse cache "
+                   "(default: $LOOPMATH_HOME or ~/.loopmath; LOOPMATH_CACHE_DIR wins); analyze writes nothing else")
+    p.add_argument("--json", action="store_true", help="print one JSON object on stdout")
     p.set_defaults(func=analyze)
 
 
@@ -385,11 +410,18 @@ def _add_validate_prices(sub) -> None:
 def _add_fit(sub) -> None:
     from .research_defaults import E1A_OBSERVE, SEED
 
-    research = sub.add_parser("research", help="E1 research verbs: fit, transfer-test (needs the [bayes] extra)")
+    research = sub.add_parser(
+        "research",
+        help="verbs for research data folders that are not part of the package (loopmath research --help)",
+        description="Verbs for research data folders that are not part of the package: sweep run records "
+                    "(research fit, research transfer-test; they need the bayes extra) and a session corpus "
+                    "(research analyze-e0; it needs the e0 extra). Name a folder with --sweep-dir or --corpus, "
+                    "LOOPMATH_SWEEP_DIR or LOOPMATH_E0_CORPUS, or config research.sweep_dir or research.e0_corpus.",
+    )
     rsub = research.add_subparsers(dest="research_command", required=True)
     for name, fn, helptext in (
-        ("fit", fit_verb, "fit the E1 cost model on the sweep data"),
-        ("transfer-test", transfer_test_verb, "score held-out cells from a fit"),
+        ("fit", fit_verb, "fit the research cost model on sweep run records"),
+        ("transfer-test", transfer_test_verb, "fit on some cells of the sweep and score the held-out ones"),
     ):
         p = rsub.add_parser(name, help=helptext)
         p.add_argument("--sweep-dir", default=None, help="sweep run records directory (default: LOOPMATH_SWEEP_DIR, then research.sweep_dir in config)")
@@ -405,10 +437,20 @@ def _add_fit(sub) -> None:
         else:
             p.add_argument("--ci", type=float, default=0.80, help="central interval for held-out coverage (default 0.80)")
         p.set_defaults(func=fn)
+    from .e0 import verb as _e0_verb
+
+    _e0_verb.register(rsub)
 
 
 def verify_receipts_verb(args: argparse.Namespace) -> int:
-    """Verify an E2 receipt ledger and print one machine-friendly result."""
+    """No ledger: check the store's receipts. A ledger path: verify that research receipt ledger."""
+    if args.ledger is None:
+        from .store.home import Store
+        from .store.verify import verify_lines, verify_store
+
+        res = verify_store(Store(args.home))
+        print("\n".join(verify_lines(res)))
+        return 1 if res["failed"] else 0
     from .receipts import ReceiptViolation, verify_receipts
 
     try:
@@ -421,18 +463,20 @@ def verify_receipts_verb(args: argparse.Namespace) -> int:
 
 
 def _add_verify_receipts(sub) -> None:
-    p = sub.add_parser("verify-receipts", help="verify an E2 receipt ledger")
+    p = sub.add_parser("verify-receipts", help="check that the receipts in your store are whole and scored right "
+                       "(or give a research ledger file)")
     p.add_argument(
         "ledger",
         nargs="?",
-        default="e2-receipts.jsonl",
-        help="receipt ledger (default: e2-receipts.jsonl)",
+        default=None,
+        help="a research receipt ledger to verify instead (e.g. e2-receipts.jsonl)",
     )
     p.add_argument(
         "--frozen",
         default=None,
-        help="checksum file (default: FROZEN.txt beside the ledger)",
+        help="with a ledger: its checksum file (default: FROZEN.txt beside the ledger)",
     )
+    p.add_argument("--home", default=None, metavar="PATH", help="the store (default: $LOOPMATH_HOME or ~/.loopmath)")
     p.set_defaults(func=verify_receipts_verb)
 
 
@@ -455,15 +499,14 @@ def main(argv: list[str] | None = None) -> int:
 
     _registry.register(sub)
 
-    if _importlib_util.find_spec("matplotlib") is not None:
-        # The E0 walkdown verb draws figures, so running it needs matplotlib.
-        # SPEC section 2's light-core rule says `analyze` runs on numpy and
-        # pandas, so matplotlib lives in the `e0` extra and this verb is simply
-        # absent without it. It registers from e0/verb.py without importing the
-        # walkdown, so no other command pays for pandas and matplotlib.
-        from .e0 import verb as _e0_verb
+    # The E0 walkdown draws figures, so running it needs matplotlib (the `e0`
+    # extra; SPEC section 2's light core is numpy and pandas). It is listed under
+    # `loopmath research`; the old top-level name stays callable, off the list.
+    # It registers from e0/verb.py without importing the walkdown, so no other
+    # command pays for pandas and matplotlib.
+    from .e0 import verb as _e0_verb
 
-        _e0_verb.register(sub)
+    _e0_verb.register(sub, listed=False)
 
     try:
         _add_fit(sub)