alphaengine 0.3.0__tar.gz → 0.4.0__tar.gz

{alphaengine-0.3.0 → alphaengine-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alphaengine
-Version: 0.3.0
+Version: 0.4.0
 Summary: Validated research tooling for investment strategies: deflation, overfitting detection, and honest trial counts.
 Project-URL: Homepage, https://github.com/quantOSC/alphaengine
 Project-URL: Documentation, https://github.com/quantOSC/alphaengine#readme
@@ -149,6 +149,7 @@ distinction is the whole of the data boundary below.
 | Command | Does | Where |
 |---|---|---|
 | `demo` | run the built-in example offline, with no account and no data | shell + session |
+| `runs [--limit N]` | your own week: what ran, what it decided, what it filed | shell + session |
 | `workflows` | what the server offers, what each needs, and which reproduce | shell + session |
 | `key [quantos \| anthropic \| openai]` | enter a credential now, or see which rungs are unlocked | session |
 | `commands [verb]` | this directory, or one command in full | shell + session |
@@ -209,6 +210,7 @@ distinction is the whole of the data boundary below.
 | `--label TEXT` | what to call the artifact this run produces |
 | `--input K=V` | a workflow input; repeatable |
 | `--quiet` | only the result, no step narration |
+| `--limit N` | how many rows to show (default 25) |
 
 ### Examples
 
@@ -222,6 +224,8 @@ alphaengine overlap
 alphaengine size
 alphaengine monitor
 alphaengine demo
+alphaengine runs
+alphaengine runs --limit 50
 alphaengine workflows
 alphaengine commands
 alphaengine run screen_universe --universe sp500

{alphaengine-0.3.0 → alphaengine-0.4.0}/README.md

@@ -108,6 +108,7 @@ distinction is the whole of the data boundary below.
 | Command | Does | Where |
 |---|---|---|
 | `demo` | run the built-in example offline, with no account and no data | shell + session |
+| `runs [--limit N]` | your own week: what ran, what it decided, what it filed | shell + session |
 | `workflows` | what the server offers, what each needs, and which reproduce | shell + session |
 | `key [quantos \| anthropic \| openai]` | enter a credential now, or see which rungs are unlocked | session |
 | `commands [verb]` | this directory, or one command in full | shell + session |
@@ -168,6 +169,7 @@ distinction is the whole of the data boundary below.
 | `--label TEXT` | what to call the artifact this run produces |
 | `--input K=V` | a workflow input; repeatable |
 | `--quiet` | only the result, no step narration |
+| `--limit N` | how many rows to show (default 25) |
 
 ### Examples
 
@@ -181,6 +183,8 @@ alphaengine overlap
 alphaengine size
 alphaengine monitor
 alphaengine demo
+alphaengine runs
+alphaengine runs --limit 50
 alphaengine workflows
 alphaengine commands
 alphaengine run screen_universe --universe sp500

{alphaengine-0.3.0 → alphaengine-0.4.0}/src/alphaengine/_version.py

@@ -17,4 +17,16 @@ is what a changed figure costs. The API may still move underneath it.
 # column, so any grid with a failure read the wrong survivor's column (or
 # raised). Fixing it changes the figure a 0.2 install would have produced from
 # the same inputs — which is exactly what the MINOR position costs here.
-__version__ = "0.3.0"
+#
+# 0.4.0 IS THE SAME RULE AGAIN, and it is the harder case to spot because it
+# reads as "we added some charts". The wire's figure cap went 64 -> 512 and the
+# per-period cap in `core.signals` went with it, so the SAME INPUTS NOW PRODUCE
+# DIFFERENT OUTPUT: `ic_by_period` returns up to 512 readings where it returned
+# 64, `best_curve` and `drawdown_curve` carry a curve rather than a sketch of
+# one, a grid of up to 512 configurations records its full surface instead of
+# reporting `trials_recorded: false`, and `compute.overlap` emits a rolling
+# correlation and a scatter it did not emit before.
+#
+# Not one of those is a bug fix, and every one changes what a saved study
+# reproduces. That costs the MINOR position while the leading digit is 0.
+__version__ = "0.4.0"

{alphaengine-0.3.0 → alphaengine-0.4.0}/src/alphaengine/cli.py

@@ -112,6 +112,34 @@ _ENV_KEY = "QUANTOS_API_KEY"
 _ENV_URL = "QUANTOS_API_URL"
 DEFAULT_BASE_URL = "https://alpha-backend-production-51df.up.railway.app"
 
+#: WHERE A RUN IS READ. The CLI printed a bare run id and left the reader to
+#: work out that `/portal/runs/<id>` exists — and named four screens that had
+#: been redirects for months besides ("Work", "the sleeve page", "your Book",
+#: "accept it in the portal", the last pointing at a surface that does not
+#: exist at all). An id nobody can turn into a URL is a reference to nothing.
+#:
+#: Overridable, and derived from the API host when that has been pointed
+#: somewhere else, so a self-hosted deployment does not send its users to ours.
+DEFAULT_PORTAL_URL = "https://qosai.app"
+
+
+def portal_url(api_url: str | None = None) -> str:
+    """The portal this account's runs live on.
+
+    `$QUANTOS_PORTAL_URL` wins. Otherwise the public portal — EXCEPT when the
+    API has been pointed at localhost, where sending somebody to the hosted
+    portal to read a run that exists only on their machine is the config-default
+    failure this codebase has already paid for four times: present, wrong, and
+    answering every check.
+    """
+    override = os.environ.get("QUANTOS_PORTAL_URL")
+    if override:
+        return override.rstrip("/")
+    host = (api_url or os.environ.get(_ENV_URL) or DEFAULT_BASE_URL).lower()
+    if "localhost" in host or "127.0.0.1" in host:
+        return "http://localhost:3000"
+    return DEFAULT_PORTAL_URL
+
 
 # ── output ─────────────────────────────────────────────────────────────────
 #
@@ -549,6 +577,69 @@ def cmd_workflows(args: argparse.Namespace) -> int:
     return 0
 
 
+def cmd_runs(args: argparse.Namespace) -> int:
+    """YOUR OWN WEEK, from where the work happens.
+
+    The terminal could start a run and could not show you one. "What did I
+    already try" was a question you had to open a browser to ask, from the one
+    place you are least likely to want to leave — and a quant's week is fifteen
+    runs of which most are stops.
+
+    THE STOPS ARE THE POINT. They are the majority of a week's output and the
+    part that evaporates everywhere else, so a stop prints its REASON rather
+    than only its token: the sentence is the most useful thing the run produced.
+    """
+    from .client import Offline, ServerError
+
+    session, url = _session(args.url, args.key)
+    try:
+        rows = session.recent_runs(limit=args.limit)
+    except Offline:
+        _explain_offline(url)
+        return 2
+    except ServerError as exc:
+        refused(exc)
+        if is_auth_error(exc) and offer_key():
+            say(dim("  Key set. Run that again."))
+        return 2
+
+    if not rows:
+        say("")
+        say(dim("  Nothing recorded on this account yet."))
+        say(dim("  A run files itself as it goes: ") + "alphaengine screen --universe <name>")
+        return 0
+
+    say("")
+    for r in rows:
+        when = str(r.get("created_at") or "")[:10]
+        kind = str(r.get("kind") or "workflow")
+        verdict = str(r.get("verdict") or r.get("status") or "")
+        mark = (
+            yellow("stopped")
+            if verdict == "stopped"
+            else green("closed")
+            if verdict == "completed"
+            else dim(verdict or "open")
+        )
+        line = f"  {dim(when)}  {bold(kind.ljust(16))}  {mark}"
+        # THE DENOMINATOR TRAVELS WITH THE COUNT, here as everywhere. A number
+        # that was counted and one that was asserted are different claims.
+        if r.get("honest_n") is not None:
+            src = str(r.get("n_trials_source") or "unknown").replace("_", " ")
+            line += dim(f"  n={r['honest_n']} {DOT} {src}")
+        filed = r.get("signal_file")
+        if isinstance(filed, dict) and filed.get("version"):
+            line += dim(f"  {DOT} filed v{filed['version']}")
+        say(line)
+        reason = str(r.get("reason") or "").strip()
+        if reason:
+            for text in _wrap(reason, 68):
+                say("    " + dim(text))
+    say("")
+    say(dim(f"  {len(rows)} shown {DOT} open one in the portal to act on it"))
+    return 0
+
+
 def preflight(catalogue: list[dict[str, Any]], name: str, *, data: Any, backtest_fn: Any) -> str | None:
     """What is missing before a run starts. `None` when nothing is.
 
@@ -1028,7 +1119,14 @@ def _propose_sleeve(session: Any, run: Any, thesis: dict[str, Any]) -> None:
 
     say("")
     say(f"  {green('Proposed.')} {len(ranked)} names for {bold(title)}")
-    say(dim("  Nothing exists yet. Open it in the portal to accept or change it."))
+    # THE PROPOSAL SURFACE WAS RETIRED IN PHASE 8 and this line went on naming
+    # it, so the one instruction printed here pointed at a redirect. Accepting
+    # work happens on the RUN now, which is where its figures, its caveats and
+    # its review pass already are.
+    say(
+        dim("  Nothing exists yet. Accept or decline it on the run: ")
+        + f"{portal_url()}/portal/runs/{getattr(run, 'run_id', '')}"
+    )
     say(dim(f"  proposal {filed.get('id')}"))
 
 
@@ -1106,15 +1204,63 @@ def _publish_signals(session: Any, run: Any, *, workspace_id: str | None, label:
         + dim(f"{saved.get('label')} {DOT} {saved.get('asof')}")
         + (dim(f" {DOT} v{version}") if version else "")
     )
-    say(dim("  It is on your account, dated and versioned. Tomorrow's run diffs against it."))
+    _say_diff(run)
+
+
+def _found(before: set[str], run: Any) -> str:
+    """What the step that just ran FOUND, in the reader's words.
+
+    ── THE RULE THAT MAKES THIS SAFE: NARRATION IS RETROSPECTIVE ──────────────
+
+    `protocol.py` is emphatic that the client must never learn the graph — a
+    step names an operation and never a purpose, and "a progress bar is a graph
+    disclosure in a friendly hat". So this may never say what comes NEXT.
+
+    It does not have to. Every word here describes a step that has ALREADY run,
+    and the past is not the graph's future. `executor.execute` returns the
+    figures and `Run.step` records them by op before the round trip, so the
+    client already knows what it just found out, in numbers, as it finds them.
+
+    Only figures this step added, and only ones carrying a LABEL.
+    `_FIGURE_LABELS` is the same vocabulary the closing recap uses — a figure
+    called one thing while it streams and another when it lands is two figures
+    to a reader.
+    """
+    fresh: dict[str, Any] = {}
+    for op, blob in (getattr(run, "figures", {}) or {}).items():
+        if op in before or not isinstance(blob, dict):
+            continue
+        fresh.update(blob)
+
+    parts: list[str] = []
+    # A STATUS OR A VERDICT OUTRANKS A NUMBER. "the book again" is the entire
+    # result of an overlap run, and printing a correlation instead is how the
+    # one conclusion becomes the one thing left unsaid.
+    for key in ("status", "verdict"):
+        word = fresh.get(key)
+        if isinstance(word, str) and word:
+            parts.append(bold(word.replace("_", " ")))
+            break
+    for key, (label, unit) in _FIGURE_LABELS.items():
+        if len(parts) >= 3:  # three is a line; more is a table, and one lands below
+            break
+        v = fresh.get(key)
+        if isinstance(v, (int, float)) and not isinstance(v, bool):
+            parts.append(f"{label} {bold(_num(v))}{(' ' + unit) if unit else ''}")
+    return f" {DOT} ".join(parts)
 
 
 def _drive(run: Any, *, quiet: bool = False) -> None:
-    """Execute the run, narrating each step.
+    """Execute the run, narrating each step BY WHAT IT FOUND.
 
     Wraps `Run.step` rather than calling `drive()` so there is something to
     watch. The loop itself — what is permitted, in what order, what stops it —
     is still entirely the server's.
+
+    IT USED TO PRINT THE OP NAME AND A DURATION: `server -> compute.screen 1.2s`.
+    That is a progress log. A quant watching it learned which functions fired
+    and never what was being found out — and the process IS the product here, so
+    a run that will not say what it is discovering is showing the wrong half.
     """
     n = 0
     failures: dict[str, int] = {}
@@ -1128,6 +1274,7 @@ def _drive(run: Any, *, quiet: bool = False) -> None:
         for step in batch:
             op = step.get("op", "?")
             before = run.status
+            seen = set(getattr(run, "figures", {}) or {})
             # THE STEP IS WATCHED WHILE IT RUNS, not announced and then silent.
             # `compute.*` executes in-process against the caller's own frames, so
             # this is the one place in the product where a long wait is entirely
@@ -1160,7 +1307,12 @@ def _drive(run: Any, *, quiet: bool = False) -> None:
                     }
                     return
             elif not quiet:
