quantred 2.4.0__py3-none-any.whl

quantred/services/maintenance.py

@@ -0,0 +1,314 @@
+"""Trial-store maintenance: quarantining a subset, and retiring an era.
+
+Two operations, deliberately not one command. They answer different questions, and
+they differ in how reversible they are:
+
+**Quarantine** (:func:`mark_contaminated`) is for a *suspect subset*. Something was
+learned about some trials after they were recorded — a bug in a scanner, a data vendor
+correction, a config that turned out not to be the one you thought. History stays
+exactly as written; an event is appended saying what was learned, and readers honour it.
+
+**Archive** (:func:`archive`) is for a *whole era*. An accounting bump changes what the
+engine computes, so every recorded metric becomes incommensurable with anything produced
+afterwards — not suspect, but measured with a different instrument. That is not a subset
+and no annotation fixes it: the journal and its index are moved aside together and a
+fresh pair started.
+
+Collapsing them would be a mistake in both directions. Quarantining an era leaves
+thousands of rows carrying a caveat nobody can act on; archiving a subset throws away
+the evidence around it.
+
+**Nothing here deletes anything.** There is no `reset`, because the destructive version
+of archive is exactly what the append-only rule exists to forbid: the journal has nothing
+behind it to rebuild from, so a record removed is a record gone. Archive moves; the files
+are still on disk under a name that says when and why.
+
+The two files move **together**, always. The store is derived from the journal, so moving
+one without the other leaves a store indexing a file that no longer exists — or worse, a
+store full of an old era's rows sitting beside a fresh journal, silently disagreeing with
+its own source and reporting a multiple-testing count for evidence that is no longer
+there. That is precisely the hand-rolled state this exists to replace.
+"""
+
+import json
+import logging
+import shutil
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Dict, Iterable, List, Optional
+
+from quantred.engine.backtest import ACCOUNTING_VERSION
+from quantred.services import audit
+from quantred.settings import state_root
+from quantred.store.trials import CONTAMINATION_TOOL, TrialStore, db_path_for_journal
+
+logger = logging.getLogger(__name__)
+
+#: Where retired eras go. Under the state root, beside the journal they came from, so
+#: an archive travels with the campaign rather than wherever the command was run.
+ARCHIVE_DIRNAME = "archive"
+
+#: Written into each archive directory. The files alone do not say why they were
+#: retired, and "why" is the part nobody reconstructs a year later.
+MANIFEST_NAME = "manifest.json"
+
+#: Appended to the *new* journal as its first line after an archive. A fresh journal that
+#: simply starts empty loses the fact that an era existed, and the emptiness then reads
+#: as "nothing has ever been run here" — which is how a campaign's evidence quietly
+#: appears to have never happened.
+ARCHIVE_TOOL = "trials:archived"
+
+
+def _resolve_journal(journal_path: Optional[Any]) -> Path:
+    return Path(journal_path) if journal_path else audit.default_trial_journal()
+
+
+def resolve_trial_ids(typed: Iterable[str], journal_path: Optional[Any] = None) -> Dict[str, Optional[str]]:
+    """Each typed id (or unique prefix) to the full id it names, ``None`` where it names none.
+
+    Raises ``AmbiguousTrialId`` (a ``ValueError``) for a prefix more than one trial carries.
+    """
+    journal = _resolve_journal(journal_path)
+    with TrialStore(db_path_for_journal(journal), journal_path=journal) as store:
+        return {t: store.resolve_id(t) for t in typed}
+
+
+def select_trials(
+    *,
+    journal_path: Optional[Any] = None,
+    trial_ids: Optional[Iterable[str]] = None,
+    strategy: Optional[str] = None,
+    kind: Optional[str] = None,
+    accounting: Optional[int] = None,
+    before: Optional[Any] = None,
+) -> List[Dict[str, Any]]:
+    """The trials a quarantine would name, resolved to explicit rows.
+
+    Filters are resolved to ids **now**, and the event records those ids rather than the
+    filter. A stored filter would re-evaluate on every rebuild and could silently pull in
+    trials recorded after the decision was made — a quarantine that grows on its own is
+    not a record of what somebody decided.
+    """
+    if trial_ids and any(f is not None for f in (strategy, kind, accounting, before)):
+        # Ids name trials outright, and the filters used to be ignored beside them, so
+        # `--id X --strategy Y` quarantined X whatever its strategy, saying nothing.
+        raise ValueError("ids name trials outright; give either ids or filters, not both")
+    journal = _resolve_journal(journal_path)
+    with TrialStore(db_path_for_journal(journal), journal_path=journal) as store:
+        if trial_ids:
+            rows = [store.get_trial(str(t)) for t in trial_ids]
+            return [r for r in rows if r]
+        # The store's own `before` rather than a second date comparison here: the store
+        # owns one definition of what a filter means, and a listing that disagreed with
+        # the store's own count of the same filter is the bug that definition prevents.
+        # Not `until`, which includes the whole day it names.
+        return store.list_trials(
+            strategy=strategy,
+            kind=kind,
+            accounting=accounting,
+            all_accounting=accounting is None,
+            before=before,
+            limit=1_000_000,
+        )
+
+
+def mark_contaminated(
+    *,
+    reason: str,
+    journal_path: Optional[Any] = None,
+    trial_ids: Optional[Iterable[str]] = None,
+    strategy: Optional[str] = None,
+    kind: Optional[str] = None,
+    accounting: Optional[int] = None,
+    before: Optional[Any] = None,
+    dry_run: bool = False,
+) -> Dict[str, Any]:
+    """Quarantine a suspect subset of trials, reason on the record.
+
+    Appends one event naming every affected trial, then applies it to the derived index.
+    A rebuild replays the event and reaches the same rows, so the quarantine survives the
+    store being thrown away — which it is, routinely, whenever the schema moves.
+
+    ``reason`` is required and not defaulted. An unexplained quarantine is worse than
+    none: a later reader sees rows excluded from every leaderboard with nothing saying
+    what was wrong with them, and has no way to judge whether it still applies.
+    """
+    if not (reason or "").strip():
+        raise ValueError("A quarantine needs a reason: an unexplained one cannot be judged later")
+
+    journal = _resolve_journal(journal_path)
+    typed = [str(t) for t in (trial_ids or [])]
+    if typed and any(f is not None for f in (strategy, kind, accounting, before)):
+        raise ValueError("ids name trials outright; give either ids or filters, not both")
+    resolved = resolve_trial_ids(typed, journal) if typed else {}
+    found = [full for full in resolved.values() if full]
+    if typed and not found:
+        # Every id was a typo. An empty id list is falsy, and handing it on read as "no
+        # ids, no filters" - so the report selected every trial in the store.
+        selected: List[Dict[str, Any]] = []
+    else:
+        selected = select_trials(
+            journal_path=journal,
+            trial_ids=found if typed else None,
+            strategy=strategy,
+            kind=kind,
+            accounting=accounting,
+            before=before,
+        )
+    # An id somebody typed is a claim that the trial exists; a filter matching nothing is
+    # an answer. Only the first is a typo signal, so only it is reported back.
+    payload_unmatched = [t for t in typed if not resolved.get(t)]
+    already = [r for r in selected if r.get("contaminated_at")]
+    fresh = [r for r in selected if not r.get("contaminated_at")]
+    ids = [r["id"] for r in fresh]
+
+    payload = {
+        "selected": len(selected),
+        "already_contaminated": len(already),
+        "to_mark": len(ids),
+        "trial_ids": ids,
+        "reason": reason,
+        "journal_path": str(journal),
+        "dry_run": dry_run,
+        "unmatched_ids": payload_unmatched,
+    }
+    if dry_run or not ids or payload_unmatched:
+        payload["applied"] = 0
+        if payload_unmatched:
+            first = "An id matched no trial, so nothing was written."
+        else:
+            first = "Nothing selected." if not selected else "Dry run: nothing was written."
+        payload["note"] = (
+            first + " A quarantined trial still counts toward its family's multiple-testing total."
+        )
+        return payload
+
+    run_id = audit.audit_log(
+        CONTAMINATION_TOOL,
+        {"trial_ids": ids, "reason": reason, "selected": len(selected)},
+        path=journal,
+    )
+    with TrialStore(db_path_for_journal(journal), journal_path=journal) as store:
+        applied = store.mark_contaminated(ids, reason=reason)
+    payload["applied"] = applied
+    payload["event_run_id"] = run_id
+    payload["note"] = (
+        "Quarantined trials are never served as a memo and never ranked, and they still "
+        "count toward their family's multiple-testing total — the search happened, and "
+        "removing it would lower the deflation bar rather than raise it."
+    )
+    return payload
+
+
+def archive(
+    *,
+    reason: str,
+    journal_path: Optional[Any] = None,
+    label: Optional[str] = None,
+    stamp: Optional[str] = None,
+    dry_run: bool = False,
+) -> Dict[str, Any]:
+    """Retire a whole era: move the journal and its index aside, together.
+
+    Together is the requirement, not a convenience. The store is an index over the
+    journal, so moving one alone leaves the other describing something that is not there
+    — a store still reporting an era's multiple-testing count beside a journal that no
+    longer holds it, with nothing erroring, because both files are individually valid.
+
+    The archive keeps a manifest saying what was retired, when, why, and under which
+    accounting version and commit. And the *new* journal opens with a record of the
+    archive, so its emptiness reads as "an era was retired here" rather than as "nothing
+    has ever been run".
+    """
+    if not (reason or "").strip():
+        raise ValueError(
+            "An archive needs a reason: a retired era with no explanation cannot be judged later"
+        )
+
+    journal = _resolve_journal(journal_path)
+    db = db_path_for_journal(journal)
+    when = stamp or datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    name = f"{when}-{label}" if label else when
+    destination = state_root() / ARCHIVE_DIRNAME / name
+
+    summary: Dict[str, Any] = {"rows": 0, "journal_lines": 0}
+    if journal.exists() or db.exists():
+        try:
+            with TrialStore(db, journal_path=journal) as store:
+                status = store.status(journal)
+            summary = {
+                "rows": status["rows"],
+                "journal_lines": status["journal_lines"],
+                "journal_trial_lines": status["journal_trial_lines"],
+                "contaminated_rows": status.get("contaminated_rows", 0),
+            }
+        except Exception:  # noqa: BLE001 - a broken store must not block retiring it
+            logger.warning("Could not summarize the store before archiving it", exc_info=True)
+
+    manifest = {
+        "archived_at": datetime.now(timezone.utc).isoformat(),
+        "reason": reason,
+        "label": label,
+        "accounting_version_at_archive": ACCOUNTING_VERSION,
+        "git_sha": audit.current_git_sha(),
+        "journal_path": str(journal),
+        "db_path": str(db),
+        "destination": str(destination),
+        **summary,
+    }
+    existing = [path for path in (journal, db) if path.exists()]
+    if dry_run:
+        return {
+            **manifest,
+            "moved": [],
+            "would_move": [path.name for path in existing],
+            "dry_run": True,
+            "note": "Dry run: nothing was moved.",
+        }
+
+    if not existing:
+        return {
+            **manifest,
+            "moved": [],
+            "dry_run": False,
+            "note": f"Nothing to archive: neither {journal.name} nor {db.name} exists.",
+        }
+
+    destination.mkdir(parents=True, exist_ok=True)
+    moved = []
+    for path in existing:
+        shutil.move(str(path), str(destination / path.name))
+        moved.append(path.name)
+    (destination / MANIFEST_NAME).write_text(json.dumps({**manifest, "moved": moved}, indent=2) + "\n")
+
+    # The new journal's first line, so an empty campaign says why it is empty.
+    audit.audit_log(
+        ARCHIVE_TOOL,
+        {"reason": reason, "archived_to": str(destination), "label": label, **summary},
+        path=journal,
+    )
+    return {**manifest, "moved": moved, "dry_run": False, "note": "Both files moved together."}
+
+
+def list_archives() -> List[Dict[str, Any]]:
+    """Every retired era, newest first, with what its manifest recorded."""
+    root = state_root() / ARCHIVE_DIRNAME
+    if not root.is_dir():
+        return []
+    out = []
+    for directory in sorted(root.iterdir(), reverse=True):
+        if not directory.is_dir():
+            continue
+        entry: Dict[str, Any] = {"name": directory.name, "path": str(directory)}
+        manifest = directory / MANIFEST_NAME
+        if manifest.exists():
+            try:
+                entry.update(json.loads(manifest.read_text()))
+            except json.JSONDecodeError:
+                entry["manifest_error"] = "unreadable"
+        else:
+            # Reported, never inferred: a directory somebody created by hand is not
+            # evidence about what it holds.
+            entry["manifest_error"] = "missing"
+        out.append(entry)
+    return out

