mostlyright-data 0.25.9__tar.gz → 0.26.1__tar.gz

{mostlyright_data-0.25.9 → mostlyright_data-0.26.1}/PKG-INFO

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

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

{mostlyright_data-0.25.9 → mostlyright_data-0.26.1}/skills/mr-data-build/SKILL.md

@@ -43,28 +43,13 @@ references. Load the reference for the current stage only, not the entire librar
    Bind `dataset.id`, describe columns, declare checks and units, and register with
    `mr-data recipe RECIPE.json --json`. Repair all lint findings before queuing work.
    The server returns the recipe digest; do not compute or invent it.
-   Decide each source's refresh continuation before you register it: `closed: true` where the
-   address names a range that has demonstrably ended, a `window` with **both** `request`
-   endpoints where the address carries a date range, a `collection` where the corpus is an index
-   of pages, and nothing where the source is mutable with no changed-since contract. A keyed JSON
-   API (`authenticated.https.api_key@2.0.0` or `@2.1.0`) takes its `window` through declared
-   request parameters, with `location: "parameter"` on both endpoints. Its run walks the window
-   one day or month at a time, so it must state `limits.max_requests`, sized for every unit. A source
-   declaring none of these is `resync_only`, and one `resync_only` source makes the entire table
-   resync-only: it will never refresh on a schedule. Declaring every source is only the first
-   gate; the shape those declarations form is the second, and Studio admits two families only:
-   every source a recorded stream, or at least one `window` with a `request`. Beside a window the
-   plan may hold `closed` siblings, or per-row request collections that carry the window's
-   partition column, but not both. A closed-only plan, any other `collection`, and a `window`
-   beside a recorded stream are each refused, so `closed: true` alone does not make a
-   table refresh. The second family is necessary and not sufficient: as soon as the plan holds
-   more than one source, every window in it must agree on one `merge.materialization`,
-   `merge.partition.column` and `merge.partition.key`, and that column must be a name
-   `table.columns` declares. Adding one `closed` sibling beside a lone window is what turns that
-   requirement on, so a window partitioning on the publisher's own header under a name the table
-   renames refreshes alone and stops the moment a second source joins it. Declare only what the
-   source's own address proves, and name the `resync_only` sources and the reason in the build
-   message.
+   Decide how each source continues before you register it, and whether the table needs a
+   declared `rebuild`: read [making a table incremental](references/making-a-table-incremental.md).
+   Run `mr-data recipe explain RECIPE.json --json` first. It names every reason the table could
+   not refresh, not only the first. Before any `--full` of a paid collection, run
+   `mr-data recipe forecast RECIPE_ID --digest DIGEST --json` and cap `pages.max_fetches_per_run`
+   from it. Declare only what the source's own address proves, and name the `resync_only`
+   sources and the reason in the build message.
 6. Read [build sizing](references/6-build-one-run-sized-to-acquire-every-measured-source-whole.md).
    Use `--full` for the requested build: it is progressive by default, with a five-minute
    inspection checkpoint while the same acquisition continues. Choose bounds from measured
