mostlyright-data 0.29.7__tar.gz → 0.29.9__tar.gz

{mostlyright_data-0.29.7 → mostlyright_data-0.29.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.29.7
+Version: 0.29.9
 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.29.7 → mostlyright_data-0.29.9}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mostlyright-data"
-version = "0.29.7"
+version = "0.29.9"
 description = "Mostly Right hosted CLI for reviewed datasets"
 readme = "README.md"
 requires-python = ">=3.11"

{mostlyright_data-0.29.7 → mostlyright_data-0.29.9}/skills/mr-data-build/references/commands.md

@@ -18,7 +18,7 @@ gap rather than doing anything, and `export-hosted-candidate`, which is a backen
 | `mr-data dataset` | Bring the dataset page into existence before there is anything on it, then fill it in while somebody watches. `dataset create --name TEXT` mints it and prints the `dataset_id`, unless the user's own request already has an empty dataset open, in which case it answers `open_request_reused` with that `dataset_id` and mints nothing (`--separate` mints a new one for a different dataset); `dataset show ID` reads it back; `dataset set ID --name TEXT --topics "a,b,c" --license ID --description-file F` writes the title, the descriptive tags, the SPDX licence and the description under the version it was read at, retrying once if somebody else wrote first, and an empty `--topics` or `--license` takes that value off the page; send `--name` and `--topics` whenever you send `--description-file`, because a description sent on its own can make Studio write a new title and new tags, and read `changed` and `written_by_studio` on the receipt for every field the write moved; a saved write whose public sync fails exits 2 and reports `public_projection_synced: false` — use `dataset sync ID` to retry that sync without rewriting Studio; `dataset note ID --heading H --blocks-file B` writes one cell of the decision record that OUTLIVES every run, and `--list` reads it back; `dataset watch ID` follows the page's own event stream; `dataset activity ID --phase P --message TEXT` says what is happening right now, silently, and is never a chat message and never a cell; `dataset publish ID [--mode public|link|private]` says who can read the dataset — `public` lists it in the public directory and serves it at an address anybody can read, `link` serves it at an unlisted address, `private` takes it back to the workspace — and `dataset publish ID --show` reads that back without changing it; `dataset archive ID --confirm-name TITLE` retires the page and frees its title, deleting nothing. |
 | `mr-data recipe` | Register one recipe document — dataset, question, table plan, sources, transform, checks and units — in one call, and print the identifiers the server derived. The document is read first and every fault comes back in one refusal, each with the JSON pointer that names it; `--no-lint` sends it as written instead. Registration refuses `THIN_BRIEF_MISSING` when the dataset's record carries no answered question and no delegation, and `THIN_RECIPE_DATASET_UNBOUND` when the document names no `dataset.id`; `--delegated "their words"` writes the delegation onto the dataset and registers in the same command, and clears the first of those two and never the second. `mr-data recipe show ID` reads one back. `mr-data recipe explain FILE` (or a recipe identifier) lists every reason its table can or cannot refresh, each with a rule code and Studio's suggested repair, and exits 2 when one blocks it. `mr-data recipe forecast RECIPE_ID --digest DIGEST` says what one run would ask of each source before it runs, and exits 3 when the run would overrun today's platform quota or one attempt. `mr-data recipe readiness --table TABLE_ID --current-only` reads the revision one table runs now. [Making a table incremental](making-a-table-incremental.md#the-loop-explain-forecast-run-diagnose) says when to use each. |
 | `mr-data cover` | Generate and attach one branded 1200×630 dataset cover. Give it the dataset ID and what the image should depict; Studio fixes the model, single-color style, curated random palette, dimensions and storage. |
