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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.31.10
+Version: 0.31.11
 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.11}/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 |
@@ -200,12 +203,27 @@ 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.
+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. Say what the column holds, its unit,
 and the words people use for it.
@@ -314,7 +332,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.11}/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.11}/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.11}/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.11}/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.11}/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",

{mostlyright_data-0.31.10 → mostlyright_data-0.31.11}/src/mostlyright/data_harness/thin/v4_search.py

@@ -325,11 +325,41 @@ SEARCH_PATHS = frozenset(
 )
 
 
+#: The human line for each ``planner_detail.reason`` Studio states (``table-search.schema.json``).
+#: Only the headline says these; ``result.planner_detail.reason`` stays Studio's own code in
+#: ``--json``. ``external_context_allowed`` is the recipe owner's consent to send the query and the
+#: search context -- never rows -- to the planner model; a public table whose sources are all
+#: public is planned either way, so the flag is what a private table's yes is written in.
+PLANNER_REASONS: dict[str, str] = {
+    "external_context_not_allowed": (
+        "planner consent withheld by the recipe (planner.external_context_allowed is false)"
+    ),
+    "private_source": "a source is not public",
+    "disabled": "the recipe turns it off (planner.enabled is false)",
+    "no_route": "this deployment has no planner route bound",
+    "provider_quota": "the planner provider's spend limit is spent",
+}
+
+
+def _planner_line(answer: Any) -> str | None:
+    """The planner's state in one sentence, when the answer carries ``planner_detail``."""
+
+    detail = answer.get("planner_detail") if isinstance(answer, dict) else None
+    reason = detail.get("reason") if isinstance(detail, dict) else None
+    if not isinstance(reason, str) or not reason:
+        return None
+    if reason == "available":
+        return "Planner: available."
+    return f"Planner unavailable: {PLANNER_REASONS.get(reason, reason)}."
+
+
 def _payload(verb: str, answer: dict[str, Any], **extra: Any) -> dict[str, Any]:
+    planner = _planner_line(answer)
+    headline = f"Search {verb} result." + (f" {planner}" if planner else "")
     return {
         "schema_version": f"{THIN_SCHEMA_PREFIX}-v4-search.v1",
         "status": "search_result",
-        "headline": f"Search {verb} result.",
+        "headline": headline,
         "lane": "hosted",
         "operation": verb,
         "result": answer,