-                say(f"  {dim('server ' + ARROW)}  {bold(op)}  {took}")
+                # WHAT IT FOUND, or the op when it produced nothing nameable —
+                # a step with no labelled figure is a real thing (`record.*`,
+                # `emit.*` seal rather than measure) and printing a blank line
+                # for it would read as a stall.
+                found = _found(seen, run)
+                say(f"  {dim(ARROW)}  {found or bold(op)}  {took}")
 
             if run.status != "open":
                 return
@@ -1261,6 +1413,7 @@ def _report(run: Any) -> int:
     if run.status == "closed":
         say(green("Closed.") + " " + dim(str((run.artifact or {}).get("workflow", ""))))
         _render_artifact(run.artifact or {})
+        _say_gaps(run)
         _where_it_lives(run)
         _say_next(run)
         return 0
@@ -1268,6 +1421,10 @@ def _report(run: Any) -> int:
         stop = run.stopped or {}
         say(yellow("Stopped.") + " " + str(stop.get("reason", "")))
         say(dim("  A stop is a result. The run did what it was built to do."))
+        # A STOP GETS ITS GAPS TOO, and needs them more than a close does: the
+        # run refused to answer, so what it could not cover is most of what
+        # there is to know about it.
+        _say_gaps(run)
         _where_it_lives(run)
         return 0
     if run.status == "abandoned":
