mostlyright-data 0.31.10__tar.gz → 0.31.12__tar.gz

{mostlyright_data-0.31.10 → mostlyright_data-0.31.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.31.10
+Version: 0.31.12
 Summary: Mostly Right hosted CLI for reviewed datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/

{mostlyright_data-0.31.10 → mostlyright_data-0.31.12}/skills/mr-data-build/references/preparing-table-search.md

@@ -146,7 +146,10 @@ column description.
 
 ## 6. Write the vocabulary column by column
 
-An alias maps a phrase to an exact filter, and a sort alias maps a phrase to a sort. List every
+An alias maps a phrase to an exact filter, and a sort alias maps a phrase to a sort. Once
+planning#1842 lands, the live page's search node applies the aliases and merges them with the
+planner's plan. Until then aliases are honoured only by `search explain`, and only while the
+planner is unavailable for that table. The live page applies none. List every
 declared column before you write the spec. Then generate its phrases from its type:
 
 | Column | Phrases | Spec entry |
@@ -191,7 +194,46 @@ column names, the descriptions and the planner. Never bind a word that two colum
 such as "growth", "change" or "best", unless the brief names the metric. "Highest growth"
 pointed at a revenue column turns "highest growth last 30 days" into a revenue sort.
 
-Studio caps a spec at 128 filter aliases and 64 sort aliases, and `search validate` refuses more.
+### Declare a floor for every rate
+
+A growth, change, ratio or per-unit column ranks nonsense first when its base is tiny. Revenue
+that grew from $5,000 to $80 million is 1,600,000% growth, and a film with three votes has a
+perfect rating. Sorting by such a column shows shells and placeholders, not the rows the reader
+asked for. For each sortable rate column, declare the column it is a rate of, and the smallest
+base that makes the rate meaningful, in `order_floors` (contract 4.54.0, up to 32 entries):
+
+```json
+"order_floors": [
+  {"column": "revenue_growth_pct", "base_column": "revenue_prior_year_usd", "min": 10000000},
+  {"column": "revenue_cagr_5y_pct", "base_column": "revenue_5y_ago_usd", "min": 10000000},
+  {"column": "vote_average", "base_column": "vote_count", "min": 100}
+]
+```
+
+- `column` is in `sortable_columns` or is a sort alias's column. `base_column` is another numeric
+  column in `filterable_columns`. List each base early in `filterable_columns`: a package keeps 64
+  filters, role and alias columns first and the rest in spec order, and a base past that cut
+  loses its floor. `search validate TABLE --spec` names such a floor in `warnings` under
+  `/order_floors/`; treat that warning as a floor that will not apply.
+- `min` is a whole number in the base column's own unit, written without a decimal point or
+  exponent: `10000000` on a column in dollars, `10` on a column in millions.
+- Floors are declared on a search revision with `mr-data search configure --spec`, not in the
+  recipe's `table.search`, which refuses the member. A revision configured from the recipe's own
+  spec carries none, and a new version of a private table keeps them only when you configure the
+  revision again. A plan made without the planner, such as a keystroke search, applies no floor.
+- A Studio older than contract 4.54.0 refuses the member as unknown. Configure without it there.
+- When a plan orders by `column`, in either direction, Studio adds `base_column >= min` as a
+  filter. The reader sees it in the search summary and can remove it. A query that already filters
+  `base_column` keeps its own filter.
+- Prefer the true base (the earlier period's revenue, the vote count) over a size proxy such as
+  market cap. When the table has no base column, add one in the transform: it is cheaper than a
+  wrong ranking.
+- Choose `min` from the built table with `mr-data query`: the smallest base at which the rate stops
+  being dominated by placeholders. State the floor at the start of the base column's
+  description, since the planner reads only the first 160 characters of a description.
+
+A recipe's spec takes 128 filter aliases and 64 sort aliases, and a search revision 512 and 256.
+`search validate` refuses more.
 Rank the phrases and keep the top of the list. Put first the words that name the kind of row, the
 facets users type most, the popularity sorts and the product's own vocabulary. A phrase you leave
 out maps to nothing. The planner may still recover it from the column names and values, and
@@ -200,15 +242,35 @@ nothing guarantees that.
 ## 8. Turn the planner on
 
 The planner turns a sentence into filters, sorts and preferences. Turn it on for every table with
-search. With search on, the planner plans every settled query. Only a query whose every word an
-alias resolved skips it. Set `"planner": {"enabled": true, "external_context_allowed": true}` on
-a public table. Keep
-`external_context_allowed` false on a private table unless the user or the workspace policy
-authorizes sending its context to the planner model. Data-read permission is not that consent.
-Queries with negation or "or" stay unresolved rather than becoming a guessed filter.
-
-Write each column description as if the planner reads it. Say what the column holds, its unit,
-and the words people use for it.
+search with `"enabled": true`. A query whose every word an alias resolved skips it. Queries with
+negation or "or" stay unresolved rather than becoming a guessed filter.
+
+The planner model sees the query text, the column names and their descriptions, value
+dictionaries of at most 16 columns of at most 256 short values each, the aliases and the field
+roles. It never sees rows.
+
+`external_context_allowed` is the owner's consent to send that context to the planner model:
+
+- A public table whose sources are all public gets the planner on its live page whatever the flag
+  says. Set the flag to `true` on it, so `search explain` and `capabilities.planner` match the page.
+- A private or link-shared table gets the planner only when the recipe sets the flag to `true`.
+  That is a deliberate yes from the user or the workspace policy. Data-read permission is not that
+  consent. Without that yes, keep the flag `false`.
+- Until the Studio change in planning#1844 is live, the flag changes only `search explain` and the
+  `capabilities.planner` readout. The live page plans a public table with public sources and no
+  other table.
+
+`search inspect`, `search status` and `search explain` say why the planner is unavailable in
+`planner_detail.reason`. `external_context_not_allowed` means the recipe withholds consent.
+`private_source` means a source is not public.
+
+Write each column description as if the planner reads it, because it does, and the page shows it
+to the reader beside results ordered by that column. Say what the column holds, the period it
+covers ("trailing twelve months", "latest fiscal year against the year before", "over the last
+five fiscal years"), its unit, and the words people use for it, abbreviations included
+("compound annual growth rate, CAGR"). The planner picks the column a query asks about, named
+bare ("revenue") or in a question ("what is the P/E ratio?"), from these descriptions. It reads
+the first 160 characters of each, so lead with what the column measures and its period.
 
 ### Name and describe columns for search
 
@@ -314,7 +376,8 @@ mr-data search explain TABLE_ID --version VERSION_ID --query "stocks under 10" -
 
 Read `planner_used`, `filters` and `order_by`. A query that asks for a filter or a sort and plans
 text only is a gap in the spec. Add the alias or sharpen the column description, then check again.
-`planner_used: false` on a settled query is a fault to report, unless aliases resolved every word.
+`planner_used: false` on a settled query is a fault to report, unless aliases resolved every word
+or `planner_detail.reason` says the planner is withheld.
 
 Run real queries against the live search once `package_state` is `ready`:
 

{mostlyright_data-0.31.10 → mostlyright_data-0.31.12}/skills/mr-data-build/references/recipe-test.md

@@ -43,7 +43,7 @@ Read `status`:
 | `recipe_test_cancelled` | Cancelled before it reported. | 2 |
 | `recipe_test_awaiting_confirmation` | Held for a size confirmation. Run `confirm_command`, then ask again. The hold is a size check, not a charge. | 2 |
 | `recipe_test_started` | `--no-wait` returned before the report. | 0 |
-| `recipe_test_still_running` | Not reported within the wait. Ask again with the same bounds. | 2 |
+| `recipe_test_still_running` | Not reported within the wait. `test_status: queued` means no worker holds the test yet, so nothing is wrong with the recipe. Ask again with the same bounds. | 2 |
 | `recipe_test_skipped` | Nothing was tested. `test.reason` says why: `not_served` (Studio predates the test), `engine_unsupported` (the recipe runs on the Keel engine) or `worker_unsupported` (the worker predates the test and refused it `JOB_INVALID`). | 0 |
 
 Asking again with the same bounds reads a running test back, and a completed test replays its
@@ -66,8 +66,9 @@ page is fetched twice, and the receipt's `recipe_test` block names the test run.
 When the test finds a blocking problem, fails, is held or is still running after those five
 minutes, the full is not started. The status is `run_stopped_by_test`,
 `run_test_awaiting_confirmation` or `run_test_still_running`, `run_id` names the test, and the
-command exits 2. Running the same command again picks a running test back up, replays a finished
-one, and tests again after a failure. `next` ends with the command that starts the
+command exits 2. `test.test_status: queued` on `run_test_still_running` means no worker had
+picked the test up; `mr-data status RUN_ID` says when one has. Running the same command again
+picks a running test back up, replays a finished one, and tests again after a failure. `next` ends with the command that starts the
 same full without the test. Repair the recipe first. Skip the test only when the user decides the
 problem does not matter:
 

{mostlyright_data-0.31.10 → mostlyright_data-0.31.12}/src/mostlyright/data_harness/thin/activity.py

@@ -50,7 +50,7 @@ from time import monotonic
 from typing import Any
 
 from mostlyright.data_harness.thin import THIN_SCHEMA_PREFIX
-from mostlyright.data_harness.thin.session import StudioSession, dataset_dashboard_url
+from mostlyright.data_harness.thin.session import StudioSessionProvider, dataset_dashboard_url
 from mostlyright.data_harness.thin.transport import (
     REQUEST_TIMEOUT_SECONDS,
     ThinLaneError,
@@ -931,8 +931,9 @@ def _document_counts(document: Mapping[str, Any]) -> tuple[int, int]:
 #: One session per process, because two reports in one command -- ``recipe`` says one thing before
 #: it registers and another after -- must not buy two token exchanges. It is never shared with a
 #: command's own client: those open their own, and a cache reaching across the two would make a
-#: progress report able to break a command by holding an expired token.
-_SESSION: StudioSession | None = None
+#: progress report able to break a command by holding an expired token. It is a provider, so the
+#: clients built on it share one renewal when the token nears its expiry rather than one each.
+_SESSION: StudioSessionProvider | None = None
 
 #: The verb's transport, which is cached because its clock is a constant. The automatic half's is
 #: not cached and cannot be: its clock is a deadline, and a deadline belongs to one report.
@@ -993,11 +994,11 @@ def _reporting_client(budget: _Budget) -> StudioV4ActivityClient:
 
 def _client_on(transport: Transport) -> StudioV4ActivityClient:
     global _SESSION
-    from mostlyright.data_harness.thin.session import open_studio_session
+    from mostlyright.data_harness.thin.session import open_renewable_session
     from mostlyright.data_harness.ux.credentials import resolve_cloud_credentials
 
     if _SESSION is None:
-        _SESSION = open_studio_session(resolve_cloud_credentials(), transport=transport)
+        _SESSION = open_renewable_session(resolve_cloud_credentials(), transport=transport)
     return StudioV4ActivityClient(_SESSION, transport=transport)
 
 

{mostlyright_data-0.31.10 → mostlyright_data-0.31.12}/src/mostlyright/data_harness/thin/recipe_test.py

@@ -49,6 +49,7 @@ from mostlyright.data_harness.thin.v4_runs import (
     CONFIRM_REQUIRED_CODE,
     TERMINAL_RUN_STATUSES,
     StudioV4RunClient,
+    attempt_progress_members,
     confirm_held_command,
     failure_sentence,
     failure_triple,
@@ -515,6 +516,12 @@ def reading(run: Mapping[str, Any]) -> tuple[str, dict[str, Any]]:
 #: under. It is not a status word: the status is still :data:`FAILED`, with ``room_fault: true``.
 ROOM_FAULT = "room_fault"
 
+#: The sentence key for a test still ``queued`` when the wait ended: no worker holds it. It is not
+#: a status word -- the status stays ``recipe_test_still_running`` / ``run_test_still_running`` --
+#: it is which ``next`` and headline that status gets, because "running" was untrue of a test no
+#: worker had picked up and sent people to look for a slow source rather than a cold queue.
+QUEUED = "queued"
+
 #: What a person does next, by what the test came to.
 _NEXT = {
     PASSED: (
@@ -662,11 +669,29 @@ def _settled(
             "confirm_command": confirm_held_command(str(run["run_id"])),
         }
     if state not in TERMINAL_RUN_STATUSES:
+        minutes = int(ceiling // 60)
+        if state == QUEUED:
+            ledger = attempt_progress_members(client, str(run["run_id"]))
+            waiting = (
+                "it is back in the queue after an earlier attempt and no worker holds it now"
+                if "progress" in ledger
+                else "no worker has picked it up yet"
+            )
+            return {
+                "status": STILL_RUNNING,
+                "headline": f"The recipe test is still queued: {waiting}, so its report is not in.",
+                **members,
+                "test_status": state,
+                **ledger,
+                "next": f"The test was still queued after {minutes} minutes: {waiting}. Ask again "
+                "with the same bounds to pick the same test back up, or check whether a worker "
+                f"has claimed it with mr-data status {run['run_id']}.",
+            }
         return {
             "status": STILL_RUNNING,
             **members,
             "test_status": state,
-            "next": f"The test had not reported after {int(ceiling // 60)} minutes. Ask "
+            "next": f"The test had not reported after {minutes} minutes. Ask "
             "again with the same bounds to pick it back up, or follow it with "
             f"mr-data watch {run['run_id']}.",
         }
@@ -786,18 +811,24 @@ def before_full(
         block = {"status": "passed", **members}
         block.pop("preflight_report", None)
         return BeforeFull(block=block, resume_capture_run_id=str(settled["run_id"]))
+    headline = members.pop("headline", None)
     test_block = {"status": status.removeprefix("recipe_test_"), **members}
-    said = ROOM_FAULT if members.get("room_fault") is True else status
-    return BeforeFull(
-        stop=_stopped(
-            status,
-            {
-                "run_id": str(settled["run_id"]),
-                "test": test_block,
-                "next": _STOPPED_NEXT[said] + _HELD_TAIL + rerun,
-            },
+    if members.get("room_fault") is True:
+        said = ROOM_FAULT
+    elif status == STILL_RUNNING and members.get("test_status") == QUEUED:
+        said = QUEUED
+    else:
+        said = status
+    sentence = _STOPPED_NEXT[said]
+    stopped: dict[str, Any] = {"run_id": str(settled["run_id"]), "test": test_block}
+    if said == QUEUED:
+        # The test's own headline, said about the full it was standing in front of.
+        sentence = sentence.format(run=settled["run_id"])
+        stopped["headline"] = str(headline).replace(
+            "so its report is not in", "so the full run was not started"
         )
-    )
+    stopped["next"] = sentence + _HELD_TAIL + rerun
+    return BeforeFull(stop=_stopped(status, stopped))
 
 
 _STOPPED_NEXT = {
@@ -814,6 +845,9 @@ _STOPPED_NEXT = {
     STILL_RUNNING: f"The recipe test had not reported after {int(FULL_WAIT_SECONDS // 60)} "
     "minutes, so the full was not started. Run this command again to pick the same test back "
     "up.",
+    QUEUED: f"The recipe test was still queued after {int(FULL_WAIT_SECONDS // 60)} minutes, "
+    "waiting for a worker, so the full was not started. Run this command again to pick the same "
+    "test back up; mr-data status {run} says whether a worker has claimed it.",
 }
 
 
@@ -847,6 +881,7 @@ __all__ = [
     "MAX_WAIT_SECONDS",
     "PASSED",
     "PREFLIGHT_COMPLETE",
+    "QUEUED",
     "ROOM_FAULT",
     "RUN_STOPPED_STATUS",
     "SKIPPED",

{mostlyright_data-0.31.10 → mostlyright_data-0.31.12}/src/mostlyright/data_harness/thin/runs.py

@@ -34,7 +34,11 @@ from mostlyright.data_harness.canonical import (
     canonical_json_bytes,
     parse_foreign_json,
 )
-from mostlyright.data_harness.thin.session import StudioSession
+from mostlyright.data_harness.thin.session import (
+    StudioSession,
+    StudioSessionProvider,
+    sessions_for,
+)
 from mostlyright.data_harness.thin.transport import (
     MAX_JSON_RESPONSE_BYTES,
     ThinLaneError,
@@ -211,15 +215,39 @@ class StudioApiClient:
     hardening, and a second ``_call`` would be a second place for the byte ceiling, the JSON
     hardening and the Studio-code translation to drift apart. Subclasses add routes; none of them
     adds a transport.
+
+    ⚠ AND EVERY CALL ASKS FOR ITS TOKEN FRESH (planning#1845). The client holds a
+    :class:`~mostlyright.data_harness.thin.session.StudioSessionProvider` rather than one token, so
+    a call made after a long wait -- the recipe test's report, a search poll, a closing read --
+    goes out on a token renewed when it had under a minute left, and a 401 on a token that was not
+    just renewed renews it once and sends the same call again, once. A session built by hand has
+    no renewal, and its 401 is final as it always was.
     """
 
-    def __init__(self, session: StudioSession, *, transport: Transport | None = None) -> None:
-        self._session = session
+    def __init__(
+        self,
+        session: StudioSession | StudioSessionProvider,
+        *,
+        transport: Transport | None = None,
+    ) -> None:
+        self._sessions = sessions_for(session)
         self._transport = transport or UrlLibTransport()
 
     @property
     def session(self) -> StudioSession:
-        return self._session
+        """The session held right now; a call renews it first when it is nearly spent."""
+
+        return self._sessions.session
+
+    @property
+    def _session(self) -> StudioSession:
+        return self._sessions.session
+
+    @property
+    def sessions(self) -> StudioSessionProvider:
+        """The provider this client's calls renew through, for a stream that should share it."""
+
+        return self._sessions
 
     @property
     def transport(self) -> Transport:
@@ -251,7 +279,6 @@ class StudioApiClient:
         headers = {
             "Accept": "application/json",
             CLIENT_HEADER: CLIENT_NAME,
-            **self._session.authorization(),
         }
         if extra_headers:
             headers.update(extra_headers)
@@ -282,10 +309,72 @@ class StudioApiClient:
             and len(raw_body) > max_request_bytes
         ):
             raise ThinLaneError("THIN_REQUEST_INVALID", "request exceeds its byte limit")
-        url = f"{self._session.studio_base_url}{path}{_query_string(query)}"
+        # A renewal made for THIS call -- ahead of expiry -- means a 401 on it is not an expiry.
+        renewals_before = self._sessions.renewals
+        selected = self._sessions.current()
+        try:
+            return self._send(
+                selected,
+                method,
+                path,
+                query=query,
+                headers=headers,
+                raw_body=raw_body,
+                expected=expected,
+                shape=shape,
+                response_headers=response_headers,
+                maximum=maximum,
+                max_members=max_members,
+            )
+        except ThinLaneError as refusal:
+            if (
+                getattr(refusal, "http_status", None) != 401
+                or not self._sessions.renewable
+                or self._sessions.renewals != renewals_before
+                # A call that carried its own bearer was refused for THAT credential.
+                or "Authorization" in headers
+            ):
+                raise
+        # The token lapsed between the check and Studio reading it, or Studio holds a shorter
+        # clock than the expiry Cloud stated. Renew once and send the same call once more; a 401
+        # never reached a handler, so the call was not applied. A second 401 is final.
+        return self._send(
+            self._sessions.renew(),
+            method,
+            path,
+            query=query,
+            headers=headers,
+            raw_body=raw_body,
+            expected=expected,
+            shape=shape,
+            response_headers=response_headers,
+            maximum=maximum,
+            max_members=max_members,
+        )
+
+    def _send(
+        self,
+        session: StudioSession,
+        method: str,
+        path: str,
+        *,
+        query: Mapping[str, Any] | None,
+        headers: Mapping[str, str],
+        raw_body: bytes | None,
+        expected: tuple[int, ...],
+        shape: type,
+        response_headers: dict[str, str] | None,
+        maximum: int,
+        max_members: int,
+    ) -> Any:
+        """One request on one session's token, and the refusal it becomes."""
+
+        url = f"{session.studio_base_url}{path}{_query_string(query)}"
+        # The session's bearer first, so a call that states its own (a deciding credential) wins.
+        sent = {**session.authorization(), **headers}
         try:
             status, raw, answered_headers = self._transport.request(
-                method, url, headers, raw_body, maximum
+                method, url, sent, raw_body, maximum
             )
             if response_headers is not None:
                 response_headers.update(answered_headers)

{mostlyright_data-0.31.10 → mostlyright_data-0.31.12}/src/mostlyright/data_harness/thin/session.py

@@ -22,6 +22,7 @@ import re
 import time
 from collections.abc import Callable, Mapping
 from dataclasses import dataclass
+from dataclasses import field as dataclass_field
 from datetime import UTC, datetime, timedelta
 from typing import Any
 from urllib.parse import quote, urlencode
@@ -169,22 +170,43 @@ TOKEN_EXCHANGE_MAX_RETRY_SECONDS = 30.0
 #: The spread is never more than the wait itself, and never subtracted from it.
 TOKEN_EXCHANGE_MAX_JITTER_SECONDS = 5.0
 
-#: How close to its expiry a Studio token is traded for a new one before a long-lived stream
-#: opens its next connection. A token that would expire mid-handshake is not worth sending.
+#: How close to its expiry a Studio token is traded for a new one before the next call or the next
+#: stream connection goes out. A token that would expire mid-call is not worth sending.
 SESSION_RENEWAL_MARGIN_SECONDS = 60.0
 
 _CLI_KEY = re.compile(r"^mr_cli_[A-Za-z0-9_-]{64}$")
 
 
+@dataclass(frozen=True)
+class SessionRenewal:
+    """How one session is traded for a fresh one: the device-key exchange, and the clock it reads.
+
+    Held by a session :func:`open_studio_session` minted, so every client built on that session can
+    renew it without each command threading the credential through by hand. It closes over the
+    device key already in this process's memory for the first exchange; nothing here writes it.
+    """
+
+    exchange: Callable[[], StudioSession]
+    now: Callable[[], datetime]
+
+    def __repr__(self) -> str:
+        return "SessionRenewal(<device-key exchange>)"
+
+
 @dataclass(frozen=True)
 class StudioSession:
-    """One short-lived Studio authority: where to call, as whom, and until when."""
+    """One short-lived Studio authority: where to call, as whom, and until when.
+
+    ``renewal`` is how to trade it for a fresh one, and ``None`` for a session that can never be
+    renewed -- one a test or a caller built by hand. It takes no part in equality or the repr.
+    """
 
     studio_base_url: str
     workspace_id: UUID
     token: str
     expires_at: datetime
     cloud_url: str
+    renewal: SessionRenewal | None = dataclass_field(default=None, compare=False, repr=False)
 
     def __repr__(self) -> str:
         return (
@@ -358,7 +380,12 @@ def open_studio_session(
     now: Callable[[], datetime] = lambda: datetime.now(UTC),
     sleep: Callable[[float], None] = time.sleep,
 ) -> StudioSession:
-    """Exchange the stored device key for a short-lived Studio token."""
+    """Exchange the stored device key for a short-lived Studio token.
+
+    The session that comes back carries its own :class:`SessionRenewal` -- this same exchange,
+    made again -- so a client built on it renews the token ahead of its expiry and once on a 401
+    (see :class:`StudioSessionProvider`) rather than outliving it.
+    """
 
     require_device_key(credentials)
     cloud_url = service_origin(credentials.cloud_url, "Cloud URL", allow_loopback_http=False)
@@ -412,6 +439,10 @@ def open_studio_session(
     expires_at = _timestamp(_text(parsed, "expires_at"), "expires_at")
     if expires_at <= now():
         raise ThinLaneError("THIN_TOKEN_EXCHANGE_FAILED", "Cloud returned an expired Studio token")
+
+    def _again() -> StudioSession:
+        return open_studio_session(credentials, transport=transport, now=now, sleep=sleep)
+
     return StudioSession(
         studio_base_url=service_origin(
             _text(parsed, "studio_base_url"), "Studio base URL", allow_loopback_http=True
@@ -420,28 +451,33 @@ def open_studio_session(
         token=_text(parsed, "token"),
         expires_at=expires_at,
         cloud_url=cloud_url,
+        renewal=SessionRenewal(exchange=_again, now=now),
     )
 
 
 class StudioSessionProvider:
-    """The Studio session a long-lived command reads through, renewed rather than outlived.
-
-    ⚠ THIS IS THE ONE PLACE THE "ONE EXCHANGE PER COMMAND" RULE BENDS, AND ONLY FOR STREAMS.
-    Every other command in this lane trades the device key once and finishes long before the
-    token expires. A ``watch`` does not: a Studio token lives for minutes and a run streams for
-    hours, and a stream that reconnects across a Cloud Run cut with the token it started with is
-    refused the moment that token lapses -- which surfaced as an opaque authorization refusal in
-    the middle of a build that was still running. So a stream asks this provider for its session
-    before every connection, and the provider re-exchanges the device key when the token has less
-    than :data:`SESSION_RENEWAL_MARGIN_SECONDS` left, or once when Studio answers 401.
-
-    ⚠ A PROVIDER WITH NO ``exchange`` NEVER RENEWS. A test, or a caller handed only a session,
-    gets exactly the behaviour it had: the session it was given, and a 401 that is final.
+    """The Studio session a command calls through, renewed rather than outlived.
+
+    ⚠ A STUDIO TOKEN LIVES FOR MINUTES AND A WAIT CAN LAST LONGER. A ``watch`` streams for hours;
+    ``run --full`` waits up to five minutes for the recipe test in front of it, and ``recipe
+    test`` twenty; the search and query polls wait on a node that is still settling. Each of those
+    used to make its follow-up call on the token minted at the start, and Studio refused it with
+    ``401 AUTHENTICATION_REQUIRED`` -- which surfaced as an authorization refusal in the middle of
+    a wait that was going fine (planning#1845). So every Studio call
+    (:class:`~mostlyright.data_harness.thin.runs.StudioApiClient`) and every stream connection asks
+    a provider for its session first, and the provider re-exchanges the device key when the token
+    has less than :data:`SESSION_RENEWAL_MARGIN_SECONDS` left. A 401 on a token that was not just
+    renewed renews once more and the caller sends the same call again, once; a second 401 is final.
+
+    ⚠ A PROVIDER WITH NO ``exchange`` NEVER RENEWS. A test, or a caller handed only a session it
+    built by hand, gets exactly the behaviour it had: the session it was given, and a 401 that is
+    final. A session :func:`open_studio_session` minted carries its exchange, and
+    :func:`sessions_for` hands it to the provider.
 
     ⚠ AND A RENEWAL MUST NAME THE SAME STUDIO AND THE SAME WORKSPACE. A stream resumes from a
-    ``Last-Event-ID`` in one Studio's cursor space; a fresh token for another origin or another
-    workspace would carry that cursor somewhere it means nothing, so the renewal is refused by name
-    rather than followed.
+    ``Last-Event-ID`` in one Studio's cursor space, and a wait reads back a run in one workspace; a
+    fresh token for another origin or another workspace would carry that cursor or that run
+    somewhere it means nothing, so the renewal is refused by name rather than followed.
 
     The device key the exchange closes over is the one already in this process's memory for the
     first exchange. Nothing here writes a token anywhere.
@@ -472,10 +508,22 @@ class StudioSessionProvider:
         return self._exchange is not None
 
     def current(self) -> StudioSession:
-        """The session to open the next connection with, renewed first when it is nearly spent."""
+        """The session to open the next connection with, renewed first when it is nearly spent.
+
+        ⚠ A RENEWAL AHEAD OF EXPIRY IS A COURTESY, NOT A GATE. When Cloud cannot mint a new token
+        right now (a cold-start 503, a 429, a 500) and the token held has not expired yet, the
+        call goes out on the token held -- which is what it did before renewal existed. Only a
+        token that has already lapsed makes the failed exchange the answer. A renewal that names
+        another Studio or workspace is refused either way.
+        """
 
         if self._exchange is not None and self._session.expires_at - self._now() < self._margin:
-            return self.renew()
+            try:
+                return self.renew()
+            except ThinLaneError as refusal:
+                lapsed = self._session.expires_at <= self._now()
+                if refusal.code == "THIN_SESSION_BINDING" or lapsed:
+                    raise
         return self._session
 
     def renew(self) -> StudioSession:
@@ -508,20 +556,25 @@ def open_renewable_session(
     now: Callable[[], datetime] = lambda: datetime.now(UTC),
     sleep: Callable[[float], None] = time.sleep,
 ) -> StudioSessionProvider:
-    """Exchange the device key once now, and keep the means to exchange it again for a stream."""
-
-    def _exchange() -> StudioSession:
-        return open_studio_session(credentials, transport=transport, now=now, sleep=sleep)
+    """Exchange the device key once now, and keep the means to exchange it again."""
 
-    return StudioSessionProvider(_exchange(), exchange=_exchange, now=now)
+    return sessions_for(open_studio_session(credentials, transport=transport, now=now, sleep=sleep))
 
 
 def sessions_for(session: StudioSession | StudioSessionProvider) -> StudioSessionProvider:
-    """A provider for what a caller holds: itself, or a session that will never be renewed."""
+    """A provider for what a caller holds: itself, or one over the session and its own renewal.
+
+    A session :func:`open_studio_session` minted renews through the exchange it carries; one built
+    by hand carries none and is never renewed.
+    """
 
     if isinstance(session, StudioSessionProvider):
         return session
-    return StudioSessionProvider(session)
+    if session.renewal is None:
+        return StudioSessionProvider(session)
+    return StudioSessionProvider(
+        session, exchange=session.renewal.exchange, now=session.renewal.now
+    )
 
 
 #: What a stated refusal code has to look like before it is interpolated into one.
@@ -960,6 +1013,7 @@ __all__ = [
     "USAGE_LIMIT_SCHEMA",
     "CloudClient",
     "CloudRouteAbsent",
+    "SessionRenewal",
     "StudioSession",
     "StudioSessionProvider",
     "approval_dashboard_url",