@@ -125,18 +110,13 @@ merely to obtain a green run. Read [recovery details](references/agent-protocol.
    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
    scheduled whole-source fallback. Do not promise freshness without evidence.
-   A recipe that is not refresh-ready is a design fault to repair, not a state to wait out: read
-   `blocking_source_names` and every source's classification in the readiness answer. That list
-   is all-or-nothing: when one source states no continuation Studio cannot derive a plan at all,
-   so it classifies EVERY source `resync_only` and names every one of them, and a twenty-source
-   recipe with one bare address comes back with twenty names rather than the one to repair. Read
-   the document to find which of them actually declares nothing rather than revising nineteen
-   truthful windows. An EMPTY list beside `refresh_ready: false` is the other answer: every source
-   is declared and the plan's SHAPE or its predecessor state is what refuses. Revise against what
-   this run measured, register the revision and resync once. The
-   revision changes the recipe digest, so the sealed predecessor stops matching and one full
-   resync is the price of the repair -- which is why the decision belongs in step 5. A table left
-   not refresh-ready never refreshes; it does not become ready later.
+   A recipe that is not refresh-ready is a design fault to repair, not a state to wait out. Run
+   `mr-data recipe explain RECIPE_ID --json`: each finding names its rule code, its sources and
+   Studio's suggested repair, and [making a table incremental](references/making-a-table-incremental.md#which-plans-refresh)
+   says what each code means. Revise against what this run measured, register the revision and
+   resync once. The revision changes the recipe digest, so one full resync is the price of the
+   repair, which is why the decision belongs in step 5. A table left not refresh-ready never
+   refreshes unless it declares `rebuild`; it does not become ready later.
    Download and verify artifacts when the user requested bytes.
 10. Report rows and coverage actually verified, checks, limitations and the stable dataset link.
     Read [delivery](references/9-present-only-what-survived-inspection-with-caveats.md) for details.
@@ -153,10 +133,23 @@ merely to obtain a green run. Read [recovery details](references/agent-protocol.
 | Source credentials | [Credentials](references/source-credentials.md) |
 | 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) |
 | Refresh cadence | [Promotion and cadence](references/promote.md) |
 | Dataset notes and evidence blocks | [Decision records](references/writing-a-decision-record.md) |
 | Exact schemas and worked recipes | [Reference index](references/reference-pages.md) |
 
+## Needs Studio 4.14
+
+Check first: run `mr-data recipe explain RECIPE.json --json` and read `studio_capabilities`. Use
+this only when `snapshot_refresh` is true; otherwise a snapshot table keeps the one day its last
+full read, and that is what to tell the user. With it true, a snapshot table keeps a daily history,
+and its size is decided when you register it. **The history ceiling is fixed at registration, and
+raising it discards the history.** Set `window.snapshot.max_partitions` to the number of days to
+keep, and `limits.max_source_bytes` to bytes per day × those days with headroom, up to 4 GiB.
+Measure bytes per day from the first full, and re-register before the first refresh if the horizon
+is short. [Needs Studio 4.14](references/making-a-table-incremental.md#needs-studio-414) has the
+arithmetic, the guards, and the other features this check gates.
+
 ## Communication and boundaries
 
 Keep routine operations quiet except where the host requires progress updates. Explain material

{mostlyright_data-0.25.9 → mostlyright_data-0.26.1}/skills/mr-data-build/references/5-draft-one-recipe-document-one-call.md

@@ -304,126 +304,14 @@ drawn with its endpoint alone, and a reader is left to guess from a query string
 
 ### Say how each source refreshes
 
-Studio reads one refresh strategy per source out of this document, and a source that states none
-is `resync_only`. One `resync_only` source makes the whole table resync-only: it never refreshes
-on a schedule, however truthful its siblings are.
-
-| what the source declares | classification | next action |
-| --- | --- | --- |
-| `source_class: "stream"` | `recorded` | `recorded` |
-| `closed: true` | `closed` | `reuse_predecessor` |
-| a `collection` | `collection` | `acquire_incremental` |
-| a `window` carrying a `request` | `window` | `acquire_incremental` |
-| none of those | `resync_only` | `resync_required` |
-
-The rows are in Studio's own precedence order -- stream, then `closed`, then `collection`, then
-`window` -- because a source may declare more than one of those members and the first match wins.
-A source carrying both `closed: true` and a request window is `closed`, and its window is never
-read. A recorded stream that also says `closed: true` is `recorded`, not `closed`.
-
-`closed: true` says the range at this address is over and a refresh may reuse the bytes the
-predecessor sealed rather than ask again. Use it for a range that has demonstrably ended, and
-understand what you are accepting: if the publisher later restates that period, the table keeps
-serving the old bytes, no run fails, and only an explicit resync repairs it. Never mark the
-current period closed -- that drops new data outright, which is a different and worse mistake.
-
-A `window` is the better answer wherever the address carries time, because it re-requests its
-recent range on every refresh and so picks up corrections inside `lookback_seconds` on its own.
-It needs `start_at`, `granularity`, `timezone`, `lookback_seconds`, `max_span_seconds` and
-`merge`, and a `request` naming BOTH ends -- an address that names only one side of a range
-cannot be narrowed. Each grammar below is closed; a spelling outside it belongs to a later
-version and is refused.
-
-- `request.start` and `request.end` take `encoding`: `date_parts` (names three parameters and
-  takes `pad`), `iso_date` or `epoch_seconds` (each names one parameter and takes no `pad`).
-- Each endpoint's `location` is `query` (the default) or `path` for an address. A keyed JSON API
-  (`authenticated.https.api_key@2.0.0` or `@2.1.0`) states `parameter` on both. Each name is then
-  a required declaration in `generic_api.request.parameters` that the request interpolates. Its
-  run walks the window one day or month at a time, and the source states `limits.max_requests`.
-  *A date window* in
-  [the recipe document](https://mostlyright.md/docs/reference/recipe/) has the rules.
-- `bound` is `inclusive` or `exclusive`. The engine's own window is half-open
-  `[start_inclusive, end_exclusive)` in UTC; start/inclusive and end/exclusive pass both instants
-  through unchanged, and the other two spellings shift by a day. **Probe the publisher rather
-  than assuming**: both spellings validate against the schema, and only the start is checked at
-  registration, so a wrong `end` silently fetches a different range than the address states.
-- `merge.materialization` is `partition_replace` only.
-- `merge.partition.column` names a column of the ACQUIRED relation -- the header the publisher
-  sent, not the name your statement gives it. **That holds only while the window is the recipe's
-  one source.** In a plan of more than one source the column must ALSO be a name `table.columns`
-  declares, so a renamed field is refused at admission and has to take the one-source route. If
-  this recipe has, or will have, a second source of any kind -- a `closed` sibling is enough --
-  partition on a name the table itself declares.
-- `merge.partition.key` is `iso_date_prefix` (first ten characters of an ISO value),
-  `iso_date_value` (a complete ISO date), `compact_utc_hour` (a real `YYYYMMDDHH`) or
-  `iso_month_prefix` (the first seven characters, a calendar month). A month key needs `start_at`
-  on the first of a month and `max_span_seconds` of at least 7,948,800.
-- `merge.row_identity` names the columns the merged relation must be unique on.
-
-`start_at` is a UTC midnight, and the start parameters already written in the address must render
-exactly that instant. If the address says `year1=2026&month1=5&day1=31`, `start_at` is
-`2026-05-31T00:00:00Z`. A keyed JSON API's start values frozen in `connector.parameters` must
-render it the same way.
-
-Declaring nothing is the honest answer for a mutable address with no changed-since contract, and
-pagination is not one. Say which sources you left `resync_only` and why, because a recipe that
-never asked the question and one that asked and answered `resync_only` register identically.
-
-**Declaring every source is the FIRST gate, and the SHAPE of the plan is the second.** Once Studio
-has one action per source it asks whether a worker can materialize the plan those actions make,
-and admits two families only: every source a recorded stream, which appends sealed batches, or at
-least one `window` carrying a `request`, with `closed` siblings permitted beside it, which replaces
-the bounded partitions the window asked for. A closed-only plan refreshes nothing -- it restores
-the predecessor's bytes and leaves no partition to replace. Any `collection` in the plan refuses
-the whole table, alone or beside a window, with one exception. A per-row request collection over
-a `window` of the plan refreshes with it when it names the window's `merge.partition.column` in
-`request.carry_columns` and no `closed` source is in the plan. A `window` beside a recorded stream
-refuses the whole table too. Each
-of those is `RESYNC_REQUIRED` before acquisition: the table registers, builds and serves, and only
-an explicit resync ever moves it again. So `closed: true` alone does NOT make a table refresh, and
-marking every source closed to clear the first warning buys a table that is just as dead and warns
-about nothing.
-
-**The second family is NECESSARY and not sufficient, and the count is of sources.** A plan holding
-more than one source -- one `window` and one `closed` sibling is already two -- is materialized by
-the several-source lane, which writes ONE table manifest. Every window in such a plan must
-therefore agree with the others on `merge.materialization`, `merge.partition.column` and
-`merge.partition.key`, and each partition column must be a name `table.columns` declares.
-Disagreeing windows, and a partition column the table does not declare, are both
-`RESYNC_REQUIRED`. So adding a `closed` sibling beside a lone window is not free: it is what turns
-the declared-column requirement on.
-
-**The THIRD gate is the SHAPE OF THE DOCUMENT, and a run is what checks it.** A recipe with
-exactly one source carrying a `request` window builds on a bounded route of its own, and that
-route holds the document to six further rules: the partition column inside `merge.row_identity`,
-`merge.row_identity` equal to `table.grain` in order, at least one identity column besides the
-partition column, a rename-free one-statement projection with no `where` and no function,
-`key_uniqueness` as the only check kind, and rows the publisher already served in order. Three of
-the six refuse the run. The other three fail silently: they drop every later refresh onto the
-complete-history fallback, which rebuilds the whole table and is what the window was declared to
-avoid. Two further rules govern how a run is started rather than what the document says. Register,
-build with a `full` run, and only then refresh, because a refresh reads its recipe off the latest
-SUCCEEDED run rather than the newest registered revision. A refresh started by hand states its own
-`--window START END`, or it is refused `RUN_WINDOW_REQUIRED`. [The recipe
-document](https://mostlyright.md/docs/reference/recipe/) writes all eight out under *What the
-bounded lane needs, beyond a usable window*, and says which fail which way. Fetch that section
-before the first build, because none of it is visible at registration.
-
-**Decide it from MEASUREMENT, not from the ceiling you typed.** `limits.max_source_bytes` is a
-bound written before anything was fetched, and it is wrong in both directions: one live publisher
-came in an order of magnitude under the ceiling declared for it, and another came in over. The
-run's own coverage is the other thing entirely. Build once, read the coverage, and correct the
-declarations against it before you record a cadence. A revision changes the recipe digest and
-costs one full resync, so the cheapest time to be right is here.
-
-**Where that coverage is depends on the route the build took.** An ordinary build seals a
-`receipt`, and `mr-data receipt RUN --json` carries one entry per source with `bytes_fetched`,
-`rows_kept`, `rows_available` and `truncated`. A build on the one-windowed-source bounded route
-seals no receipt at all, and `mr-data receipt` answers `THIN_NO_MATCHING_ARTIFACT` naming what it
-sealed instead. Read `mr-data status RUN --json` for that one: its `coverage` block carries `rows`,
-`bytes`, `window` and `truncated`. That block is Studio's fold over every source, so it is one
-source's own delivery only on a one-source recipe, which this route always is. Only
-`rows_available` is missing, and `truncated` still says whether a ceiling cut the source short.
+Studio reads one continuation per source out of this document, and a source that states none is
+`resync_only`. One `resync_only` source makes the whole table resync-only: it never refreshes on a
+schedule, however truthful its siblings are. Choose each source's continuation, and decide
+whether the table declares `rebuild`, with
+[making a table incremental](making-a-table-incremental.md). It has the decision tree, the
+request window grammar, the plan shapes Studio refreshes, and what each continuation costs. Run
+`mr-data recipe explain RECIPE.json --json` on the draft before you register it: it names every
+reason the table could not refresh at once, with Studio's suggested repair for each.
 
 ### Say what each column is, and what it shows
 

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

@@ -187,21 +187,16 @@ held answer prints back as `confirm_command`. Any authenticated surface of the p
 settle it. `mr-data run --cancel RUN_ID` stops a run that is queued or running.
 
 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.
-Normal refresh materializes an all-recorded-stream recipe, or a plan holding at least one direct
-`window.request` source with a compatible partitioned predecessor, `closed` reuse permitted beside
-it. Beside it is not free: as soon as the plan holds more than one source, every window in it must
-agree on one `merge.materialization`, `merge.partition.column` and `merge.partition.key`, and that
-column must be a name the table declares. A per-row request collection that reads a window of
-the plan and carries its partition column may join it when no `closed` source does. The
-classifier may name closed reuse or collection continuation. Closed-only plans, any plan carrying
-another collection, and a window beside a recorded stream still return `RESYNC_REQUIRED` before
-acquisition. Their bounded table materializers do not exist yet. A `window.snapshot` or unwindowed mutable source is likewise
-resync-only. Explicit resync is full,
-has no predecessor, and a collection starts from the beginning. Never hide one behind conditional
-revalidation, generic pagination, or a whole-source comparison. Research publisher cursors,
-revision identities, listings, corrections, and deletions, but use only deployed recipe grammar
-that represents the proven strategy. For each incremental source, record the affected key or
-partition and a fixture proving
-that applying its delta to the predecessor produces the same rows as a full build over
-predecessor-plus-delta. A `backfill` may be refused before acquisition; the refusal says so.
+classify every source under one truthful continuation strategy and record the supporting evidence,
+using [making a table incremental](making-a-table-incremental.md).
+`mr-data recipe explain RECIPE_ID --json` says which plan shapes this Studio refreshes and why a
+table does not. Explicit
+resync is full, has no predecessor, and a collection starts from the beginning. Never hide one
+behind conditional revalidation, generic pagination, or a whole-source comparison. Research
+publisher cursors, revision identities, listings, corrections, and deletions, but use only
+deployed recipe grammar that represents the proven strategy. For each incremental source, record
+the affected key or partition and a fixture proving that applying its delta to the predecessor
+produces the same rows as a full build over predecessor-plus-delta. Before a `--full` of a paid
+collection, run `mr-data recipe forecast RECIPE_ID --digest DIGEST --json` and cap
+`pages.max_fetches_per_run` from it. A `backfill` may be refused before acquisition; the refusal
+says so.

{mostlyright_data-0.25.9 → mostlyright_data-0.26.1}/skills/mr-data-build/references/commands.md

@@ -12,11 +12,11 @@ gap rather than doing anything, and `export-hosted-candidate`, which is a backen
 | `mr-data probe` | `probe SOURCE_ID QUESTION_ID --dataset DATASET_ID [--kind source_inspect\|sample_rows\|profile_columns\|evaluate_expression]` asks one already-registered source one question and prints the answer. **Do not plan a source inspection around it.** Both positionals are identifiers — `QUESTION_ID` is a question identifier, which no v4 registration receipt returns — and the command rides the frozen `/v3/sessions` routes, which a deployment may have switched off. Read a source instead by registering the recipe and taking one unwindowed run under `--max-rows`, then `peek`, `query` and `receipt`. |
 | `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 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`; `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; 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` | 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 strict source-action plan. Although the classifier may name closed reuse, a request-window or collection delta, or recorded input, current normal refresh materializes only a plan carrying at least one direct `partition_replace` request window with a compatible predecessor — `closed` siblings may reuse their sealed bytes beside it, a lone window needs a retained source-history record, and several must agree on materialization and partition layout — or an all-recorded-stream plan. A per-row request collection that reads a window of the plan and carries its partition column may join it when no `closed` source does. Closed-only, any plan carrying another collection, a window beside a recorded stream, snapshot and unwindowed plans return `RESYNC_REQUIRED` before acquisition. 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 spend confirmation, 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 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. |
-| `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. `--status` and `--mode` narrow it and are refused `THIN_ARGUMENT_INVALID` for a word outside the seven states or the six modes; `--limit` says how many, and pages are followed to reach it. A narrow filter over a workspace of thousands of runs reads a long way to find its matches, and a listing that does not end says how many were read and suggests a smaller `--limit`. |
+| `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 spend confirmation, 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 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. `--status` and `--mode` narrow it and are refused `THIN_ARGUMENT_INVALID` for a word outside the seven states or the six modes; `--limit` says how many, and pages are followed to reach it. A narrow filter over a workspace of thousands of runs reads a long way to find its matches, and a listing that does not end says how many were read and suggests a smaller `--limit`. 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 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. |
@@ -32,8 +32,8 @@ gap rather than doing anything, and `export-hosted-candidate`, which is a backen
 | `mr-data stream` | Record a public `wss://` venue so a build can read it. `stream document register --file F` admits the connector document, `stream registry create --digest D` admits a set of them, `stream probe` listens briefly and seals nothing, `stream capture --seconds N` records a bounded window, and `stream subscribe` keeps recording. `stream subscription {show|pause|resume|stop} ID` retains the legacy full-record interface. `stream subscription quiescence ID` reads the bounded server-computed proof; `pause-cas` and `resume-cas` read its ETag and make one conditional bounded write. An ambiguous CAS failure is not retried until a fresh invocation observes the resource again. `stream status ID` reads a capture or probe, and `stream recordings --document-digest D` names what a build could read and until when. `--seconds` is at most 600. `mr-data run` takes no duration: a build reads sealed batches and is bounded by them. |
 | `mr-data open` | Mint a single-use, short-lived address that continues this session in a browser at one dashboard path, and print it. `--open` hands it to the platform opener. The credential decides who mints: a device credential — what `mr-data login` stores — mints at Cloud, and a personal access token mints at Studio. |
 | `mr-data promote` | Record the cadence one table refreshes on and the reasoning behind it. A table's first succeeded run goes live on its own, so this is not what makes it readable; it is idempotent on a table that is already live, and it is how a withdrawn table is put back. The Harness worker does not perform the catch-up or scheduled refresh; report those only when another deployed component returns durable evidence that it did. |
-| `mr-data reschedule` | Change how often one live table refreshes, without the demote and promote that would reset its bookkeeping and buy a catch-up run. `--cadence` takes a cron expression or an interval such as `every 6h`; `--why` records the reasoning. It starts no run. `--lock` freezes the schedule so Studio stops adjusting it; `--unlock` lets it follow the source again. |
-| `mr-data table` | Report what one table is serving and how its refresh schedule is going: the state in plain words, the schedule in force, the next refresh, the schedule that was asked for and the reason given for it, and — once Studio has settled on one — the interval it measured and how many source updates that rests on. `table rename TABLE --name NAME` writes a new name, lowercase snake_case and unique within its dataset, fenced on that dataset's version and retried once if somebody else wrote first; nothing is rebuilt, because every run, version and schedule hangs off the identifier, which does not move. `table archive TABLE --confirm-name NAME` retires one table you name by the name it is called, and frees that name; a live table is refused until you `demote` it, and nothing built is deleted. `table archive TABLE [TABLE ...] --confirm DELETE` retires as many tables as you name at once: `DELETE` is the literal word, typed exactly, and it confirms the identifiers you typed rather than a name, so each table is retired under the name Studio is holding for it. Every table is attempted whatever the one before it answered, one line is printed for each, and the command exits non-zero if any was not retired — so read the outcome of each rather than the exit code alone. `--confirm-name` is refused when you name more than one table. |
+| `mr-data reschedule` | Change how often one live table refreshes, without the demote and promote that would reset its bookkeeping and buy a catch-up run. `--cadence` takes a cron expression or an interval such as `every 6h`; `--why` records the reasoning. It starts no run. `--lock` freezes the schedule so Studio stops adjusting it; `--unlock` lets it follow the source again. A table that cannot refresh answers `table_schedule_held` and exits 2, naming the two repairs: declare `rebuild`, or `table resync`. |
+| `mr-data table` | Report what one table is serving and how its refresh schedule is going: the state in plain words, the schedule in force, the next refresh, the schedule that was asked for and the reason given for it, and — once Studio has settled on one — the interval it measured and how many source updates that rests on. Where Studio reports it, it also prints the table's refresh strategy: "rebuilds every 7d; next T" or "held: blocker". `table rename TABLE --name NAME` writes a new name, lowercase snake_case and unique within its dataset, fenced on that dataset's version and retried once if somebody else wrote first; nothing is rebuilt, because every run, version and schedule hangs off the identifier, which does not move. `table archive TABLE --confirm-name NAME` retires one table you name by the name it is called, and frees that name; a live table is refused until you `demote` it, and nothing built is deleted. `table archive TABLE [TABLE ...] --confirm DELETE` retires as many tables as you name at once: `DELETE` is the literal word, typed exactly, and it confirms the identifiers you typed rather than a name, so each table is retired under the name Studio is holding for it. Every table is attempted whatever the one before it answered, one line is printed for each, and the command exits non-zero if any was not retired — so read the outcome of each rather than the exit code alone. `--confirm-name` is refused when you name more than one table. |
 | `mr-data pin` | Ask Studio to freeze one table pointer on an exact version, for a rollback or a hold. |
 | `mr-data unpin` | Ask Studio to resume pointer tracking; read the returned state before claiming it resumed. |
 | `mr-data demote` | Ask Studio to withdraw the pointer and any schedule it owns, for one table or for as many as you name: `demote TABLE [TABLE ...]` withdraws them one after another, attempts every one of them whatever the one before it answered, prints a line for each, and exits non-zero if any is still live. Pair it with `table archive` when you are retiring a set: a live table cannot be archived, so it is withdraw-then-archive, two commands rather than a loop. |
@@ -51,23 +51,18 @@ verify its final receipt.
 
 ### Strict refresh controls
 
-`mr-data recipe readiness` pages Studio's immutable-revision inventory and reports predecessor,
-incremental-materialization, and differential-proof readiness, every source's classified next
-action, and blocking source names. It reads persisted facts; it does not authorize a schedule.
+Which continuation each source declares, and which plan shapes Studio refreshes, is
+[making a table incremental](making-a-table-incremental.md). Its loop is four commands:
+`mr-data recipe explain`, `mr-data recipe forecast`, `mr-data run` and
+`mr-data status RUN_ID --diagnose`. `mr-data recipe readiness` pages Studio's immutable-revision
+inventory: every source's classified next action, the blocking source names, and, where Studio
+reports them, a `blocker_code` and whether a `rebuild` is declared. It reads persisted facts; it
+does not authorize a schedule.
 
-A refresh executes only Studio's persisted source-action plan. The classifier may name closed
-reuse, a request window or collection delta, or recorded input, but current normal refresh
-materializes only a plan carrying at least one direct `partition_replace` request window with a
-compatible predecessor, or an all-recorded-stream plan. `closed` siblings may reuse their sealed
-bytes beside a window; a lone window needs a retained source-history record, and several windows
-must agree on materialization and partition layout. A per-row request collection that reads a
-window of the plan and carries its partition column may join it when no `closed` source does.
-Closed-only, any plan carrying another collection, a window beside a recorded stream, snapshot and
-unwindowed plans return `RESYNC_REQUIRED` before acquisition.
-`mr-data table resync TABLE --request-id UUID` is the explicit
-full reread; retain and reuse the caller-generated UUID after a lost response. A held resync receipt
-prints `mr-data run --confirm-held RUN_ID` for that exact run. New full resyncs are progressive;
-an existing legacy sample-first resync still uses `--approve-full` after its preview succeeds.
+`mr-data table resync TABLE --request-id UUID` is the explicit full reread; retain and reuse the
+caller-generated UUID after a lost response. A held resync receipt prints
+`mr-data run --confirm-held RUN_ID` for that exact run. New full resyncs are progressive; an
+existing legacy sample-first resync still uses `--approve-full` after its preview succeeds.
 
 **`--refresh` states its own range, and a run that starts one by hand must pass it.** `mr-data run
 --refresh` sends what it is given. A refresh of a recipe carrying a non-snapshot request window