@@ -1284,6 +1441,96 @@ def _report(run: Any) -> int:
     return 1
 
 
+def _say_diff(run: Any) -> None:
+    """WHAT MOVED since the last file of the same label.
+
+    Nobody reads a hundred ranked names every morning; they read what changed. A
+    weekly screen's real question is the delta, and until now it was answerable
+    only in a browser — from the one place the person asking it is least likely
+    to want to leave.
+
+    NO PREDECESSOR IS ITS OWN SENTENCE. "First file of this label — nothing to
+    compare against" and "nothing moved" are opposite answers on the one morning
+    somebody is looking hardest, and collapsing them is the failure the
+    `first_file` flag exists to prevent.
+    """
+    try:
+        diff = run.filed_diff()
+    except Exception:  # noqa: BLE001 — a delta is worth losing; a result is not
+        return
+    if not diff:
+        return
+
+    if diff.get("first_file"):
+        say(dim("  First file under this label — nothing to compare against yet."))
+        return
+
+    n_in = int(diff.get("n_entered") or 0)
+    n_out = int(diff.get("n_exited") or 0)
+    n_moved = int(diff.get("n_moved") or 0)
+    n_held = len(diff.get("held") or [])
+    if not (n_in or n_out or n_moved):
+        say(dim(f"  Nothing moved against {diff.get('compared_with')} {DOT} {n_held} names, same ranking."))
+        return
+
+    parts = []
+    if n_in:
+        parts.append(green(f"{n_in} in"))
+    if n_out:
+        parts.append(red(f"{n_out} out"))
+    if n_moved:
+        parts.append(f"{n_moved} re-ranked")
+    parts.append(dim(f"{n_held} unchanged"))
+    say(f"  {dim('vs ' + str(diff.get('compared_with')))} {DOT} " + f" {DOT} ".join(parts))
+
+    # THE NAMES, not just the counts — a count tells you something happened and
+    # a desk still has to open a browser to find out what.
+    for key, colour, word in (("entered", green, "in"), ("exited", red, "out")):
+        names = [str(r.get("ticker")) for r in (diff.get(key) or []) if r.get("ticker")]
+        if names:
+            shown = ", ".join(names[:12])
+            more = f" +{len(names) - 12} more" if len(names) > 12 else ""
+            say(f"    {colour(word)}  {dim(shown + more)}")
+
+
+def _say_gaps(run: Any) -> None:
+    """WHAT THIS RUN DOES NOT TELL YOU, printed where it can still be acted on.
+
+    The quant sees the gap at the moment of the run — before delivering, while
+    closing it is still cheap — and the PM sees the SAME derived object on the
+    run's page at the moment of the decision. One derivation, two readings; that
+    is the whole reason it lives on the server rather than in this file.
+
+    THE VOICE IS THE ONE THIS TERMINAL ALREADY USES FOR MEASUREMENT FACTS:
+    quiet, factual, no colour. A gap is not a warning — it is a statement about
+    what was and was not asked, and amber on "nobody has measured these scores
+    yet" would make a normal Tuesday read as an alarm.
+
+    Never fatal. `Run.gaps()` swallows its own transport failures and returns
+    `[]`, so a server that cannot answer costs the block and not the result.
+    """
+    try:
+        gaps = run.gaps()
+    except Exception:  # noqa: BLE001 — a recap must never take the run down
+        return
+    if not gaps:
+        return
+
+    say("")
+    say(dim("  What this does not tell you"))
+    for g in gaps:
+        says = str(g.get("says") or "").strip()
+        if not says:
+            continue
+        for i, line in enumerate(_wrap(says, 72)):
+            say(("    " if i else "  " + dim("·") + " ") + dim(line))
+        # THE REMEDY IS A COMMAND, not a suggestion to think about it. A gap
+        # that cannot name one prints nothing here rather than a vague verb.
+        closes = str(g.get("closes_with") or "")
+        if closes:
+            say("    " + dim("closes with ") + f"alphaengine run {closes}")
+
+
 def _say_next(run: Any) -> None:
     """The next verb, derived from what the run actually produced.
 
@@ -1317,7 +1564,7 @@ def _say_next(run: Any) -> None:
     elif flat.get("deflated_sharpe") is not None:
         line = "find where it breaks: run stress_study --input turnover=<one-way per period>"
     elif flat.get("target_weight") is not None:
-        line = "record the fill against your Book in the portal."
+        line = "record the fill on the Portfolio, or take the whole list at once."
     elif flat.get("mean_ic") is not None:
         line = "it carries information; give it a simulator: run validate_study --project <module>"
     elif "usable" in flat:
@@ -1342,7 +1589,7 @@ def _say_next(run: Any) -> None:
             else "the data is clean: run screen_universe"
         )
     elif flat.get("status") == "breached":
-        line = "the sleeve page shows the breach against its budget."
+        line = "it crossed a line: the breach is waiting for the desk in the portal."
 
     if line:
         say(dim(f"  next {DOT} ") + line)
@@ -1362,11 +1609,10 @@ def _where_it_lives(run: Any) -> None:
     if not run_id:
         return
     say("")
-    say(
-        dim(f"  Recorded {DOT} ")
-        + f"{run_id}"
-        + dim(f" {DOT} on your account. Open Work in the portal to see it rendered.")
-    )
+    # THE URL, NOT THE ID. A reader who has to know that `/portal/runs/<id>`
+    # exists is a reader who does not open it. Most terminals make this
+    # clickable; the ones that do not still let it be copied whole.
+    say(dim("  Recorded ") + f"{portal_url()}/portal/runs/{run_id}")
 
 
 #: How many shortlist rows the terminal prints before saying how many it kept
@@ -2862,6 +3108,12 @@ def cmd_repl(args: argparse.Namespace) -> int:
         if verb == "workflows":
             cmd_workflows(args)
             continue
+        if verb == "runs":
+            # THE SESSION HAS ONE TOO, and it is the same record. A quant
+            # mid-session asking "what have I already tried" should not have to
+            # leave to find out.
+            cmd_runs(argparse.Namespace(url=args.url, key=args.key, limit=25))
+            continue
         if verb == "status":
             say(dim("no run yet") if last is None else f"{last.run_id}  {last.status}")
             continue
@@ -3076,6 +3328,8 @@ def build_parser() -> argparse.ArgumentParser:
     sub.add_parser("version", parents=[common], help="print the version")
     sub.add_parser("workflows", parents=[common], help="list what the server offers")
     sub.add_parser("demo", parents=[common], help="run the built-in example, offline")
+    rl = sub.add_parser("runs", parents=[common], help="your own week: what ran, and what it decided")
+    rl.add_argument("--limit", type=int, default=25, help="how many to show (default 25)")
     sub.add_parser("logout", parents=[common], help="remove stored credentials")
     d = sub.add_parser("commands", parents=[common], help="every command, grouped")
     d.add_argument("verb", nargs="?", help="expand one command in full")
@@ -3143,6 +3397,7 @@ def main(argv: list[str] | None = None) -> int:
     handlers: dict[str | None, Callable[[argparse.Namespace], int]] = {
         "version": cmd_version,
         "workflows": cmd_workflows,
+        "runs": cmd_runs,
         "demo": cmd_demo,
         "logout": cmd_logout,
         "commands": cmd_commands,

{alphaengine-0.3.0 → alphaengine-0.4.0}/src/alphaengine/client/executor.py

@@ -61,19 +61,26 @@ Figures = dict[str, Any]
 Workspace = dict[str, Any]
 Handler = Callable[[Figures, Workspace], Figures]
 
-# Mirrors the server's guard. Enforced on our side too, because "the data never
-# leaves" should not depend on the other end remembering to check.
-MAX_FIGURE_LIST = 64
+# Mirrors the server's guard (`harness/vocabulary.MAX_LIST_LEN`). Enforced on
+# our side too, because "the data never leaves" should not depend on the other
+# end remembering to check. THE TWO MUST MOVE TOGETHER: a client cap above the
+# server's turns every long figure into a rejected step, and one below it
+# silently truncates work the server would have accepted.
+MAX_FIGURE_LIST = 512
 
 # ── the story figures, bounded by construction ─────────────────────────────
-# A run's detail page can only draw what travels, and what travels must be a
-# SHAPE, never a series — the same bargain profile.py strikes with
-# `live_by_period`. So the paths below are bucketed HERE, from data this
-# machine already holds, to at-or-under the wire's 64-element bound: a derived
-# summary of the caller's own backtest, not the backtest.
-CURVE_POINTS = 64  # the best configuration's path, and its drawdown
-IC_POINTS = 48  # per-period ICs
-COST_POINTS = 24  # cost rungs — it is a handful of levels
+# A run's detail page can only draw what travels, and what travels is a DERIVED
+# SUMMARY of the caller's own backtest — never their input series.
+#
+# RAISED 2026-08-08 with the wire (64 -> 512). At the old bound these curves
+# arrived pre-bucketed to 64 points, which is a sketch of a curve rather than
+# the curve: a 500-day equity path collapsed to 64 buckets loses every drawdown
+# shorter than eight sessions, and the drawdowns are the part a reader is
+# looking for. The bucketing still happens HERE, on the machine that holds the
+# data, so a longer history is still summarised rather than shipped whole.
+CURVE_POINTS = 512  # the best configuration's path, and its drawdown
+IC_POINTS = 256  # per-period ICs
+COST_POINTS = 64  # cost rungs — still a handful of levels in practice
 
 
 def _bucketed(
@@ -374,11 +381,16 @@ class StepExecutor:
         # The parameter surface, per trial — the artifact a sweep exists to
         # produce, and a derived statistic per configuration, so recording it
         # crosses no data boundary. Sent only when the WHOLE grid fits the
-        # wire's 64-element cap: a sampled surface would read as the full one,
-        # which is exactly the misrepresentation the cap exists to prevent.
-        # Failed trials are omitted so a configuration that did not run renders
-        # as a hole in the surface, never as a number.
-        if result.n_trials <= 64:
+        # wire's cap: a sampled surface would read as the full one, which is
+        # exactly the misrepresentation the cap exists to prevent. Failed trials
+        # are omitted so a configuration that did not run renders as a hole in
+        # the surface, never as a number.
+        #
+        # BOUND TO THE CAP RATHER THAN REPEATING IT. This was a literal 64 while
+        # the cap was 64, so raising one silently left the other — and the
+        # symptom would have been a 300-configuration surface still reporting
+        # `trials_recorded: false` for no visible reason.
+        if result.n_trials <= MAX_FIGURE_LIST:
             figures["trials"] = [
                 {**t.params, "sharpe": t.sharpe_annualized} for t in result.trials if t.failed is None
             ]
@@ -659,7 +671,59 @@ class StepExecutor:
                 "compute.overlap found `book_returns` but no candidate. Put the "
                 "idea's own series under `returns`."
             )
-        return dict(overlap_stats(candidate, book))
+        out = dict(overlap_stats(candidate, book))
+
+        # THE STORY FIGURES. A correlation and a beta are two numbers standing
+        # in for a relationship, and a desk cannot act on the summary alone:
+        #
+        #   the SCATTER is the joint distribution the correlation summarises,
+        #   and it is where you see that a 0.2 reading is really a cloud plus
+        #   four shared crashes;
+        #
+        #   ROLLING CORRELATION is whether the reading is stable. An idea that
+        #   averages 0.2 to the book but runs at 0.9 in every drawdown is the
+        #   book again exactly when it matters, and the average says the
+        #   opposite. This is the figure that changes a sizing decision.
+        #
+        # Both are derived from the caller's own two series, on this machine,
+        # and bounded before anything travels.
+        if out.get("correlation") is not None:
+            c = np.asarray(candidate, dtype=float)
+            b = np.asarray(book, dtype=float)
+            depth = int(out.get("n_obs") or min(c.size, b.size))
+            c, b = c[-depth:], b[-depth:]
+
+            stride = max(1, depth // CURVE_POINTS)
+            out["overlap_scatter"] = [
+                {"x": round(float(b[i]), 6), "y": round(float(c[i]), 6)} for i in range(0, depth, stride)
+            ]
+
+            # A quarter of the history, floored so the window is a measurement
+            # rather than a coincidence, and skipped entirely when the series
+            # is too short to roll — a rolling reading over 12 points would be
+            # noise drawn as a trend.
+            window = max(20, depth // 4)
+            if depth >= window * 2:
+                rolling: list[float] = []
+                for end in range(window, depth + 1):
+                    cw, bw = c[end - window : end], b[end - window : end]
+                    sc, sb = float(cw.std(ddof=1)), float(bw.std(ddof=1))
+                    if sc == 0 or sb == 0:
+                        rolling.append(float("nan"))
+                        continue
+                    cov = float(np.mean((cw - cw.mean()) * (bw - bw.mean())))
+                    rolling.append(cov / (sc * sb) * window / (window - 1))
+                clean = [v for v in rolling if v == v]
+                if clean:
+                    out["rolling_correlation"] = [
+                        {"i": i + window, "v": round(v, 6)}
+                        for i, v in _bucketed(rolling, CURVE_POINTS, _last)
+                        if v == v
+                    ]
+                    out["rolling_window"] = window
+                    out["max_rolling_correlation"] = round(max(clean), 6)
+                    out["min_rolling_correlation"] = round(min(clean), 6)
+        return out
 
     # ── emit / record ──────────────────────────────────────────────────────
     #

{alphaengine-0.3.0 → alphaengine-0.4.0}/src/alphaengine/client/session.py

@@ -133,6 +133,52 @@ class Run:
         out = self.session._get(f"/api/harness/runs/{self.run_id}/trace")
         return list(out.get("events") or [])
 
+    def gaps(self) -> list[Figures]:
+        """WHAT THIS RUN DOES NOT TELL YOU.
+
+        Derived server-side by a query over the record — which of the eight
+        questions were asked, of what data, and when — and never by a model. A
+        gap a model was invited to find is one it can decline to find, and worse
+        one it can invent. Each gap names the workflow that closes it, which is
+        what makes it a next step rather than an observation.
+
+        NEVER RAISES. A recap that cannot list its gaps is still worth printing;
+        one that takes the result down with it is not. `[]` covers both "none
+        found" and "could not ask", so the caller that needs to distinguish them
+        has to say so itself.
+        """
+        try:
+            out = self.session._get(f"/api/harness/runs/{self.run_id}/gaps")
+        except (Offline, ServerError):
+            return []
+        return list(out.get("gaps") or [])
+
+    def filed_diff(self) -> Figures | None:
+        """What moved since the last file of the same label, or None.
+
+        NOBODY READS A HUNDRED RANKED NAMES EVERY MORNING; they read what moved.
+        A weekly screen's real question is the delta, and it was answerable only
+        in a browser while the person asking it was in a terminal.
+
+        `first_file` distinguishes NO PREDECESSOR from NOTHING CHANGED, which
+        are opposite answers on the one morning somebody is looking hardest —
+        so the caller must not collapse them.
+
+        None means the run filed nothing, or the diff could not be read. Never
+        raises: a delta is worth losing, a result is not.
+        """
+        try:
+            filed = self.session._get("/api/me/signals?limit=60")
+        except (Offline, ServerError):
+            return None
+        mine = [f for f in (filed.get("signals") or []) if f.get("source_run_id") == self.run_id]
+        if not mine:
+            return None
+        try:
+            return self.session._get(f"/api/me/signals/{mine[0].get('id')}/diff")
+        except (Offline, ServerError):
+            return None
+
     def step(self, step: Figures) -> Figures:
         """Execute one permitted step locally and report the figures."""
         attempt_id = uuid.uuid4().hex
@@ -276,6 +322,21 @@ class Session:
         """Names and versions. That is all a client is given, and all it needs."""
         return list(self._get("/api/harness/workflows").get("workflows") or [])
 
+    def recent_runs(self, limit: int = 25) -> list[Figures]:
+        """YOUR OWN WEEK: what ran, what it decided, what it filed.
+
+        The terminal could start work and could not show you any of it, so "what
+        did I already try" was a question you had to open a browser to ask —
+        from the one place you are least likely to want to leave.
+
+        Rows carry the verdict, the honest trial count with its provenance, and
+        the stop reason where there is one. Mostly stops, which is the point:
+        the dead ends are the majority of a week's output and the part that
+        evaporates everywhere else.
+        """
+        out = self._get(f"/api/harness/runs?limit={int(limit)}")
+        return list(out.get("runs") or [])
+
     def universes(self) -> list[Figures]:
         """Universes you registered in the portal: names, and the SYMBOLS in them.
 

