mostlyright-data 0.29.11__tar.gz → 0.30.0__tar.gz

{mostlyright_data-0.29.11 → mostlyright_data-0.30.0}/PKG-INFO

@@ -1,13 +1,16 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.29.11
+Version: 0.30.0
 Summary: Mostly Right hosted CLI for reviewed datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/
 Requires-Python: >=3.11
 Provides-Extra: build
+Requires-Dist: hatch-vcs==0.5.0; extra == 'build'
 Requires-Dist: hatchling==1.28.0; extra == 'build'
+Requires-Dist: setuptools-scm==10.3.4; extra == 'build'
 Requires-Dist: uv-build==0.11.3; extra == 'build'
+Requires-Dist: vcs-versioning==2.6.0; extra == 'build'
 Description-Content-Type: text/markdown
 
 # mostlyright-data
@@ -39,6 +42,10 @@ places it in your agent's skill directory; there is nothing to install by hand.
 edited yourself is never replaced, and `MOSTLYRIGHT_SKILL_AUTOINSTALL=0` switches the placement
 off.
 
+Once a day, after a command has printed its answer, `mr-data` asks the Python package index whether
+a newer release is published and says so in one line on stderr. `MOSTLYRIGHT_RELEASE_CHECK=0`
+switches that off.
+
 ## Sign in
 
 ```bash

{mostlyright_data-0.29.11 → mostlyright_data-0.30.0}/README.md

@@ -27,6 +27,10 @@ places it in your agent's skill directory; there is nothing to install by hand.
 edited yourself is never replaced, and `MOSTLYRIGHT_SKILL_AUTOINSTALL=0` switches the placement
 off.
 
+Once a day, after a command has printed its answer, `mr-data` asks the Python package index whether
+a newer release is published and says so in one line on stderr. `MOSTLYRIGHT_RELEASE_CHECK=0`
+switches that off.
+
 ## Sign in
 
 ```bash

{mostlyright_data-0.29.11 → mostlyright_data-0.30.0}/pyproject.toml

@@ -1,6 +1,8 @@
 [project]
 name = "mostlyright-data"
-version = "0.29.11"
+# The release tag is the version. `hatch-vcs` reads it from git at build time, so a release is a
+# `v*` tag push and no file states the number. See docs/RELEASING.md.
+dynamic = ["version"]
 description = "Mostly Right hosted CLI for reviewed datasets"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -17,8 +19,11 @@ mr-data = "mostlyright.data_harness.thin.router:main"
 
 [project.optional-dependencies]
 build = [
+    "hatch-vcs==0.5.0",
     "hatchling==1.28.0",
+    "setuptools-scm==10.3.4",
     "uv-build==0.11.3",
+    "vcs-versioning==2.6.0",
 ]
 
 [dependency-groups]
