mostlyright-data 0.31.6__tar.gz → 0.31.8__tar.gz

{mostlyright_data-0.31.6 → mostlyright_data-0.31.8}/PKG-INFO

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

{mostlyright_data-0.31.6 → mostlyright_data-0.31.8}/skills/mr-data-build/SKILL.md

@@ -14,6 +14,15 @@ offer the small models (classify, extract, match) for the judgement no rule can
 wait for the person to name a model. Steps 3, 4, 5, 8 and 10 say where, and
 [enriching with small models](references/enriching-with-small-models.md) says how.
 
+## Set the goal as a checklist
+
+At the start of every build, write the goal as a checklist with the host's todo or plan tool:
+TodoWrite in Claude Code, todowrite in opencode, or the plan tool where the host has one. List
+each deliverable the brief names. Then list every delivery step: the description in the skill's
+shape, the cover, search on the main table, the table view review, the refresh cadence and the
+enrichment offer. Keep the list current as you work. Each item ends done, or skipped on purpose
+with the reason written beside it. Do not report the build as done while an item is open.
+
 ## Four gates
 
 Every build passes these four gates in order. Do not skip one. The numbered steps below carry
@@ -196,9 +205,11 @@ step 6. The stage 3 reference holds its rule. Gate 4 is step 6.
 
 ## Work in parallel
 
-When the host can run subagents or background commands, give independent work to them at the
-same time instead of doing it one item after another. The lead agent keeps the brief, every
-decision, every write and every word to the user.
+When the host can run subagents, use them. The discovery lanes in step 4 and the probes of the
+shortlisted sources must fan out: one subagent per lane and one per source, all started at the
+same time. Run them one after another only when there is one lane or one source. Give other
+independent work to subagents or background commands the same way. The lead agent keeps the
+brief, every decision, every write and every word to the user.
 
 - **What fans out.** The discovery lanes in step 4, one subagent per lane. Probing the sources
   on the shortlist, one subagent per source, each with `mr-data source inspect`. Bounded gate-3