-| `mr-data run` | Start one run against a registered recipe, named as `--recipe RECIPE_ID --digest RECIPE_DIGEST` — both required, neither positional, and the digest is the bare hex the registration receipt printed. The mode is one of six: `sample`, `full`, `refresh`, `backfill`, `compact` and `replay`. Four have a shorthand flag (`--sample`, `--full`, `--refresh`, `--backfill`) and two do not, so write `--mode MODE`, which is accepted for every one of them. A refresh executes only Studio's persisted source-action plan, and a plan shape it does not refresh returns `RESYNC_REQUIRED` before acquisition; [which plans refresh](making-a-table-incremental.md#which-plans-refresh) lists them, and `mr-data recipe explain` says which one a table is. Use `mr-data table resync TABLE_ID --request-id UUID` for an explicit full source reread, retaining that UUID if the response is uncertain. `--backfill` states the exact window with `--window START END`. `--mode replay --sources-from RUN_ID` asks Studio to run the registered revision against the RETAINED RAW INPUTS of one named successful run of the same table: nothing is fetched from this computer, nothing is acquired again, the result is compared against that run and never becomes the live version, and it neither asks for nor records an approval. Where Studio has replay switched off, or the named run is not successful, not the same table, or no longer retains its inputs, it answers a typed refusal — report the code rather than retrying in another mode. `--sources-from` on any other mode is refused `THIN_ARGUMENT_INVALID` before anything is sent. `--max-rows` and `--max-source-bytes` bound ONE SOURCE rather than the finished table. A large run is held for a size confirmation (not a charge), which `--confirm` settles and whose printed `confirm_command` re-states every argument the request carried. `--approve-full RUN_ID` releases the full an existing legacy sample-first pair is holding once its preview has succeeded, naming either half of the pair; where the deployment still wants a person at a browser it answers `THIN_INTERACTIVE_HUMAN_REQUIRED` and names the run page. `--retry RUN_ID` tries one failed run again when its triple carries `room_fault: true`, re-stating that run's own coordinate under a byte ceiling that cannot narrow it, and refuses with the triple when the recipe was at fault. `--cancel RUN` stops one. |
+| `mr-data run` | Start one run against a registered recipe, named as `--recipe RECIPE_ID --digest RECIPE_DIGEST` — both required, neither positional, and the digest is the bare hex the registration receipt printed. The mode is one of six: `sample`, `full`, `refresh`, `backfill`, `compact` and `replay`. Four have a shorthand flag (`--sample`, `--full`, `--refresh`, `--backfill`) and two do not, so write `--mode MODE`, which is accepted for every one of them. A refresh executes only Studio's persisted source-action plan, and a plan shape it does not refresh returns `RESYNC_REQUIRED` before acquisition; [which plans refresh](making-a-table-incremental.md#which-plans-refresh) lists them, and `mr-data recipe explain` says which one a table is. Use `mr-data table resync TABLE_ID --request-id UUID` for an explicit full source reread, retaining that UUID if the response is uncertain. `--backfill` states the exact window with `--window START END`. `--mode replay --sources-from RUN_ID` asks Studio to run the registered revision against the RETAINED RAW INPUTS of one named successful run of the same table: nothing is fetched from this computer, nothing is acquired again, the result is compared against that run and never becomes the live version, and it neither asks for nor records an approval. Where Studio has replay switched off, or the named run is not successful, not the same table, or no longer retains its inputs, it answers a typed refusal — report the code rather than retrying in another mode. `--sources-from` on any other mode is refused `THIN_ARGUMENT_INVALID` before anything is sent. `--max-rows` and `--max-source-bytes` bound ONE SOURCE rather than the finished table. A large run is held for a size confirmation (not a charge), which `--confirm` settles and whose printed `confirm_command` re-states every argument the request carried. `--approve-full RUN_ID` releases the full an existing legacy sample-first pair is holding once its preview has succeeded, naming either half of the pair; where the deployment still wants a person at a browser it answers `THIN_INTERACTIVE_HUMAN_REQUIRED` and names the run page. `--retry RUN_ID` tries one failed run again when its triple carries `room_fault: true`, re-stating that run's own coordinate and ceilings and naming the failed run so Studio starts a new attempt, and refuses with the triple when the recipe was at fault. `--cancel RUN` stops one. |
 | `mr-data status` | Report which of the seven states one run is in, what it delivered and whether a ceiling cut it short, and — on a failure — what failed, where, and whether the fault was the execution room's rather than the recipe's. Exits non-zero on a failed run. `--diagnose` adds everything else Studio can say about the run: its progress, a per-row source's plan counts, its checkpoints, and how each attempt ended, with a lost attempt's cause marked as an inference. |
 | `mr-data runs` | Report this workspace's own runs: identifier, mode, state and creation time, plus the failure triple of any that failed and whether that failure was the execution room's. `--dataset DATASET_ID` narrows it to one dataset's runs, so "what have I run for this dataset?" is one scoped read, and a value that is not an identifier is refused `THIN_ARGUMENT_INVALID`. `--status` and `--mode` narrow it too and are refused `THIN_ARGUMENT_INVALID` for a word outside the seven states or the six modes; the three combine. Studio narrows before it cuts a page, so a filtered page holds the newest runs that match however many runs the workspace has. `--limit` says how many, and pages are followed to reach it; a listing that does not end says how many were read and suggests a smaller `--limit` or a narrower filter. The answer prints `next_cursor`, and `--cursor` continues from it. |
 | `mr-data watch` | Stream one run's live progress under the durable event type of each stage, resuming across stream cuts. Exits non-zero when the run failed. |

