quantred 2.4.0__py3-none-any.whl

quantred/services/campaign.py

@@ -0,0 +1,381 @@
+"""What validated a config, assembled from what was already recorded.
+
+Promoting the winning row of a walk-forward captures the parameters and loses the
+recipe. But a walk-forward is not one row — it is a *validation recipe* (the folds, the
+embargo, the objective, the search method, the book it searched at) plus a chosen
+parameter set plus the universe that was actually resolved. Without the recipe the
+config cannot say what validated it, and "this passed a walk-forward" is not a fact
+anybody can check.
+
+None of this is re-derived and none of it is re-run. The recipe is in the journal,
+where it was written as the trial's dedup identity; the universe is in the journal, in
+full, because the store keeps only its hash. This reads both back.
+
+**Three kinds of thing, labelled as such, because they age differently.**
+
+``recipe`` is *how it was validated* — reusable, still meaningful next year, and the
+thing you would repeat to check the claim.
+
+``evidence`` is *what was measured* — scoped to an accounting era and never valid
+outside it. When ``ACCOUNTING_VERSION`` moves, the recipe survives unchanged and every
+number here becomes a historical curiosity. Marking the boundary in the artifact is
+what stops the two being read as one.
+
+``metadata`` is *about the record itself* — where it came from, what is still
+recoverable, what was never captured.
+
+A section that could not be assembled says so with a reason. Absent is never rendered
+as empty, and an artifact that quietly omits a section it failed to build claims more
+completeness than it has.
+"""
+
+from typing import Any, Dict, List, Optional
+
+#: The label on each block. Kept as data rather than prose so a reader — or an agent —
+#: can filter on it: after an accounting bump, everything marked ``evidence`` is stale
+#: and everything marked ``recipe`` is not.
+RECIPE = "recipe"
+EVIDENCE = "evidence"
+METADATA = "metadata"
+
+#: Reserved keys inside a recorded params/recipe dict. They are the dedup identity's
+#: own bookkeeping, not knobs anybody set.
+_RESERVED_PREFIX = "_"
+
+
+def _split_recipe(recorded: Optional[Dict[str, Any]]) -> Dict[str, Any]:
+    """A recorded dedup recipe split into the knobs and the folded keys.
+
+    The cost model and the book limits are folded into the recipe as reserved keys
+    because they change what a validation *means*, but they are not search settings and
+    reading them as such would be misleading.
+    """
+    recorded = dict(recorded or {})
+    folded = {k: v for k, v in recorded.items() if k.startswith(_RESERVED_PREFIX)}
+    knobs = {k: v for k, v in recorded.items() if not k.startswith(_RESERVED_PREFIX)}
+    return {"settings": knobs, "folded": folded}
+
+
+def campaign_material(store, trial_id: str, *, journal_path: Optional[Any] = None) -> Dict[str, Any]:
+    """Everything recorded about what validated one trial, as one labelled block.
+
+    Takes an open store rather than opening one — the CLI and the MCP server both reach
+    this through the handle they already have, and a fourth way of opening the trial
+    store is the last thing this codebase needs.
+    """
+    from quantred.engine.backtest import ACCOUNTING_VERSION
+    from quantred.services.audit import journal_record_for_trial, research_record_for_trial
+
+    material: Dict[str, Any] = {"available": False, "reason": "", "trial_id": trial_id}
+
+    from quantred.store.trials import AmbiguousTrialId
+
+    try:
+        resolved = store.resolve_id(trial_id)
+    except AmbiguousTrialId as exc:
+        material["reason"] = str(exc)
+        return material
+    row = store.row_for(resolved) if resolved else None
+    if row is None:
+        material["not_indexed"] = True
+        material["reason"] = (
+            f"no trial with id {trial_id!r} is indexed. "
+            "Its journal line may still exist — "
+            "`trials rebuild` reindexes from the journal."
+        )
+        return material
+
+    trial_id = material["trial_id"] = resolved
+    # `audit_log` flattens a trial's extra fields onto the record rather than nesting
+    # them under a key, so `dedup_params`, `returns` and `trades` sit at the top level
+    # beside `inputs`. Printed once rather than inferred from the writer's signature:
+    # assuming a nested `extra` compiled, passed, and reported every recipe as absent.
+    record = journal_record_for_trial(trial_id, journal_path)
+    if record is None and row.get("kind") == "research":
+        record = research_record_for_trial(trial_id, journal_path)
+    inputs = (record or {}).get("inputs") or {}
+
+    accounting = row.get("accounting")
+    material.update(
+        {
+            "available": True,
+            "kind": row.get("kind"),
+            "strategy": row.get("strategy"),
+            RECIPE: _recipe_section(row, inputs, record),
+            EVIDENCE: _evidence_section(
+                store, row, inputs, trial_id, accounting, ACCOUNTING_VERSION, record=record
+            ),
+            METADATA: _metadata_section(row, inputs, record, trial_id),
+        }
+    )
+    return material
+
+
+#: Context facts that describe how a run was set up, in the order a reader wants them.
+_CONTEXT_FACTS = ("capital", "scanner", "scan_as_of", "cache")
+
+
+def _context_section(inputs: Dict[str, Any], record: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+    """The recorded run context, with every fact carrying whether it was recorded.
+
+    Each fact reports ``recorded`` rather than being present-or-missing, so a reader -
+    or an agent - can tell "this run used no scanner" from "nobody wrote down whether it
+    did". Every trial predating this block reads as the second, which is what it is: the
+    fact was never captured, and defaulting it would put a capital or a cache policy in
+    the record that nobody chose.
+
+    A verdict trial keeps its scanner in its identity (``_verdict.scanner``) rather than
+    in the context block, so that is read as the recorded fact: reporting such a trial's
+    scanner as not recorded sent a reader to guess at a value the journal holds.
+    """
+    context = dict(inputs.get("context") or {})
+    if "scanner" not in context:
+        identity = (record or {}).get("dedup_params") or (record or {}).get("resolved_config") or {}
+        scanner = (identity.get("_verdict") or {}).get("scanner")
+        if scanner:
+            context["scanner"] = scanner
+    return {fact: {"recorded": fact in context, "value": context.get(fact)} for fact in _CONTEXT_FACTS}
+
+
+def _recorded(inputs: Dict[str, Any], key: str) -> Dict[str, Any]:
+    """One context fact off a trial's journal inputs, with its recorded status.
+
+    Reads the *journal* rather than the store row: the context is not indexed, because
+    nothing queries on it and duplicating it into a column would be a second copy of a
+    fact the journal already holds.
+    """
+    context = (inputs or {}).get("context") or {}
+    return {"recorded": key in context, "value": context.get(key)}
+
+
+def _recipe_section(row, inputs, record) -> Dict[str, Any]:
+    """How it was validated. Survives an accounting bump unchanged."""
+    section: Dict[str, Any] = {
+        "kind": RECIPE,
+        "note": "how this was validated — reusable, and unaffected by an accounting bump",
+        "window": inputs.get("window") or {"start": row.get("window_start"), "end": row.get("window_end")},
+        "objective": inputs.get("objective") or None,
+        # How the run was set up, for the parts that are *not* its identity: the capital
+        # it ran at, the scanner and as-of clock its universe came through, the cache
+        # policy its bars were read under. Labelled separately from `validation` because
+        # nothing here is hashed - two runs differing only in these keys are one trial to
+        # the memo, which a reader comparing them needs to know.
+        "context": _context_section(inputs, record),
+        # The universe that was actually resolved, and the list it was resolved *from*.
+        # The store keeps only a hash of the first and nothing of the second, so this is
+        # the only place a reader gets them back - and without it the module's own
+        # claim to read the universe back was false, and a config's symbols could
+        # contradict the campaign with nothing able to notice.
+        "universe": {
+            "symbols": list(inputs.get("symbols") or []) or None,
+            "candidate_symbols": list(inputs.get("candidate_symbols") or []) or None,
+        },
+    }
+    if record is None:
+        # The store knows the trial happened and the journal line is where the recipe
+        # lives. Saying which half is missing beats an empty recipe that reads as "this
+        # was validated with no settings".
+        section["available"] = False
+        section["reason"] = (
+            "the journal line for this trial could not be read, and the recipe is only "
+            "recorded there — the store keeps a hash of it, not the recipe itself"
+        )
+        return section
+
+    if row.get("kind") == "research":
+        # The line was found; what it lacks is a per-trial recipe, which a research round
+        # does not have - its validation settings belong to the session, journaled once on
+        # the `research:session_start` line. "Could not be read" would send a reader
+        # looking for a corrupt journal.
+        section["available"] = False
+        section["reason"] = (
+            "a research round has no validation recipe of its own: the settings it was "
+            "validated under are the session's, journaled on its `research:session_start` "
+            f"line (session {inputs.get('session_id') or row.get('session_id') or 'unknown'}). "
+            "This round's line records its params, gate report and out-of-sample aggregate"
+        )
+        return section
+
+    dedup = record.get("dedup_params")
+    if dedup is None:
+        # Most kinds omit it because `params` already serves both roles; a backtest's
+        # identity *is* its parameters. Only a search has a recipe distinct from them.
+        section["available"] = False
+        section["reason"] = (
+            f"a {row.get('kind')!r} trial records no separate validation recipe — its "
+            "identity is its parameters, which are the config's own `params`"
+        )
+        # The cost model and book folded into those parameters are still named, in the
+        # same place a recipe names them: without this a config written from this block
+        # over MCP carried no `cost` for a backtest, where `trials promote` did.
+        params = _recorded_params(row, record)
+        if params:
+            folded = _split_recipe(params)["folded"]
+            if folded:
+                section["folded_into_identity"] = folded
+        return section
+
+    split = _split_recipe(dedup)
+    section.update(
+        {
+            "available": True,
+            "validation": split["settings"],
+            # Named rather than dropped: these are why two validations with identical
+            # settings can still be different validations.
+            "folded_into_identity": split["folded"],
+        }
+    )
+    return section
+
+
+def _recorded_params(row, record: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+    """A trial's recorded params: the journal line's, else the index row's."""
+    import json
+
+    params = (record or {}).get("params")
+    if isinstance(params, dict):
+        return params
+    try:
+        parsed = json.loads(row.get("params_json") or "null")
+    except (TypeError, ValueError):
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def _parse_metrics(row) -> Optional[Dict[str, Any]]:
+    """A row's stored metric block, parsed. ``None`` when there is none - never ``{}``,
+    which would read as a trial that measured nothing."""
+    import json
+
+    raw = row.get("metrics")
+    if isinstance(raw, dict):
+        return raw or None
+    try:
+        parsed = json.loads(row.get("metrics_json") or "{}")
+    except (TypeError, ValueError):
+        return None
+    return parsed or None
+
+
+def _evidence_section(store, row, inputs, trial_id, accounting, current, record=None) -> Dict[str, Any]:
+    """What was measured. Scoped to one accounting era and worthless outside it."""
+    from quantred.services.audit import holdout_from_record
+
+    strategy, universe_hash = row.get("strategy"), row.get("universe_hash")
+    family = (
+        store.family_count_by_hash(strategy, universe_hash, accounting)
+        if strategy and universe_hash and accounting is not None
+        else None
+    )
+    section: Dict[str, Any] = {
+        "kind": EVIDENCE,
+        "note": (
+            "what was measured, under accounting "
+            f"v{accounting} — not comparable with a run on a different version"
+        ),
+        "accounting": accounting,
+        "current_accounting": current,
+        "comparable_with_current_engine": accounting == current,
+        "trial_ids": [trial_id],
+        # The raw row carries `metrics_json`, a string. `get_trial` parses it; this
+        # reads the light row and has to do the same, or every materialised config
+        # records `metrics: null` for a trial that measured plenty.
+        "metrics": _parse_metrics(row),
+        # SQLite has no boolean, so the column is 0/1/NULL. A JSON artifact that says
+        # `"promotable": 1` invites a reader to treat the count-looking value as one.
+        "promotable": None if row.get("promotable") is None else bool(row.get("promotable")),
+        # Which probes ran and what they said. A probe absent here did not run, which is
+        # not the same as running and passing - the distinction the probe suite itself
+        # is built around, carried into the record.
+        "probes": _recorded(inputs, "probes"),
+        "family_n_trials": family,
+        # A walk-forward's holdout is evidence the index never kept; it lives only in the
+        # journal line. Other kinds have no such concept, so they carry no key at all.
+        **({"holdout": holdout_from_record(record)} if row.get("kind") == "walkforward" else {}),
+        "quarantined": bool(row.get("contaminated_at")),
+        "quarantine_reason": row.get("contamination_reason"),
+    }
+    if accounting != current:
+        section["staleness"] = (
+            f"recorded under accounting v{accounting}; this engine is v{current}. The "
+            "recipe above still applies — every number in this section does not"
+        )
+    # Later trials served from this one are part of the same evidence: the number was
+    # reused, and a reader tracing a config back deserves the whole chain.
+    reused = store.reused_by(row) or []
+    if reused:
+        section["trial_ids"].extend(r["id"] for r in reused)
+        section["reused_by"] = reused
+    return section
+
+
+def _seed(row, record) -> Dict[str, Any]:
+    """The seed this run used, and whether anybody wrote it down.
+
+    Read from the validation recipe first, because that is where it actually lives. The
+    ``seed`` column exists but only the research agent's session records ever populate
+    it — ``journal_trial`` has no seed parameter at all — so reading the column alone
+    reported ``None`` for every walk-forward driven from the CLI or MCP *while the same
+    block carried the real value two sections above*. A record that contradicts itself
+    about a fact it holds is worse than one that admits the fact is missing.
+
+    The column is still consulted, for the research-agent trials that do populate it and
+    may carry no recipe. Absent stays absent: a run whose seed nobody recorded reads as
+    unrecorded rather than as some default, which is the same rule every other fact in
+    this block follows.
+    """
+    recipe_seed = ((record or {}).get("dedup_params") or {}).get("seed")
+    stored = row.get("seed")
+
+    if recipe_seed is not None and stored is not None and recipe_seed != stored:
+        # Two records of one fact, disagreeing. The recipe is what defines the run, so
+        # it is the value — but reporting only the winner would hide that the record is
+        # internally inconsistent, and this block exists to make provenance checkable.
+        # Nothing here can tell which is the mistake, so it says both and neither is
+        # quietly dropped.
+        return {
+            "recorded": True,
+            "value": recipe_seed,
+            "from": "validation recipe",
+            "disagrees_with": {"value": stored, "from": "session record"},
+        }
+    if recipe_seed is not None:
+        return {"recorded": True, "value": recipe_seed, "from": "validation recipe"}
+    if stored is not None:
+        return {"recorded": True, "value": stored, "from": "session record"}
+    return {"recorded": False, "value": None, "from": None}
+
+
+def _metadata_section(row, inputs, record, trial_id) -> Dict[str, Any]:
+    """About the record: where it came from, and what is still recoverable.
+
+    Artifacts are named by the command that reads them rather than by a path. A config
+    is a portable thing and the reader may be running an installed copy with a state
+    root somewhere else entirely, so a filesystem path is the one form of this that is
+    guaranteed wrong for somebody.
+    """
+    from quantred.services.setup import invocation
+
+    stored: List[Dict[str, Any]] = []
+    for name, key, how in (
+        ("return series", "returns", invocation(f"trials compare {trial_id} <other-trial-id>")),
+        ("trade table", "trades", invocation(f"trials analyze {trial_id}")),
+        ("proposed book", "weights", invocation(f"trials show {trial_id}")),
+    ):
+        present = record is not None and record.get(key) is not None
+        if record is not None and key == "returns" and not present:
+            # A research round keeps its series under `inputs`, not at the top level.
+            present = (record.get("inputs") or {}).get("oos_returns") is not None
+        stored.append({"artifact": name, "recorded": present, "read_with": how if present else None})
+
+    return {
+        "kind": METADATA,
+        "note": "about this record — not a claim about the strategy",
+        "trial_id": trial_id,
+        "recorded_at": row.get("ts"),
+        "git_sha": row.get("git_sha"),
+        "seed": _seed(row, record),
+        "journal_line_found": record is not None,
+        "notes": _recorded(inputs, "notes"),
+        "artifacts": stored,
+    }

quantred/services/configs.py

@@ -0,0 +1,282 @@
+"""Config persistence service.
+
+Thin wrappers over :mod:`quantred.optimization.config_store` that return JSON-able
+results. Saving a config writes a file a human chooses to use; it **never**
+affects any running process.
+"""
+
+import dataclasses
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from quantred.optimization import config_store
+
+#: Device names Windows refuses as file names whatever the extension.
+_RESERVED_WINDOWS_NAMES = {
+    "CON",
+    "PRN",
+    "AUX",
+    "NUL",
+    *(f"COM{i}" for i in range(1, 10)),
+    *(f"LPT{i}" for i in range(1, 10)),
+}
+
+
+def config_filename(name: Any) -> str:
+    """``name`` as the file it names inside the configs directory, or raise.
+
+    A name is a plain file name and nothing else: this is reachable from an agent, and
+    ``save_config(name="../x")`` wrote outside the configs directory (and a read of an
+    absolute path returned any JSON file on the machine). A directory component of any
+    kind, an absolute path, ``.`` / ``..`` and an empty stem are all refused, so every
+    config lives directly under :data:`~quantred.optimization.config_store.DEFAULT_CONFIG_DIR`.
+    """
+    text = name if isinstance(name, str) else ""
+    stem = text[: -len(".json")] if text.endswith(".json") else text
+    plain = (
+        bool(stem.strip())
+        and stem not in (".", "..")
+        and "/" not in text
+        and "\\" not in text
+        and ":" not in text  # a drive letter, or an alternate data stream on Windows
+        and all(ord(ch) >= 32 for ch in text)
+        and stem.split(".")[0].upper() not in _RESERVED_WINDOWS_NAMES
+        and Path(text).name == text
+        and not Path(text).is_absolute()
+    )
+    if not plain:
+        raise ValueError(
+            f"Config name {name!r} is not a plain file name. Give a short name such as "
+            "'momentum_v2' - no directories, no '..', no absolute path; it is written under "
+            "the configs directory."
+        )
+    return f"{stem}.json"
+
+
+def _validate_candidate(
+    strategy: str,
+    params: Dict[str, Any],
+    scanner: Optional[str],
+    position_limits: Optional[Dict[str, Any]],
+    provenance: Optional[Dict[str, Any]],
+) -> None:
+    """Refuse a config that could not be run, before anything is written.
+
+    A saved config is what a person later promotes, so one that names a strategy that
+    does not exist, a parameter the strategy does not declare, a value its range check
+    rejects, or a book limit nothing enforces is a file that fails (or worse, runs at
+    the defaults) only when someone relies on it.
+    """
+    from quantred.services.registry import resolve_strategy_class, scanner_refusal
+    from quantred.strategies.base import build_with_limits, refuse_unknown_limits, refuse_unknown_params
+
+    cls = resolve_strategy_class(strategy)
+    if scanner is not None and (refusal := scanner_refusal(scanner)):
+        raise ValueError(refusal)
+    refuse_unknown_params(cls, params)
+    refuse_unknown_limits(position_limits)
+    # A config states only what it overrides; the run fills in the declared defaults, so
+    # the candidate is built the same way to check that its overrides construct.
+    candidate = {name: spec["default"] for name, spec in cls.PARAM_RANGES.items()}
+    candidate.update({k: v for k, v in (params or {}).items() if not k.startswith("_")})
+    try:
+        build_with_limits(cls, candidate, position_limits)
+    except (ValueError, TypeError, KeyError) as exc:
+        raise ValueError(f"These params do not construct {strategy!r}: {exc}") from exc
+    if isinstance(provenance, dict):
+        accepted = [f.name for f in dataclasses.fields(config_store.Provenance)]
+        unknown = [key for key in provenance if key not in accepted]
+        if unknown:
+            raise ValueError(
+                f"provenance has no field {', '.join(map(repr, unknown))}. Accepted fields: "
+                f"{', '.join(accepted)}. Put a trial id in `notes` or in `campaign` "
+                "(the get_campaign_material block)."
+            )
+
+
+def save_config(
+    name: str,
+    *,
+    strategy: str,
+    params: Dict[str, Any],
+    scanner: Optional[str] = None,
+    symbols: Optional[Any] = None,
+    capital: Optional[float] = None,
+    position_limits: Optional[Dict[str, Any]] = None,
+    provenance: Optional[Dict[str, Any]] = None,
+    overwrite: bool = False,
+) -> Dict[str, Any]:
+    """Persist a candidate config to ``configs/<name>.json``; return the path.
+
+    Does not affect any running process - a human promotes a config to live.
+
+    ``position_limits``, ``symbols`` and ``capital`` are here because without them this
+    surface could not write a *runnable* config at all: the file omits the book, and a
+    run from it inherits the strategy class's default of one position rather than the
+    book that was validated. An agent holding campaign material knows that book -
+    ``recorded_book`` reads it out - and had no parameter to put it in.
+
+    Omitted values stay omitted rather than being defaulted, so a config that never knew
+    its book is distinguishable from one saved at the class default.
+    """
+    filename = config_filename(name)
+    _refuse_replacing(filename, overwrite)
+    _validate_candidate(strategy, params, scanner, position_limits, provenance)
+    position_limits = _reconcile_book(position_limits, provenance)
+    capital = _reconcile_capital(capital, provenance)
+    cost = _recorded_cost(provenance)
+    prov = config_store.Provenance(**provenance) if isinstance(provenance, dict) else provenance
+    path = config_store.save_config(
+        filename,
+        strategy=strategy,
+        params=params,
+        scanner=scanner,
+        symbols=symbols,
+        capital=capital,
+        position_limits=position_limits,
+        cost=cost,
+        provenance=prov,
+    )
+    return {"path": str(path), "name": name}
+
+
+def _refuse_replacing(filename: str, overwrite: bool) -> None:
+    """Refuse to replace a saved config unless asked to.
+
+    A config is what a person promotes, and an agent proposing a new one under a name
+    already in use silently replaced it. Compared without case, because a
+    case-insensitive filesystem (the macOS default) maps ``Momentum.json`` onto
+    ``momentum.json``.
+    """
+    root = config_store.DEFAULT_CONFIG_DIR
+    if overwrite or not root.exists():
+        return
+    taken = {path.name.lower(): path.name for path in root.glob("*.json")}
+    if filename.lower() in taken:
+        raise ValueError(
+            f"A config named {taken[filename.lower()]!r} already exists. Choose another name, or "
+            "pass overwrite=true to replace it."
+        )
+
+
+def _reconcile_capital(capital: Optional[float], provenance: Optional[Any]) -> Optional[float]:
+    """The capital to write, checked against the one the provenance recorded.
+
+    The same rule the book gets, for the same reason: guarding one runnable field and
+    not the next leaves a config that can still argue with itself, one column over. An
+    omitted capital is taken from the campaign material that recorded it; a disagreeing
+    one is refused rather than resolved.
+
+    A campaign whose capital was never recorded changes nothing — absent stays absent,
+    and the caller's value (including none) stands.
+    """
+    recorded = _campaign_fact(provenance, "capital")
+    if recorded is None:
+        return capital
+    if capital is None:
+        return recorded
+    if float(capital) != float(recorded):
+        raise ValueError(
+            f"capital {capital} disagrees with the capital this config's own provenance "
+            f"records as validated ({recorded}). One of them is wrong and this cannot "
+            "tell which; pass the validated capital, or omit it and it will be used."
+        )
+    return capital
+
+
+def _campaign_fact(provenance: Optional[Any], fact: str) -> Optional[Any]:
+    """One recorded run-context fact out of campaign material, or ``None``.
+
+    ``None`` covers both "no campaign material" and "the material recorded no such
+    fact", which are the same thing to a caller deciding whether there is anything to
+    reconcile against.
+    """
+    campaign = (provenance or {}).get("campaign") if isinstance(provenance, dict) else None
+    entry = ((campaign or {}).get("recipe") or {}).get("context", {}).get(fact) or {}
+    return entry.get("value") if entry.get("recorded") else None
+
+
+def _recorded_cost(provenance: Optional[Any]) -> Optional[Dict[str, Any]]:
+    """The cost model the provenance's campaign material says was validated, or ``None``.
+
+    Taken rather than reconciled: this surface has no cost parameter to disagree with,
+    and a config that records an evidence block but no cost trades under the defaults
+    - the same file-argues-with-itself defect the book and capital guard against, and
+    the one ``trials promote`` shared. Absent stays absent.
+    """
+    from quantred.services.analysis import recorded_cost
+
+    campaign = (provenance or {}).get("campaign") if isinstance(provenance, dict) else None
+    return recorded_cost(((campaign or {}).get("recipe") or {}).get("folded_into_identity"))
+
+
+def _reconcile_book(
+    position_limits: Optional[Dict[str, Any]], provenance: Optional[Any]
+) -> Optional[Dict[str, Any]]:
+    """The book to write, checked against the one the provenance says was validated.
+
+    A parameter is not a guarantee. Campaign material carries the validated book in its
+    recipe, and a caller could still pass ``None`` beside it - writing a config that
+    records an eight-position validation and runs at the class default of one, which is
+    exactly the contradiction this parameter was added to end. So when the provenance
+    knows the book:
+
+    * omitted means *take it from the provenance*, because the caller supplied the
+      evidence and leaving the runnable half blank is never what they meant;
+    * disagreeing is refused outright, because one of the two numbers is wrong and
+      nothing here can tell which - and a file that argues with itself is worse than
+      no file.
+
+    Provenance that carries no campaign material, or campaign material with no recorded
+    book, changes nothing: absent stays absent rather than being filled from a default
+    nobody validated.
+    """
+    from quantred.services.analysis import recorded_book
+
+    campaign = (provenance or {}).get("campaign") if isinstance(provenance, dict) else None
+    validated = recorded_book(((campaign or {}).get("recipe") or {}).get("folded_into_identity"))
+    if not validated:
+        return position_limits
+    if position_limits is None:
+        return validated
+    if dict(position_limits) != dict(validated):
+        raise ValueError(
+            f"position_limits {position_limits} disagrees with the book this config's own "
+            f"provenance records as validated ({validated}). One of them is wrong and this "
+            "cannot tell which; pass the validated book, or omit it and it will be used."
+        )
+    return position_limits
+
+
+def load_config(name: str) -> Dict[str, Any]:
+    """Load a previously saved config by name (with or without ``.json``)."""
+    filename = config_filename(name)
+    path = config_store.DEFAULT_CONFIG_DIR / filename
+    if not path.is_file():
+        raise FileNotFoundError(f"No saved config named {name!r}.")
+    return config_store.load_config(path)
+
+
+def list_configs(directory: Optional[str] = None) -> List[Dict[str, Any]]:
+    """List saved candidate configs with a compact summary of each."""
+    root = Path(directory) if directory else config_store.DEFAULT_CONFIG_DIR
+    if not root.exists():
+        return []
+    out: List[Dict[str, Any]] = []
+    for path in sorted(root.glob("*.json")):
+        try:
+            doc = config_store.load_config(path)
+        except (ValueError, OSError):
+            continue
+        prov = doc.get("provenance", {})
+        out.append(
+            {
+                "name": path.stem,
+                "strategy": doc.get("strategy"),
+                "scanner": doc.get("scanner"),
+                "objective": prov.get("objective"),
+                "oos_metrics": prov.get("oos_metrics", {}),
+                "timestamp": prov.get("timestamp"),
+            }
+        )
+    return out