@@ -270,6 +281,21 @@ merely to obtain a green run. Read [recovery details](references/agent-protocol.
    Then run `mr-data models suggest RUN_ID --json`. It reads the run's preview and names where
    the table could use a deterministic derivation or a model call, and whether this deployment
    serves that model. Confirm each lead against the rows before you offer it.
+   A succeeded full run's `mr-data status` and `mr-data watch` output carries a `delivery` block.
+   It names a missing cover, a description that is missing or out of the skill's shape,
+   natural-language search when the run's table has none, a view review when the table has no
+   saved view, a refresh cadence when none is recorded, and always the enrichment offer.
+   Complete every step before you report the build as done. Studio marks no main table, so you
+   judge it: skip the search and view steps for a supporting table and say so in one line. A
+   scratch table you test and demote owes none of these steps.
+   Review the view with `mr-data table view TABLE_ID --json`. It lists the view kinds this
+   deployment offers and the roles each one binds. Choose from the columns and a bounded sample,
+   check the choice with `--set VIEW.json --dry-run`, then save it. The plain table is fine when
+   it reads best, but save it as a deliberate choice.
+   Record the cadence under step 9's readiness rule. A fixed snapshot has no cadence to record:
+   write that decision as a dataset note and skip the step, saying so in one line.
+   Offering enrichment is mandatory. Accepting it is the person's choice, and a no is a complete
+   answer.
 9. Any truncated source means a preview, not the requested complete dataset. Inspect coverage
    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.
@@ -285,7 +311,8 @@ merely to obtain a green run. Read [recovery details](references/agent-protocol.
    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. For new tables with search intent, inspect search readiness and test meaningful queries against
+10. Search is on by default for the dataset's main table. Supporting tables such as lookups and
+    code lists do not need it. Enable it, inspect search readiness and test meaningful queries against
     the observed version as [search preparation](references/preparing-table-search.md) describes.
     Search preparation runs independently: pending or failed indexing never means the data build
     failed, and declared metadata alone never proves observed search quality. Before delivery,

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

@@ -300,6 +300,8 @@ uses must follow from the actual fields and coverage, without promising an outco
   no bold field labels, em dashes,
   semicolons, fake quotations or unsupported claims
 - every `##` heading in DESCRIPTION.md is one of the five, in that relative order, none repeated
+- Coverage and Columns are present. A succeeded full run's `delivery` block checks the opening,
+  the headings and the 4000-character bound, and names the description until it passes
 
 **Every dataset gets a cover before its first run is presented.** Once the description is written,
 generate one with `mr-data cover DATASET_ID "what the image should depict" --json`, describing the

{mostlyright_data-0.31.6 → mostlyright_data-0.31.8}/skills/mr-data-build/references/commands.md

@@ -26,9 +26,9 @@ run in full.
 | `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 (a stated `pages.concurrency` under 64, 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`, 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` resumes a failed or cancelled progressive full from the pages it saved (`resume_capture_run_id` and the ceilings it carried; `retry_of_run_id` as well only when Studio admits a named retry). A failure that says the recipe must change is refused before anything is posted. Any other failed run is tried 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 is refused 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 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. A succeeded full run carries `delivery`: the steps still owed before the build is done (a description missing or out of the skill's shape, a missing cover, natural-language search when the dataset's main table has none, a view review when the table has no saved view, a refresh cadence when none is recorded, and always the enrichment offer), each with its command. A read that fails adds a note, never a step. It never changes the exit code. |
 | `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 watch RUN_ID RUN_ID ...` follows up to 16 runs at once, prints one line as each ends, and returns once all have finished with one receipt per run (`failed_run_ids`, `refused_run_ids`); it exits 2 when any run failed and 1 when a run could not be watched. `--from-seq` and `--last-event-id` resume one run only. |
+| `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 watch RUN_ID RUN_ID ...` follows up to 16 runs at once, prints one line as each ends, and returns once all have finished with one receipt per run (`failed_run_ids`, `refused_run_ids`); it exits 2 when any run failed and 1 when a run could not be watched. `--from-seq` and `--last-event-id` resume one run only. A full run that succeeds carries the same `delivery` block as `mr-data status`, and the multi-run receipt merges every run's steps. |
 | `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. |
@@ -47,7 +47,7 @@ run in full.
 | `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. 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 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. `table view TABLE` says whether a live table has a saved view (`view_saved`) and lists the view kinds (`table`, `cards`, `places`, `products`, `events`, `jobs`, `people`, `articles`) and the roles each binds. There is no map or chart kind, and `places` are location cards. `table view TABLE --set VIEW.json` saves `{"version": 1, "template": KIND, "fields": {ROLE: COLUMN}}`, with optional `facts` (up to 4 columns) and `imageStyle`. `--dry-run` has Cloud validate it against the live table and save nothing. The file is checked here before anything is sent. Replacing a saved view needs its revision as `--expected-revision`, which MCP `get_table` reports, because Cloud serves no CLI read of it. A stale revision is refused `THIN_TABLE_VIEW_VIEW_CHANGED`. The command uses the device key. |
 | `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. |

{mostlyright_data-0.31.6 → mostlyright_data-0.31.8}/skills/mr-data-build/references/enriching-with-small-models.md

@@ -88,7 +88,11 @@ also keep the rows it settled from being sent at all: see [Needs Studio 4.14](#n
 5. **After the run (step 8).** Run `mr-data models suggest RUN_ID --json`. It reads the run's
    preview and names, column by column, a deterministic derivation or a model call that would
    improve the table, each with `model_status` for the model it needs. It spends no call. Read
-   it as leads: confirm each against the rows before offering it.
+   it as leads: confirm each against the rows before offering it. The run's `delivery` block on
+   `mr-data status` and `mr-data watch` lists this offer as required, beside a missing
+   description, cover or main-table search. Search is its own required step, not part of this
+   offer. Make the offer before you report the build as done. Offering is
+   mandatory. Accepting is the person's choice. If nothing is worth adding, say so in one line.
 6. **Deliver (step 10).** End the report with what would make the table better: the remaining
    offers, deterministic ones first, each with the column it reads and what it would add. One
    concrete sentence each, not a menu of everything possible.

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

@@ -57,6 +57,13 @@ missing search support only when `error` begins with
 `THIN_SEARCH_CAPABILITY_UNAVAILABLE` as a capability limit too. Any other refusal is not
 capability evidence. That includes 401, 403, 429, timeouts and invalid responses. Resolve it.
 
+Search is on by default for the dataset's main table, whether or not the brief mentions it.
+Supporting tables such as lookups, code lists and dimension tables do not need it. A succeeded
+full run's `delivery` block names the search step whenever the run's table has no search, a
+search whose build failed included. Studio marks no main table, so you judge which one it is.
+Skip the step for a supporting table, while the capability is missing, or when the table has
+nothing searchable, and say why in one line.
+
 When the brief does not mention search, search is optional only while the capability is missing.
 Then omit `table.search`, keep the drafted intent beside the recipe, and record the limit in the
 dataset's Sources and decisions note. Never put that limit in the description, title or topics.

{mostlyright_data-0.31.6 → mostlyright_data-0.31.8}/skills/mr-data-build/references/promote.md

@@ -55,6 +55,13 @@ simply omitting the cadence command. Do not promise that ongoing work is disable
 state proving it, and do not demote or archive a requested readable dataset as a workaround. If the
 available controls cannot preserve the requested snapshot and refresh behavior, report that gap.
 
+**A fixed snapshot is a recorded decision, not a missing cadence.** Studio has no cadence that
+means never. Leave the table unscheduled, confirm `mr-data table TABLE_ID` shows no schedule,
+and record the decision and its reason with
+`mr-data dataset note DATASET_ID --heading "Fixed snapshot: no refresh" --markdown-file NOTE.md`.
+Then skip the delivery block's cadence step, saying so in one line. The step stays listed, and
+the note is the record.
+
 This call records a schedule; it is not proof of data continuation. Schedule only a current recipe
 that `mr-data recipe readiness --table TABLE_ID --current-only --json` reports as refresh-ready, or
 one that declares `rebuild`. [Making a table incremental](making-a-table-incremental.md) says

mostlyright_data-0.31.8/src/mostlyright/data_harness/thin/delivery.py

@@ -0,0 +1,457 @@
+"""The steps a succeeded full run still owes before the build is reported as done.
+
+A full run that succeeded has data on the page. The page is not finished until it has a real
+description and a cover, the main table has search and a deliberately chosen view, the table's
+refresh cadence is recorded, and the person has been offered enrichment. This module names what
+is missing, reading the dataset, the table's search, the table and its saved view once each, and
+always names the enrichment offer. It never raises: a read that fails adds a note, never a step.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from mostlyright.data_harness.thin import description_shape
+from mostlyright.data_harness.thin.session import StudioSession
+from mostlyright.data_harness.thin.transport import ThinLaneError, Transport
+from mostlyright.data_harness.thin.v4 import GET_TABLE_PATH, identifier
+from mostlyright.data_harness.thin.v4_datasets import StudioV4DatasetClient
+
+DELIVERY_VERSION = 1
+
+#: Where the description's shape is written down.
+SKILL_REFERENCE = "the build skill's references/5-draft-one-recipe-document-one-call.md"
+
+#: What each conformance failure tells the person to fix.
+_FAILURE_SAYS: dict[str, str] = {
+    "too_long": "it is over 4000 characters",
+    "missing_bold_opening": "it does not open with a bold first sentence",
+    "unknown_heading": "a ## heading is not one of the five",
+    "repeated_heading": "a ## heading is repeated",
+    "out_of_order_heading": "the ## headings are out of order",
+    "missing_coverage": "it has no ## Coverage section",
+    "missing_columns": "it has no ## Columns section",
+}
+
+#: The step names, in the order a person does them.
+STEPS: tuple[str, ...] = (
+    "description",
+    "cover",
+    "search",
+    "table_view",
+    "cadence",
+    "enrichment_offer",
+)
+
+_ENRICHMENT_WHY = (
+    "Offering enrichment is required on every full build. Confirm each lead against the rows, "
+    "then offer the worthwhile classification or extraction in one question. If nothing is worth "
+    "adding, say so in one line. A no is a complete answer."
+)
+
+_SEARCH_WHY = (
+    "Enable natural-language search on the dataset's main table: the one people query "
+    "directly. It is on by default, not an offer. Follow the skill's search flow in "
+    "references/preparing-table-search.md: search inspect, propose, validate, configure, build, "
+    "activate. Skip it, saying why in one line, when this is a supporting table (a lookup, a "
+    "code list, a dimension), when search inspect shows this deployment does not serve search "
+    "authoring, or when the table has nothing searchable."
+)
+
+_VIEW_WHY = (
+    "Review how its rows read best and save that view. mr-data table view lists the view kinds "
+    "this deployment offers and the roles each one binds. Inspect the columns and a bounded "
+    "sample with mr-data peek, check the view with --set VIEW.json --dry-run, then save it. The "
+    "plain table is a valid choice when it reads best, but save it as a deliberate choice. Skip "
+    "it, saying why in one line, for a supporting table."
+)
+
+_SNAPSHOT = (
+    "Studio has no cadence that means never. When the agreed answer is a fixed snapshot, leave "
+    "the table unscheduled, record that decision with mr-data dataset note {dataset_id} "
+    '--heading "Fixed snapshot: no refresh" --markdown-file NOTE.md, and skip this step, saying '
+    "so in one line. The step stays listed after the note, because the note is the record."
+)
+
+_CADENCE_WHY = (
+    "Record it from the update answer in the brief. First confirm mr-data recipe readiness "
+    "--table {table_id} --current-only --json reports the current revision refresh-ready, or that "
+    "the recipe declares rebuild. A recipe that is not refresh-ready is a design fault to repair "
+    "with mr-data recipe explain, not a reason to skip this step. Then record the cadence and "
+    "the reasoning with promote. "
+)
+
+_NOT_READY_WHY = (
+    "Its current recipe is not refresh-ready: {blocker}. That is a design fault to repair, not a "
+    "state to wait out. Run mr-data recipe explain RECIPE_ID --json, repair the recipe, register "
+    "the revision and resync once, then record the cadence and the reasoning with promote. "
+)
+
+_PARKED_WHY = (
+    "A cadence was requested, but Studio holds it because the current recipe is not "
+    "refresh-ready: {blocker}. That is a design fault to repair, not a state to wait out. Run "
+    "mr-data recipe explain RECIPE_ID --json, repair the recipe, register the revision and resync "
+    "once. Studio restores the held schedule when the recipe is ready."
+)
+
+#: Every block says this: a scratch table is a test, not the delivered dataset.
+SCOPE = "A scratch table you test and demote owes none of these steps."
+
+
+def applies(run: Mapping[str, Any], *, succeeded: bool) -> bool:
+    """Only a full run that succeeded owes delivery.
+
+    A sample is a test, and a refresh or a backfill adds rows to a dataset delivered before. The
+    caller folds a recipe test into ``succeeded``.
+    """
+
+    return succeeded and run.get("mode") == "full"
+
+
+def _step(step: str, command: str, why: str) -> dict[str, str]:
+    return {"step": step, "command": command, "why": why}
+
+
+def _enrichment_step(run_id: str) -> dict[str, str]:
+    return _step("enrichment_offer", f"mr-data models suggest {run_id} --json", _ENRICHMENT_WHY)
+
+
+def _description_why(description: Any) -> str | None:
+    """Why the description step is owed, or ``None`` when the description conforms."""
+
+    verdict = description_shape.check(description)
+    if verdict["conforms"]:
+        return None
+    sections = ", ".join(description_shape.HEADINGS)
+    if verdict["failures"] == ["empty"]:
+        return (
+            "The dataset has no description. Write one in the skill's shape: a bold first "
+            f"sentence, then ## sections from {sections}, in that order. See {SKILL_REFERENCE}."
+        )
+    said = ", ".join(_FAILURE_SAYS[code] for code in verdict["failures"])
+    return (
+        f"The description does not follow the skill's shape: {said}. Rewrite it with a bold first "
+        f"sentence, then ## sections from {sections}, in that order, Coverage and Columns always "
+        f"present. See {SKILL_REFERENCE}."
+    )
+
+
+def required_steps(
+    record: Mapping[str, Any], *, dataset_id: str, run_id: str
+) -> list[dict[str, str]]:
+    """The steps one dataset record still needs, the enrichment offer always last."""
+
+    steps: list[dict[str, str]] = []
+    why = _description_why(record.get("description"))
+    if why is not None:
+        steps.append(
+            _step(
+                "description",
+                f'mr-data dataset set {dataset_id} --name "TITLE" --topics "TOPIC,TOPIC" '
+                "--description-file DESCRIPTION.md",
+                why,
+            )
+        )
+    if not record.get("cover"):
+        steps.append(
+            _step(
+                "cover",
+                f'mr-data cover {dataset_id} "WHAT THE IMAGE SHOWS"',
+                "The dataset has no cover. Generate one.",
+            )
+        )
+    steps.append(_enrichment_step(run_id))
+    return steps
+
+
+def _search_state(answer: Mapping[str, Any], table_id: str) -> str:
+    """``active``, ``building`` (a search job is running for this version) or ``none``."""
+
+    if answer.get("schema_version") != "table-search-metadata.v1":
+        raise ValueError("not a table-search metadata answer")
+    if answer.get("table_id") != table_id:
+        raise ValueError("table-search metadata for another table")
+    if isinstance(answer.get("generation_id"), str) and answer["generation_id"]:
+        return "active"
+    # Only a running job counts: a revision whose build failed, or a spec never built, is owed.
+    if answer.get("preparation_state") == "pending":
+        return "building"
+    return "none"
+
+
+def _search_step(
+    client: StudioV4DatasetClient, table_id: str
+) -> tuple[dict[str, str] | None, str | None]:
+    """The search step when the run's table has no search, and any note. Never raises.
+
+    Studio marks no main table, so the step names the rule and the agent skips it, saying why,
+    for a supporting table.
+    """
+
+    try:
+        # Imported here: the search module's imports reach the run module, which imports this one.
+        from mostlyright.data_harness.thin.v4_search import TABLE_SEARCH_PATH
+
+        answer = client._call(
+            "GET",
+            TABLE_SEARCH_PATH.format(table_id=table_id),
+            query={"links": "false"},
+            expected=(200,),
+        )
+        state = _search_state(answer, table_id)
+    except ThinLaneError as refusal:
+        return None, _search_unchecked(table_id, f" ({refusal.code})")
+    except Exception:  # a failed read must never fail the command
+        return None, _search_unchecked(table_id, "")
+    if state == "active":
+        return None, None
+    if state == "building":
+        return None, (
+            f"Search is building for this version. Read mr-data search status {table_id} "
+            "until it is active."
+        )
+    why = f"This run's table, {table_id}, has no search. {_SEARCH_WHY}"
+    return _step("search", "mr-data search inspect --recipe RECIPE.json --json", why), None
+
+
+def _search_unchecked(table_id: str, why: str) -> str:
+    return f"Search could not be checked{why}. Read mr-data search status {table_id}."
+
+
+def _refusal_said(error: BaseException) -> str:
+    return f" ({error.code})" if isinstance(error, ThinLaneError) else ""
+
+
+def _table_record(
+    client: StudioV4DatasetClient, table_id: str
+) -> tuple[Mapping[str, Any] | None, str | None]:
+    """The Studio table record, or a note saying it could not be read. Never raises."""
+
+    try:
+        record = client._call("GET", GET_TABLE_PATH.format(table_id=table_id), expected=(200,))
+    except Exception as error:  # a failed read must never fail the command
+        return None, (
+            f"View and cadence could not be checked{_refusal_said(error)}. "
+            f"Read mr-data table {table_id}."
+        )
+    if not isinstance(record, Mapping) or record.get("table_id") != table_id:
+        return None, f"View and cadence could not be checked. Read mr-data table {table_id}."
+    return record, None
+
+
+def cadence_step(
+    record: Mapping[str, Any], *, table_id: str, dataset_id: str
+) -> dict[str, str] | None:
+    """The cadence step when a live table has no schedule and no cadence recorded.
+
+    Studio reports both as null until an explicit cadence is chosen, and while a readiness hold
+    parks a requested schedule. Studio also reads every such live table as ``held``, so ``held``
+    alone says nothing: a parked schedule or a named blocker is what makes it a repair.
+    """
+
+    if record.get("promotion_status") != "live":
+        return None
+    if record.get("schedule") is not None or record.get("cadence") is not None:
+        return None
+    strategy = record.get("refresh_strategy")
+    strategy = strategy if isinstance(strategy, Mapping) else {}
+    blocker = strategy.get("blocker") or strategy.get("blocker_code")
+    said = blocker if isinstance(blocker, str) and blocker else "a blocking finding"
+    readiness = f"mr-data recipe readiness --table {table_id} --current-only --json"
+    if isinstance(strategy.get("held_schedule"), Mapping):
+        why = (
+            _PARKED_WHY.format(blocker=said)
+            if isinstance(blocker, str) and blocker
+            else "A cadence was requested, and Studio has not yet restored it. Read "
+            f"{readiness} and mr-data table {table_id} until the schedule is in force."
+        )
+        return _step(
+            "cadence",
+            readiness,
+            f"This run's table, {table_id}, has no refresh cadence in force. " + why,
+        )
+    snapshot = _SNAPSHOT.format(dataset_id=dataset_id)
+    if isinstance(blocker, str) and blocker:
+        return _step(
+            "cadence",
+            readiness,
+            f"This run's table, {table_id}, has no refresh cadence recorded. "
+            + _NOT_READY_WHY.format(blocker=said)
+            + snapshot,
+        )
+    return _step(
+        "cadence",
+        f'mr-data promote {table_id} --cadence "CRON OR every Nh" --why "WHY THIS FITS THE '
+        'SOURCE" --json',
+        f"This run's table, {table_id}, has no refresh cadence recorded. "
+        + _CADENCE_WHY.format(table_id=table_id)
+        + snapshot,
+    )
+
+
+def _cloud_view_client(transport: Transport) -> Any:
+    """The Cloud table-view client on the stored device key. Tests replace it."""
+
+    # Imported here: the view module reads the credential store, which only this step needs.
+    from mostlyright.data_harness.thin import table_view
+
+    return table_view.cloud_client(transport)
+
+
+def _view_step(
+    record: Mapping[str, Any], *, table_id: str, transport: Transport
+) -> tuple[dict[str, str] | None, str | None]:
+    """The view step when the live table has no saved view, and any note. Never raises."""
+
+    from mostlyright.data_harness.thin import table_view
+
+    try:
+        coordinates = table_view.live_coordinates(record)
+    except Exception:
+        coordinates = None
+    if coordinates is None:
+        return None, None
+    dataset_id, live = coordinates
+    try:
+        saved = table_view.saved_state(
+            _cloud_view_client(transport),
+            dataset_id=dataset_id,
+            table_id=table_id,
+            live_version_id=live,
+        )
+    except Exception as error:  # a failed read must never fail the command
+        return None, (
+            f"The table view could not be checked{_refusal_said(error)}. "
+            f"Read mr-data table view {table_id}."
+        )
+    if saved:
+        return None, None
+    why = f"This run's table, {table_id}, has no saved view. {_VIEW_WHY}"
+    return _step("table_view", f"mr-data table view {table_id} --json", why), None
+
+
+def _table_steps(
+    client: StudioV4DatasetClient,
+    run: Mapping[str, Any],
+    *,
+    dataset_id: str,
+    transport: Transport,
+) -> tuple[list[dict[str, str]], list[str]]:
+    """Search, view and cadence for the run's table, in that order, and any notes."""
+
+    try:
+        table_id = identifier(run.get("table_id"), "table identifier")
+    except Exception:  # a record without a usable table identifier is still a delivered run
+        return [], ["Search, view and cadence could not be checked: the run names no table."]
+    steps: list[dict[str, str]] = []
+    notes: list[str] = []
+    search, note = _search_step(client, table_id)
+    if search is not None:
+        steps.append(search)
+    if note is not None:
+        notes.append(note)
+    record, note = _table_record(client, table_id)
+    if record is None:
+        notes.append(str(note))
+        return steps, notes
+    view, note = _view_step(record, table_id=table_id, transport=transport)
+    if view is not None:
+        steps.append(view)
+    if note is not None:
+        notes.append(note)
+    cadence = cadence_step(record, table_id=table_id, dataset_id=dataset_id)
+    if cadence is not None:
+        steps.append(cadence)
+    return steps, notes
+
+
+def _unchecked(run_id: str, note: str) -> dict[str, Any]:
+    return {
+        "version": DELIVERY_VERSION,
+        "scope": SCOPE,
+        "required": [_enrichment_step(run_id)],
+        "note": note,
+    }
+
+
+def block(
+    client: StudioV4DatasetClient,
+    run: Mapping[str, Any],
+    run_id: str,
+    *,
+    transport: Transport | None = None,
+) -> dict[str, Any]:
+    """The ``delivery`` member for one succeeded full run. Never raises."""
+
+    try:
+        dataset_id = identifier(run.get("dataset_id"), "dataset identifier")
+    except Exception:  # a record without a usable dataset identifier is still a delivered run
+        return _unchecked(run_id, "Presentation could not be checked: the run names no dataset.")
+    try:
+        record = client.dataset(dataset_id)
+    except ThinLaneError as refusal:
+        record = f" ({refusal.code})"
+    except Exception:  # a failed read must never fail the command
+        record = ""
+    if not isinstance(record, Mapping):
+        why = record if isinstance(record, str) else ""
+        return _unchecked(
+            run_id,
+            f"Presentation could not be checked{why}. Read mr-data dataset show {dataset_id}.",
+        )
+    steps = required_steps(record, dataset_id=dataset_id, run_id=run_id)
+    table, notes = _table_steps(
+        client, run, dataset_id=dataset_id, transport=transport or client.transport
+    )
+    steps[len(steps) - 1 : len(steps) - 1] = table
+    delivered: dict[str, Any] = {"version": DELIVERY_VERSION, "scope": SCOPE, "required": steps}
+    if notes:
+        delivered["note"] = " ".join(notes)
+    return delivered
+
+
+def for_run(
+    session: StudioSession,
+    transport: Transport,
+    run: Mapping[str, Any],
+    run_id: str,
+    *,
+    succeeded: bool,
+) -> dict[str, Any] | None:
+    """The ``delivery`` member, or ``None`` when the run owes none."""
+
+    if not applies(run, succeeded=succeeded):
+        return None
+    try:
+        return block(
+            StudioV4DatasetClient(session, transport=transport), run, run_id, transport=transport
+        )
+    except Exception:  # the block must never fail the command
+        return _unchecked(run_id, "Presentation could not be checked.")
+
+
+def merged(blocks: Iterable[Mapping[str, Any] | None]) -> dict[str, Any] | None:
+    """One block for several runs: every step once, in run order."""
+
+    steps: list[dict[str, str]] = []
+    notes: list[str] = []
+    seen: set[tuple[Any, Any]] = set()
+    for one in blocks:
+        if not isinstance(one, Mapping):
+            continue
+        for step in one.get("required") or ():
+            key = (step.get("command"), step.get("why"))
+            if key in seen:
+                continue
+            seen.add(key)
+            steps.append(dict(step))
+        note = one.get("note")
+        if isinstance(note, str) and note not in notes:
+            notes.append(note)
+    if not steps:
+        return None
+    delivered: dict[str, Any] = {"version": DELIVERY_VERSION, "scope": SCOPE, "required": steps}
+    if notes:
+        delivered["note"] = " ".join(notes)
+    return delivered