{mostlyright_data-0.29.7 → mostlyright_data-0.29.9}/skills/mr-data-build/references/live-run.md

@@ -28,8 +28,9 @@ appends again, and `watch` stops rather than reconnecting.
 
 **A terminal run is cached against `(recipe, digest, mode, clamps)`.** Re-running that exact
 coordinate replays the stored result rather than making a new attempt — a stored failure included —
-which is why `mr-data run --retry RUN_ID` moves a ceiling rather than re-sending the request as it
-was. It is also why `SANDBOX_MEMORY_BOUNDARY` reads as a source problem and is not one: it names
+which is why `mr-data run --retry RUN_ID` names the failed run to Studio rather than re-sending the
+request as it was; the ceilings stay the same unless Studio does not admit the named retry, and
+then the byte ceiling is raised as it was before. It is also why `SANDBOX_MEMORY_BOUNDARY` reads as a source problem and is not one: it names
 the source being fetched, the cause is a clean room with no delegated memory cgroup, it is
 intermittent and per-instance, and `room_fault` is true on that run so nothing has to be inferred
 from the wording. Report the failure once, retry it when supported, then report the replacement

{mostlyright_data-0.29.7 → mostlyright_data-0.29.9}/src/mostlyright/data_harness/thin/recipe.py

@@ -80,11 +80,9 @@ SHOW_SCHEMA = f"{THIN_SCHEMA_PREFIX}-recipe-read.v1"
 READINESS_SCHEMA = f"{THIN_SCHEMA_PREFIX}-recipe-readiness.v1"
 PROPOSE_SCHEMA = f"{THIN_SCHEMA_PREFIX}-recipe-propose.v1"
 
-#: The bound on the document. The same number the authoring lane bounded one of its six documents
-#: by -- four times the contract's own 262144-byte ceiling on a canonical recipe -- rather than a
-#: second number chosen here, because this document is those six documents in one and the ceiling
-#: it has to clear is the canonical form's.
-MAX_DOCUMENT_BYTES = 4 * 262_144
+#: A plain input file may occupy up to Studio's 2 MiB body ceiling. Before submission,
+#: the complete canonical UTF-8 request envelope must also fit that ceiling.
+MAX_DOCUMENT_BYTES = v4.MAX_RECIPE_REQUEST_BYTES
 
 #: ``recipe.schema.json#/$defs/recipe_document``'s required members, in the order the schema lists
 #: them. Checked here before the network, for the reason every early refusal in this client