{alphaengine-0.3.0 → alphaengine-0.4.0}/src/alphaengine/commands.py

@@ -92,6 +92,7 @@ FLAGS: dict[str, Flag] = {
     "label": Flag("--label", "TEXT", "what to call the artifact this run produces"),
     "input": Flag("--input", "K=V", "a workflow input; repeatable"),
     "quiet": Flag("--quiet", "", "only the result, no step narration"),
+    "limit": Flag("--limit", "N", "how many rows to show (default 25)"),
 }
 
 
@@ -192,6 +193,26 @@ COMMANDS: tuple[Command, ...] = _question_commands() + (
         ),
         examples=("alphaengine demo",),
     ),
+    Command(
+        verb="runs",
+        group="start",
+        args="[--limit N]",
+        scope="both",
+        purpose="your own week: what ran, what it decided, what it filed",
+        body=(
+            "The terminal could START work and could not show you any of it, so "
+            '"what did I already try" was a question you had to open a browser to '
+            "ask, from the one place you are least likely to want to leave.\n\n"
+            "MOSTLY STOPS, AND THAT IS THE POINT. The dead ends are the majority "
+            "of a research week and the part that evaporates everywhere else, so a "
+            "stopped run prints its REASON here rather than only its token: the "
+            "sentence is the most useful thing the run produced.\n\n"
+            "Every row carries the honest trial count WITH its provenance, because "
+            "a count that was derived from a grid that ran and one that was "
+            "asserted are different claims about the same number."
+        ),
+        examples=("alphaengine runs", "alphaengine runs --limit 50"),
+    ),
     Command(
         verb="workflows",
         group="start",

{alphaengine-0.3.0 → alphaengine-0.4.0}/src/alphaengine/core/signals.py

@@ -41,7 +41,14 @@ import numpy as np
 
 from .series_shapes import series_values
 
-MAX_PERIODS = 64
+#: The longest per-period sequence a reading reports, and the longest bounded
+#: name list beside it.
+#:
+#: RAISED 64 -> 512 on 2026-08-08 with the wire cap. This one is easy to miss and
+#: silently defeats the others: the core truncates `ic_by_period` HERE, before
+#: `StepExecutor` ever buckets it, so leaving this at 64 would have held IC
+#: through time at 64 points no matter what `IC_POINTS` said.
+MAX_PERIODS = 512
 _RND = 6
 
 DEFAULT_HORIZON = 21

{alphaengine-0.3.0 → alphaengine-0.4.0}/src/alphaengine/study/report.py

@@ -54,7 +54,12 @@ class ReportError(RuntimeError):
 # here rather than imported from `client` so that `alphaengine.study` never
 # pulls the client in — a guarantee `test_client.py` enforces, and one worth
 # more than not repeating fifteen lines.
-MAX_FIGURE_LIST = 64
+#
+# DUPLICATED ON PURPOSE, WHICH MEANS IT CAN DRIFT BY ACCIDENT. Raised with
+# `client.executor.MAX_FIGURE_LIST` on 2026-08-08; `test_client.py` holds the
+# two equal so the deliberate duplication cannot become an accidental
+# disagreement.
+MAX_FIGURE_LIST = 512
 
 
 def _guard(payload: dict[str, Any]) -> dict[str, Any]:

{alphaengine-0.3.0 → alphaengine-0.4.0}/tests/test_cli.py

@@ -1322,3 +1322,171 @@ def test_an_unreachable_portal_is_not_an_error_here():
             raise RuntimeError("offline")
 
     assert cli._universe_named_in("screen my sp100 universe", _Down()) is None
+
+
+# ── the run narrates itself, and never leaks the graph ─────────────────────
+#
+# The terminal used to print `server -> compute.screen 1.2s`: which functions
+# fired, never what was being found out. These hold the replacement to the one
+# rule that makes it safe — NARRATION IS RETROSPECTIVE. Every line describes a
+# step that has already run, so the past cannot disclose the graph's future.
+
+
+class _Narrating:
+    """A run whose figures have just gained one op's worth of results."""
+
+    def __init__(self, figures):
+        self.figures = figures
+
+
+def test_narration_reports_only_what_the_last_step_added():
+    before = {"compute.profile": {"universe_size": 500}}
+    run = _Narrating({**before, "compute.screen": {"n_evaluated": 431, "n_insufficient": 56}})
+    line = cli._found(set(before), run)
+    assert "431" in line and "56" in line
+    # The earlier step's figure is not restated — it was already narrated.
+    assert "500" not in line
+
+
+def test_a_verdict_outranks_a_number():
+    """ "the book again" is the entire result of an overlap run; a correlation
+    printed instead is the one conclusion left unsaid."""
+    run = _Narrating({"compute.overlap": {"correlation": 0.91, "verdict": "the_book_again"}})
+    line = cli._found(set(), run)
+    assert line.index("the book again") < line.index("0.91")
+
+
+def test_a_status_leads_the_line():
+    run = _Narrating({"compute.monitor": {"status": "breached", "n_obs": 250}})
+    assert cli._found(set(), run).startswith(cli.bold("breached"))
+
+
+def test_narration_never_names_an_op_or_a_stage():
+    """Rule 1 of the protocol: a step names an OPERATION, and the reader of this
+    line must not learn even that. Stage names are the graph's shape."""
+    run = _Narrating({"compute.screen": {"n_evaluated": 431}})
+    line = cli._found(set(), run)
+    assert "compute" not in line and "screen" not in line
+
+
+def test_a_step_that_produced_no_labelled_figure_narrates_nothing():
+    """`emit.*` and `record.*` seal rather than measure. The caller prints the
+    op in that case — a blank line would read as a stall."""
+    run = _Narrating({"emit.study": {"artifact_id": "abc", "sealed": True}})
+    assert cli._found(set(), run) == ""
+
+
+def test_narration_is_bounded_to_a_line():
+    run = _Narrating({"compute.all": {k: 1.0 for k in list(cli._FIGURE_LABELS)[:9]}})
+    assert cli._found(set(), run).count(cli.DOT) <= 2  # three parts, two separators
+
+
+# ── the gaps block ─────────────────────────────────────────────────────────
+
+
+def test_the_gap_block_prints_the_sentence_and_the_command(capsys):
+    class _R:
+        def gaps(self):
+            return [
+                {
+                    "code": "scores_never_measured",
+                    "kind": "sequence",
+                    "says": "These names are ranked by a score nothing has measured.",
+                    "closes_with": "evaluate_signal",
+                }
+            ]
+
+    cli._say_gaps(_R())
+    out = capsys.readouterr().out
+    assert "What this does not tell you" in out
+    assert "nothing has measured" in out
+    # THE REMEDY IS A COMMAND, not a suggestion to think about it.
+    assert "alphaengine run evaluate_signal" in out
+
+
+def test_a_gap_with_no_remedy_prints_no_command(capsys):
+    class _R:
+        def gaps(self):
+            return [
+                {
+                    "code": "engine_moved_on",
+                    "kind": "provenance",
+                    "says": "Computed on an older engine.",
+                    "closes_with": "",
+                }
+            ]
+
+    cli._say_gaps(_R())
+    out = capsys.readouterr().out
+    assert "older engine" in out and "alphaengine run" not in out
+
+
+def test_no_gaps_prints_no_heading(capsys):
+    class _R:
+        def gaps(self):
+            return []
+
+    cli._say_gaps(_R())
+    assert capsys.readouterr().out == ""
+
+
+def test_a_recap_never_takes_the_run_down(capsys):
+    """The result is already on screen; losing the gap block costs a block."""
+
+    class _R:
+        def gaps(self):
+            raise RuntimeError("the server is having a day")
+
+    cli._say_gaps(_R())
+    assert capsys.readouterr().out == ""
+
+
+# ── the portal bridge points at addresses that exist ───────────────────────
+#
+# The CLI printed a bare run id and named four screens that had been redirects
+# for months: "Work", "the sleeve page", "your Book", and — worst — "accept it
+# in the portal", pointing at a proposal surface that no longer exists at all.
+# An id nobody can turn into a URL is a reference to nothing.
+
+
+def test_a_run_is_printed_as_a_url_not_a_bare_id(capsys, monkeypatch):
+    monkeypatch.delenv("QUANTOS_PORTAL_URL", raising=False)
+    monkeypatch.delenv("QUANTOS_API_URL", raising=False)
+
+    class _R:
+        run_id = "run_abc123"
+
+    cli._where_it_lives(_R())
+    out = capsys.readouterr().out
+    assert "https://qosai.app/portal/runs/run_abc123" in out
+
+
+def test_the_portal_follows_the_api_to_localhost(monkeypatch):
+    """A CONFIG DEFAULT THAT IS PRESENT AND WRONG is worse than one that is
+    missing. Sending somebody to the hosted portal to read a run that exists
+    only on their machine is that failure exactly."""
+    monkeypatch.delenv("QUANTOS_PORTAL_URL", raising=False)
+    monkeypatch.setenv("QUANTOS_API_URL", "http://localhost:8000")
+    assert cli.portal_url() == "http://localhost:3000"
+
+
+def test_the_portal_url_is_overridable(monkeypatch):
+    """A self-hosted deployment must not send its users to ours."""
+    monkeypatch.setenv("QUANTOS_PORTAL_URL", "https://research.example.com/")
+    assert cli.portal_url() == "https://research.example.com"
+
+
+def test_no_line_names_a_screen_that_is_a_redirect():
+    """Four names that had been redirects since Phase 8. This asserts the
+    SOURCE rather than one code path, because the next one to go stale will be
+    somewhere none of these tests happens to reach."""
+    import pathlib
+
+    source = pathlib.Path(cli.__file__).read_text(encoding="utf-8")
+    for gone in (
+        "Open Work in the portal",
+        "the sleeve page shows",
+        "against your Book in the portal",
+        "Open it in the portal to accept",
+    ):
+        assert gone not in source, gone

{alphaengine-0.3.0 → alphaengine-0.4.0}/tests/test_client.py

@@ -93,12 +93,16 @@ def test_sweep_records_the_parameter_surface_when_the_grid_fits():
 
 
 def test_an_oversized_grid_records_the_absence_not_a_sample():
+    """A sampled surface would read as the full one, which is the whole reason
+    the cap exists. Sized off MAX_FIGURE_LIST — at 130 trials against a literal
+    this test silently inverted when the cap went to 512 and began asserting
+    that an oversized grid IS recorded."""
+    fast = list(range(2, 15))  # 13
+    slow = list(range(20, 20 + 2 * (MAX_FIGURE_LIST // len(fast) + 2), 2))
     ex = executor()
-    out = ex.execute(
-        "compute.sweep",
-        {"grid": {"fast": list(range(2, 15)), "slow": list(range(20, 40, 2))}},
-    )
-    assert out["n_trials"] == 130
+    out = ex.execute("compute.sweep", {"grid": {"fast": fast, "slow": slow}})
+
+    assert out["n_trials"] == len(fast) * len(slow) > MAX_FIGURE_LIST
     assert "trials" not in out
     assert out["trials_recorded"] is False
 
@@ -143,14 +147,23 @@ def test_a_handler_can_be_supplied_for_ops_only_your_environment_answers():
 # ── the data does not leave, enforced on this side too ─────────────────────
 def test_the_executor_refuses_to_send_a_series():
     """Enforced client side as well as server side. 'The data stays put' should
-    not depend on the other end remembering to check."""
-    ex = StepExecutor(data=prices(), handlers={"data.describe": lambda p, w: {"px": [1.0] * 500}})
+    not depend on the other end remembering to check.
+
+    SIZED OFF THE CAP, NOT OFF A LITERAL. These fixtures were 500 and 200 while
+    the cap was 64; raising it to 512 made both of them legal payloads, and both
+    tests went green while asserting nothing at all. A guard test whose fixture
+    does not move with the threshold stops testing the guard on the day the
+    threshold moves — which is the one day you want it to fail.
+    """
+    over = [1.0] * (MAX_FIGURE_LIST + 1)
+    ex = StepExecutor(data=prices(), handlers={"data.describe": lambda p, w: {"px": over}})
     with pytest.raises(ValueError, match="stays on your machine"):
         ex.execute("data.describe", {})
 
 
 def test_a_series_is_caught_however_it_is_nested():
-    ex = StepExecutor(data=prices(), handlers={"data.describe": lambda p, w: {"a": {"b": list(range(200))}}})
+    nested = list(range(MAX_FIGURE_LIST + 1))
+    ex = StepExecutor(data=prices(), handlers={"data.describe": lambda p, w: {"a": {"b": nested}}})
     with pytest.raises(ValueError, match="series"):
         ex.execute("data.describe", {})
 
@@ -709,3 +722,31 @@ def test_cost_ladder_emits_the_curve_only_when_it_was_measured():
     # ABSENCE, never a flat line at zero.
     bare = ex.execute("compute.cost_ladder", {})
     assert "cost_curve" not in bare
+
+
+def test_the_two_figure_caps_are_equal_even_though_they_are_duplicated():
+    """`study/report.py` repeats `MAX_FIGURE_LIST` rather than importing it, so
+    that `alphaengine.study` never pulls the client in — a real guarantee, and
+    the reason the duplication exists.
+
+    Deliberate duplication still drifts by accident. Both were 64; the wire cap
+    moved to 512 on 2026-08-08 and a report path left behind would have refused
+    exactly the curves the change exists to allow, from the one code path that
+    runs with no server to correct it.
+    """
+    from alphaengine.study.report import MAX_FIGURE_LIST as REPORT_CAP
+
+    assert MAX_FIGURE_LIST == REPORT_CAP
+
+
+def test_the_core_does_not_truncate_a_sequence_before_the_executor_buckets_it():
+    """MAX_PERIODS is upstream of every story figure and silently outranks them.
+
+    `information_coefficient` truncates `ic_by_period` to MAX_PERIODS before
+    `StepExecutor` ever sees it, so a core cap below `IC_POINTS` holds the chart
+    at the core's number and nothing in the executor says why.
+    """
+    from alphaengine.core.signals import MAX_PERIODS
+
+    assert MAX_PERIODS >= IC_POINTS
+    assert MAX_PERIODS <= MAX_FIGURE_LIST

{alphaengine-0.3.0 → alphaengine-0.4.0}/tests/test_smoke.py

@@ -69,15 +69,20 @@ def test_report_refuses_a_series_before_it_leaves_the_machine():
     series hidden under any key at all. It is duplicated on the server on
     purpose: a check that runs only on the client is not a check, and one that
     runs only on the server tells you too late and without naming the field.
+
+    SIZED OFF THE CAP. The fixture was 500 elements against a cap of 64; when
+    the cap moved to 512 the payload became legal and this test would have gone
+    on passing while asserting that the guard does nothing.
     """
     import pytest
 
-    from alphaengine.study.report import _guard
+    from alphaengine.study.report import MAX_FIGURE_LIST, _guard
 
     _guard({"performance": {"sharpe": 1.2}})  # figures pass
 
+    over = list(range(MAX_FIGURE_LIST + 1))
     with pytest.raises(ValueError, match="is a series"):
-        _guard({"performance": {"totally_not_returns": list(range(500))}})
+        _guard({"performance": {"totally_not_returns": over}})
 
 
 def test_report_needs_a_key_and_says_so():