@@ -38,9 +43,34 @@ dev = [
 pypi-release = ["twine==6.2.0"]
 
 [build-system]
-requires = ["hatchling==1.28.0"]
+requires = [
+    "hatch-vcs==0.5.0",
+    "hatchling==1.28.0",
+    "setuptools-scm==10.3.4",
+    "vcs-versioning==2.6.0",
+]
 build-backend = "hatchling.build"
 
+# `uv sync` rebuilds the editable install when the commit or the tags change, so the installed
+# version follows a new release tag.
+[tool.uv]
+cache-keys = [{ file = "pyproject.toml" }, { git = { commit = true, tags = true } }]
+
+[tool.hatch.version]
+source = "vcs"
+
+# Only `v<digits>` tags are releases. A commit after the last one builds as that release's
+# version, as a checkout between releases always has: `mr-data propose` records the version as
+# plain X.Y.Z and refuses anything else. A tree without git history builds as 0.0.0.
+[tool.hatch.version.raw-options]
+tag_regex = "^v(?P<version>[0-9]+(?:\\.[0-9]+)*(?:(?:a|b|rc)[0-9]+)?)$"
+version_scheme = "only-version"
+local_scheme = "no-local-version"
+fallback_version = "0.0.0"
+
+[tool.hatch.version.raw-options.scm.git]
+describe_command = ["git", "describe", "--dirty", "--tags", "--long", "--match", "v[0-9]*"]
+
 [tool.hatch.build.targets.wheel]
 sources = ["src"]
 only-include = [

{mostlyright_data-0.29.11 → mostlyright_data-0.30.0}/skills/mr-data-build/SKILL.md

@@ -34,17 +34,18 @@ only a ceiling. Keep a stated one only when a run's refusal told you to lower it
 documents a limit on concurrent connections, and record the reason in a dataset note so the next
 session finds it. Then choose the source shape that fits.
 
-| Source shape | Use | Always state |
-| --- | --- | --- |
-| One public file that never changes | `public.https` with a Reader pin | `closed: true` |
-| One large public Parquet file whose publisher answers byte ranges | a `parquet.tabular@1.1.0` pin | `columns` |
-| Keyed JSON API paged by page number, whose first page states the page count | `authenticated.https.api_key@2.1.0` with the counted `pagination.parallel` | `total_pages_pointer`, `max_page_bytes`, the gap |
-| API that takes a date range | `window.request` | `lookback_seconds` |
-| Many pages behind one index | `public.https.collection@2.0.0` | the gap |
-| One request per row of another source | a per-row `request`, with `batch` when a `GET` takes a list of ids | the gap |
-| Bulk dump beside a windowed source | `reference` | `recheck_seconds` |
-| Live `wss://` feed | a recorded stream | see [Streams](references/recording-a-stream-venue.md) |
+| Source shape | Use | Always state | Recipe |
+| --- | --- | --- | --- |
+| One public file that never changes | `public.https` with a Reader pin | `closed: true` | [one file](references/patterns.md#one-public-file-that-never-changes) |
+| One large public Parquet file whose publisher answers byte ranges | a `parquet.tabular@1.1.0` pin | `columns` | [ranged Parquet](references/patterns.md#one-large-public-parquet-file-read-by-range) |
+| Keyed JSON API paged by page number, whose first page states the page count | `authenticated.https.api_key@2.1.0` with the counted `pagination.parallel` | `total_pages_pointer`, `max_page_bytes`, the gap | [keyed API](references/patterns.md#keyed-json-api-with-pages-fetched-together) |
+| API that takes a date range | `window.request` | `lookback_seconds` | [date range](references/patterns.md#api-that-takes-a-date-range) |
+| Many pages behind one index | `public.https.collection@2.0.0` | the gap | [collection](references/patterns.md#many-pages-behind-one-index) |
+| One request per row of another source | a per-row `request`, with `batch` when a `GET` takes a list of ids | the gap | [per-row](references/patterns.md#one-request-per-row-many-ids-per-request) |
+| Bulk dump beside a windowed source | `reference` | `recheck_seconds` | [reference](references/patterns.md#bulk-dump-beside-a-windowed-source) |
+| Live `wss://` feed | a recorded stream | see [Streams](references/recording-a-stream-venue.md) | none |
 
+[Patterns](references/patterns.md) has one complete recipe per row, with the pace set.
 [Sources](references/sources.md#pace-and-width) has the pace rules and the limits of parallel
 pages. [Readers](references/readers.md) has the Reader pins and the limits of a ranged read.
 
@@ -88,7 +89,10 @@ step 6. The stage 3 reference holds its rule. Gate 4 is step 6.
 3. Settle purpose, row grain, tables, coverage, required sources and update cadence before
    dependent work. In an attended build, ask unresolved material questions in one concise message
    with recommended choices; recording an assumption is not asking the user. Default to one joined,
-   ML-ready table at the agreed grain unless the user requests otherwise. Validate join cardinality
+   ML-ready table at the agreed grain unless the user requests otherwise. Define membership and
+   relationship evidence for the intended use; resolve consequential proxies (for example,
+   institution location versus a person’s origin) rather than silently treating them as equivalent.
+   Validate join cardinality
    and point-in-time correctness; surface incompatible grains rather than silently multiplying rows.
    Ask whether this is a fixed snapshot or an updating dataset, how often updates are needed, and
    whether automatic cadence adjustment is wanted. Existing answers and explicit delegation remain
@@ -189,8 +193,10 @@ merely to obtain a green run. Read [recovery details](references/agent-protocol.
 
 8. Read `mr-data checks RUN_ID --json`, `mr-data receipt RUN_ID --json` and
    `mr-data peek RUN_ID --json`; use bounded `mr-data query` for agreed quality questions.
-   Verify row grain, joins, requested fields, coverage and every declared check. Successful
-   execution alone is not a verified dataset. `receipt` carries one coverage entry per source --
+   Verify row grain, joins, requested fields, coverage and every declared check. Inspect representative
+   and suspicious rows against source evidence and the agreed definitions; schema and count checks
+   alone cannot establish that the rows mean what the dataset claims. Successful execution alone
+   is not a verified dataset. `receipt` carries one coverage entry per source --
    `bytes_fetched`, `rows_kept`, `rows_available`, `truncated` and the window -- where the run
    record folds all sources into four numbers. That is what each source ACTUALLY weighed and
    carried, and it is the evidence the refresh decision belongs on rather than the ceiling you
@@ -201,7 +207,8 @@ merely to obtain a green run. Read [recovery details](references/agent-protocol.
    correction into step 10. Read
    [verification](references/7-interrogate-ask-the-run-what-it-actually-delivered.md).
 9. Any truncated source means a preview, not the requested complete dataset. Inspect coverage
-   even when the run succeeded. A null coverage window does not mean all history was acquired.
+   even when the run succeeded. Untruncated acquisition does not prove publisher pagination, nested
+   records or population coverage is complete. A null coverage window does not mean all history was acquired.
    Repair only evidenced faults on the same dataset/table and verify the revision again.
    Record cadence only when authorized and `mr-data recipe readiness --json` reports the current
    revision refresh-ready. A blocked mutable snapshot requires an explicit table resync, not a
@@ -234,6 +241,7 @@ merely to obtain a green run. Read [recovery details](references/agent-protocol.
 | Live stream recording | [Streams](references/recording-a-stream-venue.md) |
 | Prediction target or leakage | [Prediction labels](references/prediction-labels.md) |
 | How each source continues, `rebuild`, and the cost of a refresh | [Making a table incremental](references/making-a-table-incremental.md) |
+| Testing a recipe before its full, and its first refresh before the schedule | [Recipe test](references/recipe-test.md) |
 | Refresh cadence | [Promotion and cadence](references/promote.md) |
 | Dataset notes and evidence blocks | [Decision records](references/writing-a-decision-record.md) |
 | Search configuration, example queries and readiness | [Search preparation](references/preparing-table-search.md) |

{mostlyright_data-0.29.11 → mostlyright_data-0.30.0}/skills/mr-data-build/references/2-brief-two-to-four-questions-each-with-a-recommended-answer.md

@@ -17,7 +17,9 @@ user already supplied. Always include update behavior when it remains unresolved
   separate tables as an equal default. Check join keys, cardinality, unmatched rows and, for
   prediction, feature availability at prediction time. If a join would mix incompatible grains,
   duplicate examples or leak future information, explain the tradeoff and resolve it before building.
-- **Coverage.** Which entities, geography and date range?
+- **Coverage.** Which entities, geography and date range? Resolve definitions that materially change
+  membership here: a person’s institutional country, origin and current residence are different
+  populations. Ask about the intended population, not which convenient API filter to use.
 - **Updates.** A fixed historical snapshot or an updating dataset? If updating, how often is new
   data needed, and should that schedule stay fixed or adapt to source publication? Recommend a
   cadence from the use case and available source evidence, mark an unverified recommendation as
@@ -27,10 +29,23 @@ user already supplied. Always include update behavior when it remains unresolved
   the agent recommend them? Ask about the consequential fork — official but delayed against broader
   and more recent, or a source that needs a credential — and research the options yourself.
 
-Fields and definitions, quality tradeoffs and delivery constraints are follow-ups, not openers:
+Other field details, quality tradeoffs and delivery constraints are follow-ups:
 ask one when an answer or a source finding exposes it. There is no second brief — this message is
 the one that decides the shape.
 
+**Turn the brief into criteria the result can be checked against.** Record what one row claims,
+what qualifies an entity or relationship, and how repeated observations or versions count. Use the
+existing decision notes and recipe checks; this does not introduce a new approval or schema.
+Resolve only consequential ambiguity and honor supplied answers. For a human collaboration table,
+a software agent credited on a release is not evidence of collaboration with that agent’s vendor;
+the user need not specify this exclusion. Whether software contributions count at all depends on
+their purpose. A release-history dataset can legitimately retain every version.
+
+Use a few included and excluded examples when they help expose a boundary. Carry unresolved
+source limitations into the source comparison rather than redefining the goal around available
+fields. Do not infer a person’s origin from their name or silently replace it with institutional
+country. If the intended population cannot be evidenced, explain the gap and resolve the scope.
+
 **Every question is a pending `clarification` block on the dataset and the same words in chat.**
 The block carries `question` and no `answer`, so the page shows it open; the chat asks it in the
 same words, so the two readers see one question rather than two. The answer REVISES that cell —

{mostlyright_data-0.29.11 → mostlyright_data-0.30.0}/skills/mr-data-build/references/6-build-one-run-sized-to-acquire-every-measured-source-whole.md

@@ -213,6 +213,18 @@ held answer prints back as `confirm_command`. Any authenticated surface of the s
 may settle it. Never present it to the user as a cost or a payment. `mr-data run --cancel RUN_ID`
 stops a run that is queued or running.
 
+**A full tests its recipe first.** `mr-data run --full` runs `mr-data recipe test` with Studio's
+default bounds, waits up to five minutes for its report, and then starts the full resuming from
+the test's pages, so nothing is fetched twice. A blocking problem, a failed or held test, or a test
+still running after five minutes keeps the full from starting: the status is
+`run_stopped_by_test`, `run_test_awaiting_confirmation` or `run_test_still_running`, `run_id` names
+the test, and `next` ends with the same full plus `--skip-test`. Repair the recipe rather than
+skipping the test, unless the user decides the problem does not matter; a test still running is
+picked back up by the same command. A test that failed in the room (`room_fault: true`) is tested
+again by the same command. Studio admits the test as the full it stands in front of, so a large
+full can be held for a size confirmation twice, once for the test and once for the full. See
+[recipe test](recipe-test.md).
+
 Do not treat the accepted command vocabulary as execution evidence. Before proposing a schedule,
 classify every source under one truthful continuation strategy and record the supporting evidence,
 using [making a table incremental](making-a-table-incremental.md).

{mostlyright_data-0.29.11 → mostlyright_data-0.30.0}/skills/mr-data-build/references/7-interrogate-ask-the-run-what-it-actually-delivered.md

@@ -9,6 +9,35 @@ mr-data checks RUN --json                     # every check the recipe declared
 mr-data receipt RUN --json                    # sources, digests, coverage, snapshot members
 ```
 
+#### Check meaning against the brief
+
+Inspect actual rows beyond the first preview: sample across material source/entity/type groups
+and inspect anomalies such as unusually prolific pairs, repeated titles or concentrated counts.
+Trace selected inclusions and suspected exclusions to source records. Record the version, sample
+selection, rows inspected, evidence and unresolved limitations in the dataset notes. A sample is
+not proof of population-wide accuracy; passing declared checks only proves their assertions.
+
+Choose checks from the dataset’s claims. For a human co-authorship table, inspect counterpart
+identity and affiliation evidence, distinct people rather than self-edges, work types, and repeated
+release families. A bot credit does not establish a human relationship with its vendor. Use
+source-supported identities or narrowly justified matches; a name substring is not a reliable bot
+classifier. Preserve legitimate human names. Treat software releases and version deduplication
+according to the agreed grain: do not ban software or collapse versions in a release-history task.
+Encode evidenced, repeatable failures as supported recipe checks where possible, then verify the
+repair. Do not relax checks or prune legitimate rows to make them pass.
+
+Separate acquisition limits from source and population coverage. Read publisher totals and
+continuation tokens, nested-list caps or completeness flags, and join losses where applicable.
+`coverage.truncated: false` does not prove all publisher pages or all authors inside each record
+were returned. Missing completeness evidence means unknown. A nested cap calls for another
+supported acquisition path or a stated limitation, not silent exclusion of every large record.
+
+Known examples can reveal omissions, but compare their eligibility against the same population,
+dates and relationship definition first. A broader benchmark is useful for discussing scope; its
+size is not a valid recall denominator for a narrower dataset. Investigate eligible misses and
+preserve out-of-scope examples as such. Do not manufacture a recall or accuracy percentage from
+an unvalidated list or an anomaly-focused sample.
+
 **The last of those answers `THIN_NO_MATCHING_ARTIFACT` on a run that sealed no receipt**, naming
 what it sealed instead. That is the ordinary shape of a recipe with one `request`-windowed source
 rather than a fault. Read `mr-data status RUN --json` for its coverage, as
@@ -57,7 +86,7 @@ instead, and wait through the window the refusal names rather than retrying in a
 
 **A query sent straight after another may find no worker to start.** The worker behind the query
 before is still winding down, and Studio fails the new session at once with
-`RESEARCH_SESSION_WORKER_UNAVAILABLE`. `mr-data query` waits 8 seconds and opens one more session,
+`RESEARCH_SESSION_WORKER_UNAVAILABLE`. `mr-data query` waits 8 to 12 seconds and opens one more session,
 once. The answer then names the first session under `session.retried_after`. If the second has no
 worker either, the command refuses `THIN_RESEARCH_SESSION_ENDED` and names both sessions, each with
 its state, close reason and failure code. Nothing was queued, so running the same command again

{mostlyright_data-0.29.11 → mostlyright_data-0.30.0}/skills/mr-data-build/references/9-present-only-what-survived-inspection-with-caveats.md

@@ -1,23 +1,25 @@
 ### 9. Present — only what survived inspection, with caveats
 
 Report what you inspected, and nothing you did not. Nothing else checks this run: `verified` is
-what you established by reading it, not a word another worker said. Three facts carry whatever
-you say and all three are on the run: how many rows you looked at, what the declared checks
-reported, and whether `coverage.truncated` was true anywhere. A null coverage window means the
-acquisition was unwindowed rather than that it covered all time. Never present a sampled row as a
+what you established by reading it, not a word another worker said. Report how many rows you
+inspected and how you selected them, what the declared checks reported, and whether `coverage.truncated` was true anywhere. Include the source evidence and
+limitations behind membership, relationships and population coverage. A null coverage window means
+the acquisition was unwindowed rather than that it covered all time. Never present a sampled row as a
 whole-population value, never call a run verified because it succeeded, and never report coverage
-you did not read off `coverage`.
+you did not establish from the run and source evidence.
 
 **Read `truncated` first, because it decides which of two endings this is.** When it is false on
-every coverage entry, nothing was cut and the table this run sealed is the table a full run would
-have sealed. When it is true anywhere, what you have is a shape rather than an answer.
+every coverage entry, the acquisition reports no transport truncation. This alone does not
+establish publisher pagination, nested-list completeness or coverage of the intended population.
+When it is true anywhere, what you have is a shape rather than an answer.
 
 **The real table's full run, untruncated everywhere, is the build. Present it as one.** A
 scratch-table test is never the build, whatever its coverage says. Calling a complete table "a
 preview" tells somebody their dataset does not exist yet when it does. Say what was built, and link the page:
 
-> Built 43,812 rows from four sources, every source acquired whole and nothing truncated. All four
-> declared checks passed. Live at <link>. It refreshes every 6 hours, because the publisher posts
+> Built 43,812 rows from four sources with no reported acquisition truncation. All four declared
+> checks passed. Inspected 40 rows across the four sources; publisher totals match acquired records.
+> Live at <link>. It refreshes every 6 hours, because the publisher posts
 > hourly and the bytes appear about forty minutes late.
 
 Say plainly that it is live: the first succeeded run of a table goes live on its own, so there is
@@ -48,12 +50,15 @@ preview, and release it with `mr-data run --approve-full`. `failed` is the full
 triple and structured recovery. A known retry case can use `mr-data run --retry RUN_ID`; otherwise
 preserve the document until the evidence identifies a repair. A bare run of the same coordinate
 replays that failure. `cancelled` means they withdrew the decision, so say so and ask nothing
-further unless they raise it. Ask, then give the turn back; do not hold a stream open waiting for
+further unless they raise it. The exception is a run whose `cancel_reason` is
+`preflight_complete`, or that carries `preflight`: that is a recipe test, which always ends
+`cancelled` with its report and never becomes a version. It is not the full build and not a
+withdrawn decision; read its `preflight_report` as [recipe test](recipe-test.md) describes. Ask, then give the turn back; do not hold a stream open waiting for
 either answer.
 
-Then interrogate that run as stage 7 says, and present it with the preview's caveats removed and
-its own read off `coverage`. Do not start a full build because the preview looked good or because a
-dataset was asked for — the decision is whether THIS is the recipe to build.
+Then interrogate that run as stage 7 says. Remove only the preview caveats the new evidence
+resolves, and retain unresolved source limitations. Do not start a full build because the preview
+looked good or because a dataset was asked for — the decision is whether THIS is the recipe to build.
 
 **Either way, offer the bytes.** A sealed table is downloadable whatever mode produced it —
 `mr-data download RUN --output DIR --json` — so somebody who wants to look before agreeing to

{mostlyright_data-0.29.11 → mostlyright_data-0.30.0}/skills/mr-data-build/references/commands.md

@@ -3,6 +3,12 @@
 These thirty-eight are the whole surface, alongside `acquire-slices`, which names a capability
 gap rather than doing anything, and `export-hosted-candidate`, which is a backend operator step.
 
+Every command that takes a run identifier also takes its first eight or more characters,
+`recipe propose --sources-from` included. The prefix is matched against the workspace's newest
+1,000 runs before the command checks anything else, so it needs a signed-in session. A prefix that
+matches two runs is refused naming both, and one that matches none is refused, so name an older
+run in full.
+
 | Command | What it does |
 | --- | --- |
 | `mr-data auth` | Validate the effective device credential with Cloud; manage metadata-only device revocation, remote-first logout, safe rotation, and explicit recovery; explain the ephemeral token boundary. |
@@ -15,21 +21,22 @@ gap rather than doing anything, and `export-hosted-candidate`, which is a backen
 | `mr-data catalog` | `catalog search "QUESTION"` asks the sealed public-source catalogue which of its entries might answer a question and ranks them best first. Every ranked entry comes back with the disposition its own facts earned — `admitted`, `human_escalation_required` or `refused` — because an entry the catalogue could not vouch for is still a finding. `--format csv` states the one data format the question requires — one token per question, never repeated — and it is not a filter: an entry that does not declare that format still comes back ranked, with disposition `refused` and `filters_match` false, so nothing is held back; `--limit N` ranks at most N, up to 25. It fetches nothing and registers nothing. The catalogue holds one provider (Data.gov) and only part of it, so it is never exhaustive and an empty answer is not evidence that no such source exists. When the answer is `catalog_unavailable`, this deployment has no catalogue to search: record the lane and carry on. |
 | `mr-data public` | Read Mostly Right's public dataset catalogue. `public search "QUERY"` ranks published datasets (`--topic`, `--limit` and `--cursor` narrow and page it), `show SLUG` reads one overview, `tables SLUG` lists its table identifiers, `schema TABLE_ID` reads one table's schema, `sample TABLE_ID` prints its published preview rows, `lookup "QUERY"` is the connector search shape and `fetch SLUG` returns the dataset's Markdown document. Those seven need no login. `query TABLE_ID`, with `--body` or `--body-file`, and `download-url TABLE_ID` do need `mr-data login`: they ask Cloud, with the device key, to run one query over a public table and to say how it can be downloaded. Preview rows are not a query, and no table bytes pass through the command. |
 | `mr-data connected` | `connected list` shows the public datasets connected to this workspace and `connected add SLUG` connects one by its slug. It needs `mr-data login`: both ask Cloud, with the device key, over the routes MCP's `list_connected_datasets` and `connect_dataset` use. |
+| `mr-data ask` | `ask "QUESTION" [--run RUN_ID ...] [--failure-code CODE]` asks the Mostly Right support agent one question and waits for the answer; `--no-wait` prints the question id at once and `ask status QUESTION_ID` reads it later. It needs `mr-data login` and a workspace the agent is switched on for: while it is off the answer is `THIN_CLOUD_SUPPORT_AGENT_DISABLED`, which is final. The agent may file a problem for the Mostly Right team and prints its reference (`SR-N`). |
 | `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. The explanation's `fast_features` names each fast feature the recipe uses or misses, with a one-line fix. [Making a table incremental](making-a-table-incremental.md#the-loop-explain-forecast-run-diagnose) says when to use each. |
+| `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. A recipe that misses a feature that sets how fast a run fetches (an unstated pace, a stated `pages.concurrency`, a per-row request open to `batch`, a page walk open to `pagination.parallel`, or a Parquet file open to a ranged read) is refused `THIN_RECIPE_SLOW`, with each feature's pointer and fix, before anything is sent. Apply the fixes, or pass `--accept-slow "REASON"` with one sentence on why the slow path is right for this source. The receipt prints the reason and the features it covered. 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` 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. `--digest` is optional there, and without it the digest the recipe was registered with is forecast. `mr-data recipe readiness --table TABLE_ID --current-only` reads the revision one table runs now. The explanation's `fast_features` names each fast feature the recipe uses or misses, with a one-line fix. [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 are required, neither is 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. `--max-rows` cuts rows after a source is fetched and decoded, so it does not shorten a collection walk. A sample with no clamp is refused: `CLAMPS_REQUIRED` from Studio, and `THIN_REQUEST_INVALID` from this client first. A table's first succeeded run goes live, truncated or not, so test on a scratch table as [the probe rule](3-probe-read-a-source-before-committing-to-it.md#the-probe-rule-test-on-a-scratch-table-never-on-the-real-table) says. 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 run` | Start one run against a registered recipe, named as `--recipe RECIPE_ID`, with `--digest RECIPE_DIGEST` when you want the run to assert which bytes it means. Neither is positional. The digest is the bare hex the registration receipt printed. Left out, the run reads it back from the registered recipe, which is the same value, because a recipe identifier names one revision. A full of a recipe that misses a fetch-speed feature is refused `THIN_RECIPE_SLOW`, as registration is, unless `--accept-slow "REASON"` is passed. Other modes print the missed features and are not refused. 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. `--max-rows` cuts rows after a source is fetched and decoded, so it does not shorten a collection walk. A sample with no clamp is refused: `CLAMPS_REQUIRED` from Studio, and `THIN_REQUEST_INVALID` from this client first. A table's first succeeded run goes live, truncated or not, so test on a scratch table as [the probe rule](3-probe-read-a-source-before-committing-to-it.md#the-probe-rule-test-on-a-scratch-table-never-on-the-real-table) says. 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 and the next step Studio's recovery category names when it is not. `room_fault` is Studio's `recovery.room_fault` where Studio states one. A source that kept refusing (`SOURCE_RATE_LIMITED`, `SOURCE_HTTP_5XX`, `SOURCE_PROXY_BUSY`) is sent anyway: Studio admits it 120 seconds after the failure and refuses `RUN_RETRY_TOO_SOON` with a Retry-After before then, so wait that long and run `--retry` again. `--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. |
-| `mr-data query` | Run one bounded read-only SQL statement over a finished run's own table and print the rows. Bounded on rows, on answer bytes and on time, and refused by name when a bound is crossed. |
-| `mr-data search` | `search VERB` prepares and tests versioned search for a new table through Studio; no model or index runs on this computer. The verbs are `inspect`, `sample`, `values`, `propose`, `configure`, `validate`, `add-cases`, `explain`, `preview`, `evaluate`, `estimate`, `build`, `status`, `activate`, `cancel` and `rollback`. `inspect`, `propose` and `validate` also take `--recipe FILE` before registration. A build returns promptly with job coordinates, and an operation Studio does not serve answers a typed capability error. [Prepare search](preparing-table-search.md) says how it fits a build. |
+| `mr-data query` | Run one bounded read-only SQL statement over a finished run's own table and print the rows. Name the table `run_table` in the SQL, whatever the recipe called it. Bounded on rows, on answer bytes and on time, and refused by name when a bound is crossed. When no worker can answer, the refusal names `mr-data download RUN_ID` as `fallback_command`, which brings the table here to read locally. The question is asked through Mostly Right Cloud; while its usage paywall is on and the workspace is unsubscribed, each answered query counts toward the person's monthly allowance, and a spent allowance refuses `THIN_USAGE_LIMIT`. A refusal after the question was queued names its `query_id`; running the same command again reads that query back. |
+| `mr-data search` | `search VERB` prepares and tests versioned search for a new table through Studio; no model or index runs on this computer. The verbs are `inspect`, `sample`, `values`, `propose`, `configure`, `validate`, `add-cases`, `explain`, `preview`, `evaluate`, `estimate`, `build`, `status`, `activate`, `cancel`, `rollback`, `locate` and `try`. `inspect`, `propose` and `validate` also take `--recipe FILE` before registration. `validate --spec` checks a spec and its evaluation cases against the pinned contract without sending anything. `locate` resolves evaluation-case rows to locators, and `try` runs one query against the live search. A build returns promptly with job coordinates, and an operation Studio does not serve answers a typed capability error. [Prepare search](preparing-table-search.md) says how it fits a build. |
 | `mr-data peek` | Print the columns, their logical types and the first rows of one run's table. The type comes off the run's own column profile where the preview carries none, so `type` is null only for a run that sealed no profile. |
 | `mr-data receipt` | Print what one run recorded about how it was built: every source it fetched and what those bytes hashed to, the coverage it delivered, and the members of its raw snapshot. |
 | `mr-data checks` | Report how each check the recipe declared came out — the name, whether it passed, what it found. Exits non-zero when one did not pass. |
 | `mr-data note` | Write one cell of a run's decision record — a heading, a body, and the typed blocks that carry a source, a decision or a clarification onto the stage its phase names. The body comes from `--markdown-file FILE`, which is the form to use; standard input is read when no file is named and is refused when it is a terminal or empty. `--list` reads back what is written. |
 | `mr-data artifacts` | `artifacts list RUN_ID` lists what one run sealed — each artifact's identifier, kind, size and digest — without fetching a byte, which is the same answer MCP's `run_artifacts` gives. `mr-data download` brings the bytes. |
-| `mr-data download` | Bring one run's artifacts back to this computer, each one's bytes checked against the digest Studio sealed them under. `--kind` selects out of `table_parquet`, `table_manifest`, `table_part`, `column_profile`, `preview`, `receipt` and `raw_snapshot`; without it, the shape the run sealed — one file and the receipt for a table written whole, or the manifest, EVERY part the version names and the receipt for a table made of parts, written as `table/manifest.json` beside `table/parts/<part_key>.parquet`. A version composed over several refreshes names parts earlier runs sealed; those are fetched too, and a part that cannot be fetched refuses by name rather than leaving a folder holding part of a table. A run that sealed no receipt brings back what it did seal, without one. |
+| `mr-data download` | Bring one run's artifacts back to this computer, each one's bytes checked against the digest Studio sealed them under. `--kind` selects out of `table_parquet`, `table_manifest`, `table_part`, `column_profile`, `preview`, `receipt` and `raw_snapshot`; without it, the shape the run sealed — one file and the receipt for a table written whole, or the manifest, EVERY part the version names and the receipt for a table made of parts, written as `table/manifest.json` beside `table/parts/<part_key>.parquet`. A version composed over several refreshes names parts earlier runs sealed; those are fetched too, and a part that cannot be fetched refuses by name rather than leaving a folder holding part of a table. A run that sealed no receipt brings back what it did seal, without one. Every read is minted through Mostly Right Cloud. While Cloud's usage paywall is on and the workspace is unsubscribed, the table rows read (parts, table parquet) count toward the person's monthly allowance and a manifest or table counts one query; receipts, previews and profiles are free, and files already in the folder with the right digest are not read again. Re-running after a spent allowance does not count those files again, except that when a part sealed by an earlier run is still missing, each page of part reads fetched to reach it counts the rows of every part on it, including parts already on disk. A spent allowance refuses `THIN_USAGE_LIMIT`, naming the upgrade address and when the allowance resets. When the rows left cover only some parts, those parts are written and verified and the download ends as a partial one: `THIN_USAGE_LIMIT` with `download_partial: true`, `parts_written` of `part_count` and `rows_written` of `row_count`. The table in the folder is then NOT whole; do not read it as the dataset. Re-running the same command into the same folder after the reset or a subscription continues from the first part not written. `THIN_DATA_EGRESS_THROUGH_CLOUD` either says to upgrade mr-data (it asked Studio directly), says Cloud does not serve the metered download route yet, or says the fault is on Mostly Right's side; in the last two cases retry later, and neither upgrading nor a new device key changes anything. |
 | `mr-data verify` | Hold one run's sealed table manifest against the parts it names, and report every disagreement. Without `--deep` it fetches the manifest alone; with `--deep` it fetches every part the run sealed and re-hashes it against the digest the manifest states. Exits non-zero when anything disagrees. |
 | `mr-data parts` | List one table version's parts — the identifier, the row count, the byte size and the recorded bounds of each — so a training loader can shard them across workers and read a table no single file should hold. `--version` names a version rather than the live one, and `--from`/`--to` keep only the parts a value range cannot rule out. Nothing is downloaded by listing them; the pattern is under [Reading a table that is made of parts](7-interrogate-ask-the-run-what-it-actually-delivered.md#reading-a-table-that-is-made-of-parts). |
 | `mr-data diff` | Compare two runs and say what changed. |
@@ -102,12 +109,12 @@ block carries `rows`, `bytes`, `window` and `truncated`, and on a one-source rec
 source's own delivery.
 
 `auth`, `login`, `whoami` and `clarify` are the same implementation in both profiles, and
-`clarify` alone reaches nothing at all. The other thirty-four are hosted, and they answer from
-Studio apart from `public` and `connected`, which answer from Cloud. Fifteen only read: `status`,
+`clarify` alone reaches nothing at all. The other thirty-five are hosted, and they answer from
+Studio apart from `public`, `connected` and `ask`, which answer from Cloud. Fifteen only read: `status`,
 `runs`, `watch`, `peek`, `receipt`, `checks`, `download`, `artifacts`, `verify`, `parts`, `diff`,
 `connections`, `catalog`, `public` and `reader`.
-Nineteen start or change something: `dataset`, `recipe`, `cover`, `run`, `query`, `probe`,
-`source`, `search`, `keys`, `stream`, `open`, `connected`, `note`, `promote`, `reschedule`,
+Twenty start or change something: `dataset`, `recipe`, `cover`, `run`, `query`, `probe`,
+`source`, `search`, `keys`, `stream`, `open`, `connected`, `ask`, `note`, `promote`, `reschedule`,
 `table`, `pin`, `unpin` and `demote`. The split is over names, not over invocations: `table TABLE`
 reads and `table rename` writes, and the name sits on the side of whichever half changes
 something.

{mostlyright_data-0.29.11 → mostlyright_data-0.30.0}/skills/mr-data-build/references/live-run.md

@@ -84,6 +84,7 @@ executing; `status` is.
 **A failed run always carries the same three members** — `failure_code`, `failure_detail` and
 `failed_stage` — on three surfaces: the run record, the terminal event on the stream, and every
 refusal a command raises about it. `mr-data status` and `mr-data runs` add a fourth reading beside
-them, `room_fault`, which is this client saying whether that code names the execution room rather
-than the document. `true` identifies a known retry case; `false` only means this classifier did
+them, `room_fault`, which says whether the failure is the execution room's rather than the
+document's. It is Studio's own reading (`recovery.room_fault`, which also sees the worker's
+`failure_cause`) where Studio states one, and this client's reading of the code otherwise. `true` identifies a known retry case; `false` only means this classifier did
 not identify one. Read structured recovery and causal evidence before changing the recipe.