quantred/services/registry.py

@@ -0,0 +1,351 @@
+"""Discovery: the registries of strategies and scanners, and their tunables.
+
+Single source of truth for "what can the engine run?" - imported by the CLI, the
+MCP server, and the research agent so they all see the same menu.
+"""
+
+import logging
+import re
+import sys
+from collections.abc import Mapping
+from importlib import metadata
+from typing import Any, Dict, List, Optional, Type
+
+from quantred.demo.scanners import DemoVolumeScanner
+from quantred.demo.strategies import DemoTrendStrategy
+from quantred.scanners.base import ScannerStrategy
+from quantred.scanners.symbol_scanner import BUILTIN_SCANNERS as _BUILTIN_SCANNERS
+from quantred.scanners.symbol_scanner import SymbolScanner
+from quantred.settings import (
+    LEGACY_DISTRIBUTION_NAMES,
+    SCANNER_ENTRY_POINT_GROUP,
+    STRATEGY_ENTRY_POINT_GROUP,
+    entry_point_groups,
+)
+from quantred.strategies.base import Strategy
+
+logger = logging.getLogger(__name__)
+
+_NAME_RE = re.compile(r"^[A-Za-z][A-Za-z0-9_-]*$")
+
+#: Names the engine itself owns, and the classes behind them. This is the reserved
+#: set: an installed pack cannot take one of these names.
+#:
+#: The demo pair is *also* declared as an entry point in the engine's own
+#: ``pyproject.toml``, so the shipped wheel exercises the same discovery path a
+#: pack's does rather than leaving it to CI fixtures. Seeded here as well because
+#: enumeration order across distributions is not defined: a pack registering
+#: ``demo_trend`` would otherwise win or lose by accident, and reserving a name is
+#: worth nothing if which class answers to it is a coin flip.
+BUILTIN_STRATEGIES: Dict[str, Type[Strategy]] = {"demo_trend": DemoTrendStrategy}
+
+#: Built-in scanners. Taken from the scanner package's own literal rather than from
+#: ``SymbolScanner.SCANNERS``, which discovery overwrites with the merged set -
+#: re-deriving from that on a module reload quietly promoted installed contributions
+#: into the reserved built-in names.
+BUILTIN_SCANNERS: Dict[str, Type[ScannerStrategy]] = {
+    **_BUILTIN_SCANNERS,
+    "demo_volume": DemoVolumeScanner,
+}
+
+#: Trading strategies exposed everywhere (CLI, MCP, agent).
+#:
+#: Seeded with the built-ins rather than left empty, so these are never *less* than
+#: the public engine at any instant. Discovery imports arbitrary third-party modules,
+#: and a pack that reads the registry while importing used to observe the empty dict
+#: this was populated from - raising, and being dropped as a broken contribution.
+STRATEGIES: Dict[str, Type[Strategy]] = dict(BUILTIN_STRATEGIES)
+
+#: Universe scanners exposed everywhere (CLI, MCP, agent).
+SCANNERS: Dict[str, Type[ScannerStrategy]] = dict(BUILTIN_SCANNERS)
+
+
+def refresh_registries() -> None:
+    """Reload built-ins plus installed strategy/scanner entry points.
+
+    Import-time discovery is enough for normal CLI/MCP use, but tests and notebooks
+    can call this after changing the environment. Built-in names are reserved:
+    an installed private package cannot silently replace the public examples.
+
+    Both registries are built in full before either is swapped in. Clearing first
+    published an empty registry for the whole of discovery - which is exactly when
+    third-party code is being imported and may read it - and left the registry wiped
+    rather than merely stale if anything raised on the way.
+    """
+    strategies = _merged_registry(BUILTIN_STRATEGIES, STRATEGY_ENTRY_POINT_GROUP, Strategy)
+    scanners = _merged_registry(BUILTIN_SCANNERS, SCANNER_ENTRY_POINT_GROUP, ScannerStrategy)
+    STRATEGIES.clear()
+    STRATEGIES.update(strategies)
+    SCANNERS.clear()
+    SCANNERS.update(scanners)
+    # SymbolScanner is still used directly in a few paths; keep its legacy class
+    # attribute in sync with the single service registry.
+    SymbolScanner.SCANNERS = dict(SCANNERS)
+
+
+def list_strategies() -> List[Dict[str, Any]]:
+    """Names, one-line descriptions, and whether each is shipped demo scaffolding.
+
+    ``demo`` is read from the class, not from registry membership. The shipped
+    example arrives by entry point exactly as a private pack's does, so *how* something
+    was discovered stopped being able to say what it is for. Carried rather than
+    implied, because without a label the reasonable read of a registry is that the
+    platform *is* whatever is in it.
+    """
+    return [
+        {
+            "name": name,
+            "description": _first_line(cls.__doc__),
+            "timeframe": getattr(cls, "TIMEFRAME", None) or None,
+            "demo": is_demo(cls),
+        }
+        for name, cls in STRATEGIES.items()
+    ]
+
+
+def list_scanners() -> List[Dict[str, Any]]:
+    """Names, one-line descriptions, and whether each is shipped demo scaffolding."""
+    return [
+        {
+            "name": name,
+            "description": _first_line(cls.__doc__),
+            "demo": is_demo(cls),
+        }
+        for name, cls in SCANNERS.items()
+    ]
+
+
+def scanner_refusal(value: str) -> Optional[str]:
+    """Why ``value`` is not a usable scanner name, or ``None`` when it is.
+
+    ``"none"`` means no scan and is always accepted. One definition for the CLI (at parse
+    time) and the services (before any step runs), so an unknown name is refused the same
+    way on every surface rather than failing inside a scan and being reported as a
+    different problem further down the report.
+    """
+    import difflib
+
+    if value == "none" or value in SCANNERS:
+        return None
+    close = difflib.get_close_matches(value, list(SCANNERS), n=1)
+    hint = f" Did you mean {close[0]!r}?" if close else ""
+    installed = ", ".join(sorted(SCANNERS)) or "none installed"
+    return f"unknown scanner {value!r}.{hint} Available: {installed}; or 'none' to skip the scan."
+
+
+def is_demo(cls: Type) -> bool:
+    """Whether ``cls`` is shipped demonstration scaffolding, rather than inheriting it.
+
+    Read from the class's own ``__dict__``, not through the MRO. ``docs/content/usage/
+    private-strategies.md`` invites a pack to start by subclassing ``DemoTrendStrategy``,
+    and an inherited flag reported that pack's real strategy to the CLI, the MCP server
+    and the research agent as shipped scaffolding - the same "the platform *is* whatever
+    is in it" misread the label exists to prevent, pointing the other way. A subclass
+    that genuinely is more scaffolding can say so by setting ``DEMO`` itself.
+    """
+    return bool(cls.__dict__.get("DEMO", False))
+
+
+def get_param_ranges(kind: str, name: str) -> Dict[str, Any]:
+    """The ``PARAM_RANGES`` map for a strategy/scanner - what is tunable and its bounds.
+
+    Args:
+        kind: ``"strategy"`` or ``"scanner"``.
+        name: A registered name.
+    """
+    registry = STRATEGIES if kind == "strategy" else SCANNERS if kind == "scanner" else None
+    if registry is None:
+        raise ValueError(f"kind must be 'strategy' or 'scanner', got {kind!r}")
+    if name not in registry:
+        raise ValueError(f"Unknown {kind} '{name}'. Available: {list(registry)}")
+    return {"kind": kind, "name": name, "param_ranges": registry[name].PARAM_RANGES}
+
+
+#: Identity prefix of a strategy the research agent or a draft walk-forward wrote. It
+#: names a mechanism for the trial history; it is never a registered, runnable name.
+DRAFT_PREFIX = "draft:"
+
+
+def resolve_strategy_class(name: str) -> Type[Strategy]:
+    if name.startswith(DRAFT_PREFIX):
+        from quantred.utils.errors import GeneratedCodeRefused
+
+        raise GeneratedCodeRefused(name)
+    if name not in STRATEGIES:
+        raise ValueError(f"Unknown strategy '{name}'. Available: {list(STRATEGIES)}")
+    return STRATEGIES[name]
+
+
+def _merged_registry(builtins: Dict[str, Type], group: str, base_cls: Type) -> Dict[str, Type]:
+    registry = dict(builtins)
+    for name, cls in _entry_point_classes(group, base_cls).items():
+        if name in registry:
+            if registry[name] is cls:
+                # The engine's own demo, arriving by the entry point it declares.
+                # Same name, same class, nothing overridden - warning here would fire
+                # on every single run and train the reader to ignore the real one.
+                continue
+            logger.warning("Ignoring %s entry point %r: built-in names cannot be overridden", group, name)
+            continue
+        registry[name] = cls
+    return registry
+
+
+def _entry_point_classes(group: str, base_cls: Type) -> Dict[str, Type]:
+    """Load extension classes from an entry-point group.
+
+    A contribution may be either a class, a mapping of name -> class, or a no-arg
+    function returning that mapping. Invalid contributions are ignored with a warning
+    so a broken private package cannot make the public engine unusable.
+    """
+    found: Dict[str, Type] = {}
+    for entry_point in _select_entry_points(group):
+        declared = getattr(entry_point, "group", None) or group
+        if _from_legacy_distribution(entry_point):
+            # The previous distribution (`tradeflow-engine` 2.3.0) can still be installed
+            # beside this one and declares the demo pair under the old groups. Those
+            # names are built in here already; loading them would import the old
+            # package's copy of the same classes and trip the override warning on every
+            # command. This distribution's own declarations are *not* skipped: the demo
+            # pair goes through this path on every install, which is the point of
+            # declaring it rather than only seeding it.
+            logger.debug(
+                "Skipping %s entry point %r: declared by the previous distribution",
+                declared,
+                entry_point.name,
+            )
+            continue
+        # Loading is all-or-nothing for one entry point: if the module will not
+        # import, or hands back something that is not a set of contributions, there
+        # is nothing of it to keep.
+        try:
+            contributions = _coerce_contributions(entry_point.name, entry_point.load())
+        except Exception as exc:  # noqa: BLE001 - discovery should degrade, not brick the CLI
+            logger.warning("Ignoring %s entry point %r: %s", declared, entry_point.name, exc)
+            continue
+
+        # Validation is not. One unusable class in a pack of five used to abort the
+        # loop, keeping whatever had already been added and silently dropping the
+        # siblings it had not reached yet - so which of a pack's contributions
+        # survived came down to dict ordering, and the warning named neither the
+        # offending class nor the ones lost behind it.
+        for name, cls in contributions.items():
+            try:
+                _validate_extension(name, cls, base_cls, declared)
+            except Exception as exc:  # noqa: BLE001 - one bad class, not one bad pack
+                logger.warning(
+                    "Ignoring %s contribution %r from entry point %r: %s",
+                    declared,
+                    name,
+                    entry_point.name,
+                    exc,
+                )
+                continue
+            if name in found:
+                logger.warning(
+                    "Ignoring duplicate %s contribution %r from entry point %r",
+                    declared,
+                    name,
+                    entry_point.name,
+                )
+                continue
+            found[name] = cls
+    _warn_if_a_pack_imports_the_old_name()
+    return found
+
+
+def _from_legacy_distribution(entry_point: Any) -> bool:
+    """Whether ``entry_point`` is declared by the engine's *previous* distribution.
+
+    Only the previous one: its declarations are a second copy of classes that are
+    built in here already. The current distribution's own entry points are loaded like
+    anyone's.
+    """
+    dist = getattr(entry_point, "dist", None)
+    name = getattr(dist, "name", None) or (getattr(dist, "metadata", None) or {}).get("Name")
+    return bool(name) and str(name).lower().replace("_", "-") in LEGACY_DISTRIBUTION_NAMES
+
+
+_WARNED_OLD_IMPORT = False
+
+
+def _warn_if_a_pack_imports_the_old_name() -> None:
+    """Say once that something loaded through the ``tradeflow`` import alias.
+
+    The alias's ``DeprecationWarning`` is hidden by Python's default filters unless it
+    is raised from ``__main__``, so a pack loaded by entry point would use it silently
+    while the docs say it warns. Detected from the alias itself (its module and its
+    import finder are present) rather than from any one pack.
+    """
+    global _WARNED_OLD_IMPORT
+    if _WARNED_OLD_IMPORT or "tradeflow" not in sys.modules:
+        return
+    if not any(type(finder).__name__ == "_AliasFinder" for finder in sys.meta_path):
+        return
+    _WARNED_OLD_IMPORT = True
+    logger.warning(
+        "A pack imports the old `tradeflow` name; it works through tradeflow-engine 2.3.1 - "
+        "change its imports to `quantred`."
+    )
+
+
+def _select_entry_points(group: str) -> List[Any]:
+    """Installed entry points in ``group``, or none if they cannot be enumerated.
+
+    Enumeration was the one step of discovery outside a ``try``, and it is the step
+    that reads installed distribution metadata - which can be malformed by a package
+    this project has never heard of. Because discovery runs at import, that took down
+    every command importing this module, which is every command: precisely the
+    "a broken private distribution must not make the open engine unusable" case the
+    rest of this file is written around.
+    """
+    try:
+        entry_points = metadata.entry_points()
+        found: List[Any] = []
+        for name in entry_point_groups(group):
+            if hasattr(entry_points, "select"):
+                found.extend(entry_points.select(group=name))
+            else:  # pragma: no cover - the dict-shaped API of older Pythons
+                found.extend(entry_points.get(name, ()))
+        return found
+    except Exception as exc:  # noqa: BLE001 - built-ins only beats no engine at all
+        logger.warning("Cannot enumerate %s entry points (%s); built-in names only", group, exc)
+        return []
+
+
+def _coerce_contributions(default_name: str, loaded: Any) -> Dict[str, Type]:
+    if isinstance(loaded, type):
+        return {default_name: loaded}
+    if isinstance(loaded, Mapping):
+        return dict(loaded)
+    if callable(loaded):
+        contributed = loaded()
+        if not isinstance(contributed, Mapping):
+            raise ValueError("factory entry point must return a mapping of name -> class")
+        return dict(contributed)
+    raise ValueError("entry point must load a class, mapping, or mapping factory")
+
+
+def _validate_extension(name: str, cls: Type, base_cls: Type, group: str) -> None:
+    if not isinstance(name, str) or not _NAME_RE.match(name):
+        raise ValueError(f"invalid extension name {name!r}")
+    if not isinstance(cls, type) or not issubclass(cls, base_cls) or cls is base_cls:
+        raise ValueError(f"{name!r} is not a concrete {base_cls.__name__} subclass")
+    if getattr(cls, "__abstractmethods__", None):
+        raise ValueError(f"{name!r} leaves abstract methods unimplemented")
+    if not isinstance(getattr(cls, "PARAM_RANGES", None), dict):
+        raise ValueError(f"{name!r} must declare PARAM_RANGES")
+    logger.info("Loaded %s extension %r from %s", group, name, cls.__module__)
+
+
+def _first_line(doc: str) -> str:
+    return (doc or "").strip().split("\n", 1)[0]
+
+
+# Discovery at import, guarded at import. A degraded engine that still runs the
+# built-ins is worth more than an ImportError on every command, and the traceback is
+# logged rather than swallowed so the cause stays recoverable.
+try:
+    refresh_registries()
+except Exception:  # noqa: BLE001
+    logger.warning("Extension discovery failed; built-in strategies and scanners only", exc_info=True)