@@ -1187,6 +1185,9 @@ def register(
     """
 
     document = read_document(Path(args.target))
+    # UUIDs have fixed wire length. Refuse an oversized envelope before credentials,
+    # capability reads or delegation writes; the actual client checks it again.
+    v4.recipe_registration_body(document, "00000000-0000-0000-0000-000000000000")
     # New grammar must be refused as unserved before local lint can diagnose its shape.
     keyless = any(
         capability == "keyless_window" for _, capability in recipe_explain.gated_grammar(document)

{mostlyright_data-0.29.7 → mostlyright_data-0.29.9}/src/mostlyright/data_harness/thin/recipe_explain.py

@@ -39,6 +39,7 @@ from mostlyright.data_harness.thin.transport import ThinLaneError
 from mostlyright.data_harness.thin.v4 import (
     EXPLAIN_AND_FORECAST_REQUEST_VERSION,
     StudioV4Client,
+    check_recipe_request_size,
     identifier,
 )
 
@@ -1231,17 +1232,18 @@ def explain_document_at_studio(
     nothing, which is what makes it safe to ask before a registration.
     """
 
+    body = {
+        "schema_version": ROUTES_REQUEST_VERSION,
+        "workspace_id": str(client.session.workspace_id),
+        "document": dict(document),
+    }
+    check_recipe_request_size(body)
     try:
-        # The one inherited `_call` (thin/v4.py): the route rides the same transport, byte
-        # ceiling and refusal translation as every other V4 call.
+        # The one inherited `_call` carries the ordinary response ceiling.
         answer = client._call(
             "POST",
             EXPLAIN_REFRESH_PATH,
-            body={
-                "schema_version": ROUTES_REQUEST_VERSION,
-                "workspace_id": str(client.session.workspace_id),
-                "document": dict(document),
-            },
+            body=body,
             expected=(200,),
         )
     except ThinLaneError as refusal:

{mostlyright_data-0.29.7 → mostlyright_data-0.29.9}/src/mostlyright/data_harness/thin/v4.py

@@ -39,6 +39,7 @@ from collections.abc import Mapping
 from typing import Any
 from uuid import UUID
 
+from mostlyright.data_harness.canonical import canonical_json_bytes
 from mostlyright.data_harness.thin.runs import StudioApiClient
 from mostlyright.data_harness.thin.transport import ThinLaneError
 
@@ -915,6 +916,35 @@ def identifier(value: str, field: str) -> str:
         raise ThinLaneError("THIN_REQUEST_INVALID", f"{value!r} is not a {field}") from error
 
 
+# Studio's API request-body middleware accepts at most 2 MiB. Bound the complete
+# UTF-8 wire envelope, not the recipe's character count or its formatted file size.
+MAX_RECIPE_REQUEST_BYTES = 2 * 1024 * 1024
+# A GET recipe includes the document plus identifiers and registration metadata.
+# Give that envelope 1 MiB headroom; ordinary JSON routes retain their 1 MiB cap.
+MAX_RECIPE_RESPONSE_BYTES = MAX_RECIPE_REQUEST_BYTES + 1024 * 1024
+
+
+def check_recipe_request_size(body: Mapping[str, Any]) -> None:
+    size = len(canonical_json_bytes(body))
+    if size > MAX_RECIPE_REQUEST_BYTES:
+        raise ThinLaneError(
+            "THIN_RECIPE_REQUEST_TOO_LARGE",
+            f"the serialized recipe request is {size} bytes; Studio accepts at most "
+            f"{MAX_RECIPE_REQUEST_BYTES} bytes including its request envelope. "
+            "Reduce the recipe before submitting it",
+        )
+
+
+def recipe_registration_body(document: Mapping[str, Any], workspace_id: str) -> dict[str, Any]:
+    body = {
+        "workspace_id": workspace_id,
+        "document": dict(document),
+        "require_category": True,
+    }
+    check_recipe_request_size(body)
+    return body
+
+
 class StudioV4Client(StudioApiClient):
     """The V4 routes, over the transport and the hardening :class:`StudioApiClient` already has.
 
@@ -993,11 +1023,7 @@ class StudioV4Client(StudioApiClient):
         return self._call(
             "POST",
             CREATE_RECIPE_PATH,
-            body={
-                "workspace_id": str(self.session.workspace_id),
-                "document": dict(document),
-                "require_category": True,
-            },
+            body=recipe_registration_body(document, str(self.session.workspace_id)),
             expected=(201,),
         )
 
@@ -1008,6 +1034,7 @@ class StudioV4Client(StudioApiClient):
             "GET",
             GET_RECIPE_PATH.format(recipe_id=identifier(recipe_id, "recipe identifier")),
             expected=(200,),
+            maximum=MAX_RECIPE_RESPONSE_BYTES,
         )
 
     def recipe_readiness(
@@ -1049,14 +1076,16 @@ class StudioV4Client(StudioApiClient):
     def explain_recipe_refresh(self, document: Mapping[str, Any]) -> dict[str, Any]:
         """Judge one unregistered recipe document for refresh, and read what this Studio serves."""
 
+        body = {
+            "schema_version": EXPLAIN_AND_FORECAST_REQUEST_VERSION,
+            "workspace_id": str(self.session.workspace_id),
+            "document": dict(document),
+        }
+        check_recipe_request_size(body)
         return self._call(
             "POST",
             EXPLAIN_RECIPE_REFRESH_PATH,
-            body={
-                "schema_version": EXPLAIN_AND_FORECAST_REQUEST_VERSION,
-                "workspace_id": str(self.session.workspace_id),
-                "document": dict(document),
-            },
+            body=body,
             expected=(200,),
         )
 

{mostlyright_data-0.29.7 → mostlyright_data-0.29.9}/src/mostlyright/data_harness/thin/v4_query.py

@@ -54,7 +54,6 @@ from mostlyright.data_harness.thin.session import (
 )
 from mostlyright.data_harness.thin.transport import ThinLaneError, UrlLibTransport
 from mostlyright.data_harness.thin.v4 import (
-    GET_RECIPE_PATH,
     GET_RUN_PATH,
     GET_RUN_QUERY_PATH,
     RUN_QUERY_PATH,
@@ -278,7 +277,7 @@ class StudioV4QueryClient(StudioV4Client):
     def recipe_source_ids(self, recipe_id: str) -> list[str]:
         """The sources a recipe registered, which a session opened for its dataset may probe."""
 
-        record = self._call("GET", GET_RECIPE_PATH.format(recipe_id=recipe_id), expected=(200,))
+        record = self.recipe(recipe_id)
         listed = record.get("source_ids")
         sources = (
             [item for item in listed if isinstance(item, str) and item]

{mostlyright_data-0.29.7 → mostlyright_data-0.29.9}/src/mostlyright/data_harness/thin/v4_runs.py

@@ -129,8 +129,10 @@ DISCARD_HISTORY_FLAG = "--discard-snapshot-history"
 #: ⚠ AND ANOTHER ATTEMPT NEEDS A DIFFERENT COORDINATE. Studio derives a run's identity from
 #: ``(recipe_id, recipe_digest, mode, clamps, resource_class)`` and replays a terminal result for
 #: an identical command, so re-issuing the same request returns the same failure without waking a
-#: worker. ``mr-data run --retry RUN_ID`` is what turns that into one command; see
-#: :func:`retry_clamps` for the one coordinate it moves and why moving it changes nothing else.
+#: worker. ``mr-data run --retry RUN_ID`` is what turns that into one command: it names the failed
+#: run as ``retry_of_run_id``, which Studio folds into the identity, and the ceilings go out as
+#: they were. See :func:`retry_clamps` for the coordinate it moves instead when Studio answers
+#: ``RUN_NOT_RETRYABLE`` or a stored run that is already over.
 ROOM_FAULT_CODES: frozenset[str] = frozenset(
     {
         "EXECUTION_LEASE_EXPIRED",
@@ -591,9 +593,12 @@ def declare_run_arguments(parser: argparse.ArgumentParser) -> None:
         "--retry",
         metavar="RUN_ID",
         help="try this failed run again, when what failed was the room rather than the recipe; "
-        "the same recipe, digest, mode and ceilings go out under one byte clamp raised above what "
-        "the document declares, because an identical command replays the stored failure. A run "
-        "that states a byte ceiling of its own has no such coordinate to move and is refused",
+        "the same recipe, digest, mode and ceilings go out naming the failed run, so Studio "
+        "starts a new attempt rather than replaying the stored failure. When Studio does not "
+        "admit that for the run, or answers with a stored run that is already over, the "
+        "command goes out once more under a byte clamp raised above what the document "
+        "declares. A stored run that is queued or running is printed as it is and no second "
+        "run is started",
     )
     parser.add_argument(
         "--approve-full",
@@ -1289,12 +1294,45 @@ def fresh_full_record(run: Mapping[str, Any]) -> bool:
     )
 
 
+#: The refusals of a retry that named the failed run after which the same retry goes out once
+#: more under a moved byte clamp, which is what this command sent before it named the run.
+#: ``RUN_NOT_RETRYABLE`` is Studio declining ``retry_of_run_id`` for this run: its list of
+#: platform failures is its own, and a Studio that has not yet deployed a code this client reads
+#: as a room fault answers with it. The snapshot-history refusal is here because the command it
+#: prints is re-typed without ``retry_of_run_id`` (there is no flag for it), so that command has
+#: to carry a coordinate of its own.
+#:
+#: ``KEEL_ENGINE_REQUIRED`` is here because naming the run can cause it. Studio never hands a
+#: retry of a Python run to Keel (``v4/runs.py``, ``retry_of_python_run``), and then refuses a
+#: recipe the Python engine does not build. The body this command sent before it named the run
+#: carries no ``retry_of_run_id``, so admission chooses the engine again and the run can start.
+#: When the second answer is the same refusal, it is raised as it is.
+_CLAMP_RETRY_CODES: frozenset[str] = frozenset(
+    {"RUN_NOT_RETRYABLE", SNAPSHOT_HISTORY_CODE, "KEEL_ENGINE_REQUIRED"}
+)
+
+#: The states of a run answered to the named retry that mean no new attempt started. Studio's own
+#: automatic resume of a lost progressive full starts its successor with the body the named retry
+#: sends (``apps/api/.../v4/auto_resume.py``: the lost run's clamps and resource class, with
+#: ``resume_capture_run_id`` and ``retry_of_run_id`` both naming it), so once that successor
+#: exists the named retry derives its run id and Studio answers ``201`` with the successor's
+#: stored record. When that record is already over, the retry goes out under the moved byte
+#: clamp, which is a coordinate the successor does not hold.
+#:
+#: ``succeeded`` is a member for the same reason as the other two: a run that is over is not the
+#: attempt this command was asked for. A plain start of the same command is answered with the
+#: failed run's stored record, so without this the table could not be built again from this
+#: command once a successor had succeeded, and 0.29.7 started a run here.
+_STORED_END_STATUSES: frozenset[str] = TERMINAL_RUN_STATUSES
+
+
 def retry_body(
     run: Mapping[str, Any],
     run_id: str,
     *,
     declared_bytes: int = 0,
     fresh_read_control: bool = False,
+    clamp_moved: bool = False,
 ) -> dict[str, Any]:
     """The ``create_run_command`` that is this failed run again, rebuilt off its own record.
 
@@ -1302,6 +1340,12 @@ def retry_body(
     nothing else: the whole point of ``--retry RUN_ID`` is that it does not require somebody to
     have kept the recipe, the digest, the mode and the ceilings the first attempt went out with.
 
+    THE FAILED RUN IS NAMED, AND THE CEILINGS ARE THE ONES IT CARRIED. ``retry_of_run_id`` enters
+    the identity Studio derives, so the command is a new attempt without any ceiling changing
+    (planning#234). ``clamp_moved`` builds the other body instead: no ``retry_of_run_id``, and
+    :func:`retry_clamps` in place of the stated ceilings, for a Studio that answered
+    ``RUN_NOT_RETRYABLE`` to the first.
+
     ⚠ A FRESH FULL IS RETRIED FRESH, AND THE BODY SAYS SO. Studio already keeps a resumed chain
     on the answer lineage its origin was admitted with, so a retry of a fresh full reads fresh
     whatever this body says; stating ``reuse_saved_answers: false`` makes the body, and the rerun
@@ -1319,7 +1363,16 @@ def retry_body(
                 "THIN_RESPONSE_INVALID", f"Studio reported run {run_id} without a {member}"
             )
         body[member] = stated
-    body["clamps"] = retry_clamps(run, declared_bytes=declared_bytes)
+    if clamp_moved:
+        body["clamps"] = retry_clamps(run, declared_bytes=declared_bytes)
+    else:
+        carried = run.get("clamps")
+        clamps = dict(carried) if isinstance(carried, Mapping) else {}
+        if "window" in clamps:
+            clamps["window"] = _command_window(clamps["window"])
+        if clamps:
+            body["clamps"] = clamps
+        body["retry_of_run_id"] = identifier(run_id, "run identifier")
     if body["mode"] == "full":
         body["progressive"] = True
         if run.get("progressive") is True:
@@ -1395,7 +1448,67 @@ def retry(run_id: str, *, client: StudioV4RunClient) -> dict[str, Any]:
             "--mode replay --sources-from RUN_ID once the room is well, or build the recipe "
             "rather than replaying it",
         )
-    # ⚠ THE RECIPE IS READ BEFORE THE RETRY IS BUILT, and that round trip is the price of the
+    # ⚠ THE CAPABILITY IS READ ONLY WHEN IT CAN CHANGE THE BODY. A retry of anything but a fresh
+    # full sends the same body whatever this Studio serves, so asking would be a round trip that
+    # decides nothing.
+    fresh_read_control = False
+    if fresh_full_record(run):
+        table_id = run.get("table_id")
+        if isinstance(table_id, str) and table_id:
+            fresh_read_control = (
+                table_capabilities(client, identifier(table_id, "table identifier")).get(
+                    FRESH_READ_CONTROL
+                )
+                is True
+            )
+    body = retry_body(run, run_id, fresh_read_control=fresh_read_control)
+    try:
+        started = client.create_run(body)
+    except ThinLaneError as refusal:
+        if getattr(refusal, "studio_code", None) in _CLAMP_RETRY_CODES:
+            return _retry_under_a_moved_clamp(
+                run, run_id, client=client, triple=triple, fresh_read_control=fresh_read_control
+            )
+        held = _held_for_confirmation(refusal, body)
+        if held is None:
+            raise
+        # ⚠ SETTLED BY THE HELD RUN'S OWN ID. A re-typed start has no flag for
+        # `retry_of_run_id`, so it would name the failed run's coordinate and Studio would answer
+        # with the stored failure. The refusal names the run Studio held, and `--confirm-held`
+        # confirms that exact record.
+        held["confirm_command"] = confirm_held_command(
+            identifier(str(held["run_id"]), "run identifier")
+        )
+        held["retry_of"] = run_id
+        held["retried_failure"] = triple
+        return held
+    if started.get("status") in _STORED_END_STATUSES:
+        # ⚠ A RUN THAT IS ALREADY OVER IS NOT ANOTHER ATTEMPT. Studio answered the named retry
+        # with a record it had stored under the same identity (see `_STORED_END_STATUSES`), so
+        # printing it as `run_retried` would hand back a stored failure as the retry
+        # (planning#234). The moved clamp is the coordinate 0.29.7 sent, and it starts a run.
+        return _retry_under_a_moved_clamp(
+            run, run_id, client=client, triple=triple, fresh_read_control=fresh_read_control
+        )
+    return _retried(client, started, run_id=run_id, triple=triple, clamp_moved=False)
+
+
+def _retry_under_a_moved_clamp(
+    run: Mapping[str, Any],
+    run_id: str,
+    *,
+    client: StudioV4RunClient,
+    triple: Mapping[str, Any],
+    fresh_read_control: bool,
+) -> dict[str, Any]:
+    """The same retry without ``retry_of_run_id``, under the one ceiling that can move.
+
+    What ``--retry`` sent before it named the failed run, kept for a Studio that answers
+    ``RUN_NOT_RETRYABLE`` or ``KEEL_ENGINE_REQUIRED`` to the named retry, or answers it with a
+    stored run that is already over.
+    """
+
+    # ⚠ THE RECIPE IS READ BEFORE THIS BODY IS BUILT, and that round trip is the price of the
     # clamp being inert. Studio projects from the document's own declared ceilings, so a clamp
     # chosen without reading them is a clamp that might lower what the run projects -- and
     # `projected_bytes` is what the spend and sample-first thresholds are read against.
@@ -1411,24 +1524,12 @@ def retry(run_id: str, *, client: StudioV4RunClient) -> dict[str, Any]:
             "Studio answered without the recipe document this run was started against, so the "
             "bytes it is projected against could not be read and a retry cannot be sized",
         )
-    # ⚠ THE CAPABILITY IS READ ONLY WHEN IT CAN CHANGE THE BODY. A retry of anything but a fresh
-    # full sends the same body whatever this Studio serves, so asking would be a round trip that
-    # decides nothing.
-    fresh_read_control = False
-    if fresh_full_record(run):
-        table_id = run.get("table_id")
-        if isinstance(table_id, str) and table_id:
-            fresh_read_control = (
-                table_capabilities(client, identifier(table_id, "table identifier")).get(
-                    FRESH_READ_CONTROL
-                )
-                is True
-            )
     body = retry_body(
         run,
         run_id,
         declared_bytes=declared_source_bytes(document),
         fresh_read_control=fresh_read_control,
+        clamp_moved=True,
     )
     try:
         started = client.create_run(body)
@@ -1450,10 +1551,25 @@ def retry(run_id: str, *, client: StudioV4RunClient) -> dict[str, Any]:
         held["retry_of"] = run_id
         held["retried_failure"] = triple
         return held
+    return _retried(client, started, run_id=run_id, triple=triple, clamp_moved=True)
+
+
+def _retried(
+    client: StudioV4RunClient,
+    started: Mapping[str, Any],
+    *,
+    run_id: str,
+    triple: Mapping[str, Any],
+    clamp_moved: bool,
+) -> dict[str, Any]:
+    """The receipt of a retry Studio started, with the cell that says why the run exists."""
+
     payload = _started(started, client.session, status="run_retried")
     payload["retry_of"] = run_id
     payload["retried_failure"] = triple
-    payload["note"] = _retry_note(client, started, run_id=run_id, triple=triple)
+    payload["note"] = _retry_note(
+        client, started, run_id=run_id, triple=triple, clamp_moved=clamp_moved
+    )
     return payload
 
 
@@ -1497,6 +1613,7 @@ def _retry_note(
     *,
     run_id: str,
     triple: Mapping[str, Any],
+    clamp_moved: bool = False,
 ) -> dict[str, Any] | None:
     """One cell on the NEW run saying which fault it is another attempt at, or ``None``.
 
@@ -1524,17 +1641,31 @@ def _retry_note(
     except ThinLaneError:
         return None
     try:
-        cell = client.append_cell(fresh, body=_retry_cell(client, fresh, run_id, triple))
+        cell = client.append_cell(
+            fresh, body=_retry_cell(client, fresh, run_id, triple, clamp_moved=clamp_moved)
+        )
     except ThinLaneError as refusal:
         return {"written": False, "refusal": {"code": refusal.code, "detail": refusal.detail}}
     return {"written": True, "cell_id": cell.get("cell_id")}
 
 
 def _retry_cell(
-    client: StudioV4RunClient, fresh: str, run_id: str, triple: Mapping[str, Any]
+    client: StudioV4RunClient,
+    fresh: str,
+    run_id: str,
+    triple: Mapping[str, Any],
+    *,
+    clamp_moved: bool = False,
 ) -> dict[str, Any]:
     """The append command that cell is, composed where its refusals are already being caught."""
 
+    coordinate = (
+        "A byte ceiling above anything the sources can deliver gives the attempt a coordinate "
+        "of its own; an identical command would have replayed the stored failure."
+        if clamp_moved
+        else "The attempt names the failed run and carries the same ceilings; an identical "
+        "command that did not name it would have replayed the stored failure."
+    )
     return run_cell_body(
         workspace_id=client.session.workspace_id,
         run_id=fresh,
@@ -1544,9 +1675,8 @@ def _retry_cell(
             f"Run {run_id} failed at the {triple['failed_stage']} stage with "
             f"{triple['failure_code']}: {triple['failure_detail']}\n\n"
             "That code is about the room the run landed in rather than about this recipe, so the "
-            "document is unchanged. A byte ceiling above anything the sources can deliver gives "
-            "the attempt a coordinate of its own; an identical command would have replayed the "
-            "stored failure. Full retries use progressive acquisition. When the failed full was "
+            f"document is unchanged. {coordinate} "
+            "Full retries use progressive acquisition. When the failed full was "
             "already progressive, the retry also names it as the capture ancestor so Studio can "
             "reuse compatible sealed pages."
         ),