mostlyright-data 0.24.0__tar.gz → 0.25.1__tar.gz

{mostlyright_data-0.24.0 → mostlyright_data-0.25.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.24.0
+Version: 0.25.1
 Summary: Mostly Right hosted CLI for reviewed datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/
@@ -112,14 +112,17 @@ its raw inputs still retained. Replay compares against that run and never become
 Studio returns a typed refusal when replay is unavailable; the CLI does not fetch sources locally.
 
 The hosted engine executes sample, full and refresh runs. Studio's action classifier can name
-closed-source reuse, request-window or collection acquisition, and recorded stream input, but the
-current worker has only two executable normal-refresh materializers: an exact single direct
-partition request-window plan with a compatible predecessor, and an all-recorded-stream plan.
-Closed-only, collection, and mixed plans return `RESYNC_REQUIRED` before acquisition, as does a
-mutable snapshot or other unwindowed source. Nothing is revalidated or re-acquired whole as an
-implicit fallback. Use `mr-data table resync TABLE_ID --request-id UUID` when a deliberate full
-source reread is intended, retaining that UUID through an uncertain response. URL windows may use
-declared query parameters or path placeholders; a fixed date URL does not advance automatically.
+closed-source reuse, request-window or collection acquisition, and recorded stream input, but
+normal refresh admits only two families of plan: every source a recorded stream, and at least one
+direct partition request window with a compatible predecessor, with `closed` reuse permitted
+beside it. Once such a 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 one the table declares. Closed-only plans, any plan carrying a collection, a window beside a
+recorded stream, a mutable snapshot and any other unwindowed source return `RESYNC_REQUIRED`
+before acquisition. Nothing is revalidated or re-acquired whole as an implicit fallback. Use
+`mr-data table resync TABLE_ID --request-id UUID` when a deliberate full source reread is
+intended, retaining that UUID through an uncertain response. URL windows may use declared query
+parameters or path placeholders; a fixed date URL does not advance automatically.
 Configure a correction lookback where the publisher can revise earlier observations.
 
 A source exposing only its current snapshot cannot supply a historical delta. It is supported only

{mostlyright_data-0.24.0 → mostlyright_data-0.25.1}/README.md

@@ -100,14 +100,17 @@ its raw inputs still retained. Replay compares against that run and never become
 Studio returns a typed refusal when replay is unavailable; the CLI does not fetch sources locally.
 
 The hosted engine executes sample, full and refresh runs. Studio's action classifier can name
-closed-source reuse, request-window or collection acquisition, and recorded stream input, but the
-current worker has only two executable normal-refresh materializers: an exact single direct
-partition request-window plan with a compatible predecessor, and an all-recorded-stream plan.
-Closed-only, collection, and mixed plans return `RESYNC_REQUIRED` before acquisition, as does a
-mutable snapshot or other unwindowed source. Nothing is revalidated or re-acquired whole as an
-implicit fallback. Use `mr-data table resync TABLE_ID --request-id UUID` when a deliberate full
-source reread is intended, retaining that UUID through an uncertain response. URL windows may use
-declared query parameters or path placeholders; a fixed date URL does not advance automatically.
+closed-source reuse, request-window or collection acquisition, and recorded stream input, but
+normal refresh admits only two families of plan: every source a recorded stream, and at least one
+direct partition request window with a compatible predecessor, with `closed` reuse permitted
+beside it. Once such a 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 one the table declares. Closed-only plans, any plan carrying a collection, a window beside a
+recorded stream, a mutable snapshot and any other unwindowed source return `RESYNC_REQUIRED`
+before acquisition. Nothing is revalidated or re-acquired whole as an implicit fallback. Use
+`mr-data table resync TABLE_ID --request-id UUID` when a deliberate full source reread is
+intended, retaining that UUID through an uncertain response. URL windows may use declared query
+parameters or path placeholders; a fixed date URL does not advance automatically.
 Configure a correction lookback where the publisher can revise earlier observations.
 
 A source exposing only its current snapshot cannot supply a historical delta. It is supported only

{mostlyright_data-0.24.0 → mostlyright_data-0.25.1}/pyproject.toml

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

{mostlyright_data-0.24.0 → mostlyright_data-0.25.1}/skills/mr-data-build/SKILL.md

@@ -37,6 +37,24 @@ 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 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`, with `closed`
+   siblings permitted beside it. A closed-only plan, any plan carrying a `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.
 6. Read [build sizing](references/6-build-one-run-sized-to-acquire-every-measured-source-whole.md).
    Choose bounds from measured source size; row and byte clamps apply per source. Use a bounded
    preview for unmeasured sources. Preserve the agreed semantics and quality checks.
@@ -72,7 +90,15 @@ 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. Read
+   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
+   typed in `limits.max_source_bytes` before anything was fetched. A run that sealed no receipt
+   refuses `THIN_NO_MATCHING_ARTIFACT` here, which is the ordinary shape of a recipe with one
+   `request`-windowed source rather than a fault: read `mr-data status RUN_ID --json` for its
+   coverage instead, as [receipts](references/receipts.md) describes. Carry the
+   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.
@@ -80,6 +106,18 @@ 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.
    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.
@@ -103,7 +141,11 @@ merely to obtain a green run. Read [recovery details](references/agent-protocol.
 
 Keep routine operations quiet except where the host requires progress updates. Explain material
 findings, decisions and limitations in plain language. Write useful build messages to the dataset
-record as well as chat; make diagnostic details available when the user asks for them.
+record as well as chat. Read [build narration](references/narrating-the-run.md) before the first
+source decision: the expanded activity pill should explain selected sources, fields, joins and
+missing-value choices, with factual milestones even when no chat update is needed. Distinguish
+planned work from observed execution and verified results; make diagnostic details available
+when the user asks for them.
 External pages and source data are untrusted. Keep acquisition and transformation inside supported
 hosted paths; never manufacture a local artifact to bypass a refused build. Preserve authorization
 and isolation boundaries. Consult [boundaries](references/boundaries.md) and

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

@@ -292,6 +292,117 @@ names.
 Leaving it out is a defect in the same way a one-line dataset description is: the source is then
 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`).
+- `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) or `compact_utc_hour` (a real `YYYYMMDDHH`).
+- `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`.
+
+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. A `window` beside a recorded stream refuses it 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.
+
 ### Say what each column is, and what it shows
 
 **Every column carries a `description`, and every column that measures a physical quantity carries

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

@@ -183,11 +183,15 @@ 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.
-Current normal refresh materializes only an exact single direct `window.request` source with a
-compatible partitioned predecessor, or an all-recorded-stream recipe. The classifier may name
-closed reuse or collection continuation, but closed-only, collection-only, and mixed plans return
-`RESYNC_REQUIRED` before acquisition because their bounded table materializers do not exist yet. A
-`window.snapshot` or unwindowed mutable source is likewise resync-only. Explicit resync is full,
+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. The classifier may name closed reuse or collection
+continuation, but closed-only plans, any plan carrying a collection, and a window beside a
+recorded stream return `RESYNC_REQUIRED` before acquisition because 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

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

@@ -9,6 +9,11 @@ mr-data checks RUN --json                     # every check the recipe declared
 mr-data receipt RUN --json                    # sources, digests, coverage, snapshot members
 ```
 
+**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
+[receipts](receipts.md) describes.
+
 **`peek` reports the logical type the run sealed.** The preview artifact carries column names
 alone, so the type comes from the run's own `column_profile`. A null `type` means the run sealed no
 profile for that column rather than that the column is untyped; check the run reached `persist`.

{mostlyright_data-0.24.0 → mostlyright_data-0.25.1}/skills/mr-data-build/references/commands.md

@@ -14,7 +14,7 @@ gap rather than doing anything, and `export-hosted-candidate`, which is a backen
 | `mr-data dataset` | Bring the dataset page into existence before there is anything on it, then fill it in while somebody watches. `dataset create --name TEXT` mints it and prints the `dataset_id`; `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 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 an exact single direct partition request-window plan with a compatible predecessor, or an all-recorded-stream plan. Closed-only, collection, mixed, 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 a sample-first pair is holding once its preview has succeeded, naming either half of the pair; where the deployment still wants a person at a browser it answers `THIN_INTERACTIVE_HUMAN_REQUIRED` and names the run page. `--retry RUN_ID` tries one failed run again when its triple carries `room_fault: true`, re-stating that run's own coordinate under a byte ceiling that cannot narrow it, and refuses with the triple when the recipe was at fault. `--cancel RUN` stops one. |
+| `mr-data run` | Start one run against a registered recipe, named as `--recipe RECIPE_ID --digest RECIPE_DIGEST` — both required, neither positional, and the digest is the bare hex the registration receipt printed. The mode is one of six: `sample`, `full`, `refresh`, `backfill`, `compact` and `replay`. Four have a shorthand flag (`--sample`, `--full`, `--refresh`, `--backfill`) and two do not, so write `--mode MODE`, which is accepted for every one of them. A refresh executes only Studio's persisted 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. Closed-only, any plan carrying a 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 a 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 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. |
@@ -23,7 +23,7 @@ gap rather than doing anything, and `export-hosted-candidate`, which is a backen
 | `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 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. |
+| `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 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. |
@@ -46,13 +46,41 @@ action, and blocking source names. It reads persisted facts; it does not authori
 
 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 an exact single direct partition request-window plan with a compatible
-predecessor, or an all-recorded-stream plan. Closed-only, collection, mixed, snapshot, and
-unwindowed plans return `RESYNC_REQUIRED` before acquisition. `mr-data table resync TABLE --request-id UUID` is the explicit
+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. Closed-only, any plan carrying a 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. A sample-first resync instead uses
 `--approve-full` only 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
+and no range is refused `RUN_WINDOW_REQUIRED` at the `transform` stage, before a source is fetched.
+Write `--window START END`, two UTC timestamps, start included and end excluded. Do not subtract
+the lookback yourself: each source's own `lookback_seconds` widens that start backwards and aligns
+it down to a whole UTC day, floored at `start_at`. The lookback never reaches the end, though the
+end is still aligned up to the next whole UTC day. `--backfill` takes
+the same pair, and the client refuses a backfill without it before anything is sent. Nothing local
+requires it on a refresh, so a refresh without it is accepted and dies in the run.
+
+**A refresh asked for before the source's period closes is refused `WINDOW_NOT_READY`.** This
+reaches only a source declaring `refresh_readiness`, which says the publisher serves a UTC day
+once that day is over. Studio floors `now` minus the declared lag to the UTC day, and a refresh
+whose range starts at or after that floor names no completed period. The run fails at once rather
+than being held. A refresh asked for from the dashboard in that state is recorded as a noop with
+the same code and starts no run. Only time clears it, and the refused run's range is frozen, so a
+new run is needed once the day is over. Report the code and wait rather than retrying or revising
+the recipe.
+
+**A refresh on the one-windowed-source bounded route seals no `receipt`.** `mr-data receipt`
+answers `THIN_NO_MATCHING_ARTIFACT` and names what the run did seal, which is the ordinary shape
+of that route rather than a fault. Read `mr-data status RUN_ID --json` instead: its `coverage`
+block carries `rows`, `bytes`, `window` and `truncated`, and on a one-source recipe that is that
+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 twenty-eight answer from Studio. Twelve only
 read: `status`, `runs`, `watch`, `peek`, `receipt`, `checks`, `download`, `verify`, `parts`,

{mostlyright_data-0.24.0 → mostlyright_data-0.25.1}/skills/mr-data-build/references/narrating-the-run.md

@@ -1,5 +1,32 @@
 ## Narrating the run
 
+### Content for the expanded activity pill
+
+Give the reader a short heading and enough detail to understand the actual dataset. At meaningful
+milestones, record what changed in their understanding:
+
+- Sources: which publisher and format supply which fields, with observed coverage and limitations.
+- Extraction: which fields were inspected and how they map to the requested columns.
+- Cleaning and joins: exact matching keys, conversions, row grain and missing-value choices,
+  including why a choice preserves the requested meaning.
+- Result: verified output rows and columns, checks and source coverage, retaining any truncation
+  qualification. A successful run alone does not prove the result meets the brief.
+
+Use the recipe for planned semantics, worker updates for reported execution, and status, checks,
+receipt and inspected output for completion claims. For example, before execution say “The recipe
+matches observations by station and date”; say “Matching observations by station and date” only
+when the worker reports that operation. A broad transform-stage update does not establish which
+join is executing. Do not infer all sources were fetched, checks passed, or work finished from a
+timer, progress count, quiet stream or agent activity. Worker progress is provisional reporting,
+not verified result evidence. Keep names and numbers grounded in this dataset rather than copying
+an example. Saving a table and making the dataset public are separate actions.
+
+Use a small number of substantive notes, not a second event stream. Update a settled decision's
+cell instead of repeatedly appending the same explanation. The UI renders worker progress itself;
+agent prose supplies the source choices and reasoning that progress cannot explain.
+
+### Dataset and run records
+
 There are two decision records and they are not interchangeable. A cell is the same document in
 both: one outcome-led heading, a markdown body, and typed blocks the Dataset page lays out as rows
 a reader can compare. What differs is which log it lands in and when that log closes.
@@ -7,7 +34,7 @@ a reader can compare. What differs is which log it lands in and when that log cl
 The rule that binds them to the chat is in the
 [User communication contract](user-communication-contract.md#user-communication-contract): every message is a cell, in the same
 words, at the same moment — the message's first sentence is the `--heading` and the whole message
-is the body.
+is the body. Factual page-only milestone cells are also useful; they do not require extra chat.
 
 **The DATASET's record is the primary one, and it never closes.**
 `mr-data dataset note DATASET_ID` writes it. The sources compared and refused, the grain argued
@@ -28,8 +55,10 @@ and what belongs there is what is true of that run alone: a clamp that truncated
 not pass, the exact revision this attempt tested. A run's narrative closes when the run reaches a
 terminal state, and an append after that answers `409 RUN_NARRATIVE_CLOSED` — a refusal no client
 check can soften, because only the backend knows the run has finished. A bounded run reaches its
-terminal state in seconds, so "while the run is going" means immediately after `mr-data run`
-returns the identifier, not after `status` says the run succeeded.
+terminal state in seconds, so append run-specific notes while it is known to be active. If an
+append races completion and receives `RUN_NARRATIVE_CLOSED`, write the useful finding to the
+dataset record with the run identified in its context. Post-run checks, coverage and delivery
+always belong in the dataset record; do not retry appending to a closed run.
 
 ```sh
 mr-data note --run RUN_ID --heading "The row ceiling stopped one source short" \

{mostlyright_data-0.24.0 → mostlyright_data-0.25.1}/skills/mr-data-build/references/promote.md

@@ -47,13 +47,16 @@ the cadence itself, and it belongs to the user.
 This call records a schedule; it is not proof of data continuation. Schedule only a current recipe
 that `mr-data recipe readiness --json` reports as refresh-ready. Studio must have a persisted bounded
 action for every source. The classifier may name closed reuse, a request-window or collection
-delta, or recorded stream input, but current normal refresh executes only an exact single direct
-partition request-window plan with a compatible predecessor, or an all-recorded-stream plan.
-Closed-only, collection, mixed, snapshot, and unwindowed plans return `RESYNC_REQUIRED` before
-acquisition. Use `mr-data table resync TABLE_ID --request-id UUID` when a full reread is
-genuinely needed; it is an explicit run, not a schedule fallback. Only returned state and durable
-run evidence support a claim that the table is caught up or refreshing. If that evidence is absent,
-report that a schedule was recorded and that ongoing freshness is unavailable.
+delta, or recorded stream input, but normal refresh admits only an all-recorded-stream plan, or a
+plan holding at least one direct partition request window with a compatible predecessor, `closed`
+reuse permitted beside it. A plan of more than one source is admitted only when its windows agree
+on one `merge.materialization`, `merge.partition.column` and `merge.partition.key`, and that
+column is a name the table declares. Closed-only, collection, snapshot, and unwindowed plans, and
+a window beside a recorded stream, return `RESYNC_REQUIRED` before acquisition. Use `mr-data
+table resync TABLE_ID --request-id UUID` when a full reread is genuinely needed; it is an
+explicit run, not a schedule fallback. Only returned state and durable run evidence support a
+claim that the table is caught up or refreshing. If that evidence is absent, report that a
+schedule was recorded and that ongoing freshness is unavailable.
 
 `mr-data pin TABLE_ID --version VERSION_ID` freezes the pointer on an exact version for a rollback
 or a hold, `mr-data unpin TABLE_ID` resumes tracking, and `mr-data demote TABLE_ID` detaches the

{mostlyright_data-0.24.0 → mostlyright_data-0.25.1}/skills/mr-data-build/references/receipts.md

@@ -23,6 +23,24 @@ A flag that cannot mean what it means locally is accepted and reported, never re
 digests, sources, timings and checks are already on the record it read. Read that key before
 repeating an argument that did nothing; only flags actually passed are reported.
 
+### Runs that seal no receipt
+
+A recipe with exactly one source carrying a request window builds on a bounded route of its own,
+and that route seals no `receipt` artifact. It is the route the first `full` build of such a recipe
+takes, and every refresh after it takes the same one. `mr-data receipt` answers
+`THIN_NO_MATCHING_ARTIFACT` and names what the run did seal, which is the raw source bundles, the
+source state index, the source inventory, an incremental proof, the column profile, the preview,
+the parts and the manifest. The run's own `receipt_digest` names that incremental proof rather than
+a receipt. This is not a failure and not a deployment problem, so do not retry it and do not report
+it as one.
+
+What the run delivered is not lost with the receipt. `mr-data status RUN_ID --json` carries the
+run record's `coverage` block: `rows`, `bytes`, `window` and `truncated`. Studio folds the
+worker's per-source array into that one block, and on this route the recipe has exactly one
+source, so the fold is that source's own numbers. `rows` is rows kept and `bytes` is bytes
+fetched. The one field only a receipt carries is `rows_available`, so a run on this route cannot
+say how many rows it left behind, only that `truncated` says there were some.
+
 ### Asking the table a question
 
 **In `mr-data query` the relation is always named `run_table`**, never the name the recipe gave the

{mostlyright_data-0.24.0 → mostlyright_data-0.25.1}/skills/mr-data-build/references/user-communication-contract.md

@@ -8,7 +8,7 @@ cursors, digests, receipts, retry mechanics or service boundaries in anything th
 Where the host requires periodic status, that cadence is the only exception: one concise
 outcome-oriented sentence about the dataset stage or an observed result, inventing no progress.
 
-**Speak at six boundaries and nowhere else.** Each is a stage above, and each is one message:
+**Send chat messages at these six boundaries.** Each is a stage above, and each is one message:
 
 | When | What it carries |
 | --- | --- |
@@ -28,9 +28,14 @@ message sent during a build is also a cell on the dataset's record: write it wit
 `mr-data dataset note`, taking the message's first sentence as the heading and the whole message as
 the body, in the same breath as sending it. The two are one act, not a message and a later summary
 of it. A person who joins by opening the page reads what the person in the chat read, and a person
-who scrolls the chat away still has it. The rule runs both ways: do not write a cell about work
-this document says to keep silent, and do not send a message you are not willing to write down. It
-licenses no extra update.
+who scrolls the chat away still has it.
+
+The expanded activity pill may also carry page-only milestone cells: selected sources and their
+fields, a settled join or missing-value decision, a material finding, or a verified result. Write
+one when the fact changes what a reader understands about the dataset; do not copy every worker
+tick or routine command into a cell. These notes need no matching chat message. Preparation,
+retries and transport mechanics remain silent on both surfaces. See
+[build narration](narrating-the-run.md) for the distinction between planned and observed work.
 
 **Activity is not narration.** Setting the dataset's activity is a routine, silent act like any
 other command: never a chat message and never a cell. The rule above governs what is said;

{mostlyright_data-0.24.0 → mostlyright_data-0.25.1}/skills/mr-data-build/references/writing-a-decision-record.md

@@ -28,8 +28,15 @@ themselves. Do not present a sequence of unlabeled paragraphs or default to a bu
 
 ### Agent presence lifecycle
 
-The floating pill represents only your active work. Start `dataset activity` immediately after creation, update the sentence when your task changes, and renew at least once a minute while you are actively working. The default lease is two minutes. Do not leave a detached heartbeat running after your turn ends. Worker ingestion progress has its own table surface and is not proof that you are working.
+The floating pill combines agent activity with worker build progress. Your activity lease
+represents only your active work. Start `dataset activity` immediately after creation, update the
+sentence when your task changes, and renew at least once a minute while you are actively working.
+The default lease is two minutes. Do not leave a detached heartbeat running after your turn ends.
+Worker progress can continue in the expanded pill after your lease ends; it is not proof that you
+are working. Do not renew your lease just to keep worker progress visible.
 
 When recovering, report what you are trying now; an earlier failed attempt belongs in the record. Before every final handoff, cancellation, or exhausted stop, report `--phase done` with a truthful final sentence (for example, “Dataset ready to explore” or “Stopped before the build completed”). Do this even when tables are not enabled. Only use `waiting_on_you` when a question is actually open — the brief at stage 2, the plan at stage 4, or the full build after a preview — and never under a delegation, which leaves nothing to wait on. A table going live does not finish your agent session.
 
-Stage 1 opened the dataset before research began; keep that same tab. Enable its optional Follow agent control for a watch-along experience; manual scrolling pauses it and must never be overridden.
+Stage 1 opened the dataset before research began; keep that same tab. Follow agent starts enabled
+for a watch-along experience; respect the viewer’s choice to pause or disable it. Manual scrolling
+pauses following and must never be overridden.