mostlyright-data 0.23.0__tar.gz → 0.25.0__tar.gz

{mostlyright_data-0.23.0 → mostlyright_data-0.25.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.23.0
+Version: 0.25.0
 Summary: Mostly Right hosted CLI for reviewed datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/
@@ -89,6 +89,17 @@ can reissue supported platform execution failures without changing the recipe.
 
 Use the identifiers returned by registration and run submission. `mr-data dataset create`
 creates a dataset page before a recipe is ready. `mr-data watch RUN_ID` follows a submitted run.
+A scheduled refresh runs only Studio's persisted bounded source-action plan; it never silently
+falls back to a mutable whole-source fetch. `mr-data table resync TABLE_ID --request-id UUID`
+explicitly requests a full source reread when that is needed. Choose and retain the UUID before
+submitting: if the response is lost, repeat that exact command with the same UUID rather than
+starting another reread. A persisted spend hold is still an accepted resync: its receipt names
+the run, projection and exact `mr-data run --confirm-held RUN_ID` action. If it is a sample-first
+preview, confirm that preview first, then release its linked full
+only after the preview succeeds. `mr-data recipe readiness` reads Studio's paginated,
+immutable-revision inventory before a production-wide schedule sweep: predecessor,
+incremental-materialization and differential-proof readiness, together with each source's next
+action. It reports Studio's persisted facts; it does not authorize a schedule.
 
 To request an offline replay of retained inputs with a registered revision:
 
@@ -100,16 +111,23 @@ Studio must have replay enabled and the named successful run must belong to the
 its raw inputs still retained. Replay compares against that run and never becomes the live version.
 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. A refresh uses each source's declared
-update behavior: bounded source windows merge with retained history; snapshot sources are
-revalidated or acquired again. The table's transformations and checks run over the resulting
-source relations. 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 remains a
-supported source, with snapshot comparison and recomputation rather than a claim that only new
-rows were fetched. Recorded streams use their registered capture and continuation semantics.
+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
+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
+through an explicit table resync; refresh does not turn its whole current result into an
+incremental update. Recorded streams use their registered capture and continuation semantics.
 
 See [Recipe documents](docs/RECIPE-DOCUMENT.md) for source-window and bootstrap contracts.
 A table's first succeeded run goes live on its own, whatever mode it was; `mr-data promote
@@ -135,7 +153,8 @@ worker executables or image publisher.
 - [Recipe examples](https://mostlyright.md/docs/recipes/)
 - [Join market settlements](https://mostlyright.md/docs/recipes/market-settlement-join/)
 - [Compare a forecast with observations](https://mostlyright.md/docs/recipes/forecast-vs-observation/)
-- [Replace a snapshot on refresh](https://mostlyright.md/docs/recipes/snapshot-window/)
+- [Model a snapshot source](https://mostlyright.md/docs/recipes/snapshot-window/) — normal refresh
+  is unavailable until its bounded materializer ships; use explicit table resync today
 - [Union many weather stations](https://mostlyright.md/docs/recipes/many-station-weather/)
 - [Aggregate a stream into bars](https://mostlyright.md/docs/recipes/stream-to-bars/)
 - [Use a public dataset](https://mostlyright.md/docs/guides/use-public-datasets/)

{mostlyright_data-0.23.0 → mostlyright_data-0.25.0}/README.md

@@ -77,6 +77,17 @@ can reissue supported platform execution failures without changing the recipe.
 
 Use the identifiers returned by registration and run submission. `mr-data dataset create`
 creates a dataset page before a recipe is ready. `mr-data watch RUN_ID` follows a submitted run.
+A scheduled refresh runs only Studio's persisted bounded source-action plan; it never silently
+falls back to a mutable whole-source fetch. `mr-data table resync TABLE_ID --request-id UUID`
+explicitly requests a full source reread when that is needed. Choose and retain the UUID before
+submitting: if the response is lost, repeat that exact command with the same UUID rather than
+starting another reread. A persisted spend hold is still an accepted resync: its receipt names
+the run, projection and exact `mr-data run --confirm-held RUN_ID` action. If it is a sample-first
+preview, confirm that preview first, then release its linked full
+only after the preview succeeds. `mr-data recipe readiness` reads Studio's paginated,
+immutable-revision inventory before a production-wide schedule sweep: predecessor,
+incremental-materialization and differential-proof readiness, together with each source's next
+action. It reports Studio's persisted facts; it does not authorize a schedule.
 
 To request an offline replay of retained inputs with a registered revision:
 
@@ -88,16 +99,23 @@ Studio must have replay enabled and the named successful run must belong to the
 its raw inputs still retained. Replay compares against that run and never becomes the live version.
 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. A refresh uses each source's declared
-update behavior: bounded source windows merge with retained history; snapshot sources are
-revalidated or acquired again. The table's transformations and checks run over the resulting
-source relations. 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 remains a
-supported source, with snapshot comparison and recomputation rather than a claim that only new
-rows were fetched. Recorded streams use their registered capture and continuation semantics.
+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
+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
+through an explicit table resync; refresh does not turn its whole current result into an
+incremental update. Recorded streams use their registered capture and continuation semantics.
 
 See [Recipe documents](docs/RECIPE-DOCUMENT.md) for source-window and bootstrap contracts.
 A table's first succeeded run goes live on its own, whatever mode it was; `mr-data promote
@@ -123,7 +141,8 @@ worker executables or image publisher.
 - [Recipe examples](https://mostlyright.md/docs/recipes/)
 - [Join market settlements](https://mostlyright.md/docs/recipes/market-settlement-join/)
 - [Compare a forecast with observations](https://mostlyright.md/docs/recipes/forecast-vs-observation/)
-- [Replace a snapshot on refresh](https://mostlyright.md/docs/recipes/snapshot-window/)
+- [Model a snapshot source](https://mostlyright.md/docs/recipes/snapshot-window/) — normal refresh
+  is unavailable until its bounded materializer ships; use explicit table resync today
 - [Union many weather stations](https://mostlyright.md/docs/recipes/many-station-weather/)
 - [Aggregate a stream into bars](https://mostlyright.md/docs/recipes/stream-to-bars/)
 - [Use a public dataset](https://mostlyright.md/docs/guides/use-public-datasets/)

{mostlyright_data-0.23.0 → mostlyright_data-0.25.0}/pyproject.toml

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

{mostlyright_data-0.23.0 → mostlyright_data-0.25.0}/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,12 +90,31 @@ 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. 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.
    Repair only evidenced faults on the same dataset/table and verify the revision again.
-   Record cadence only when authorized; do not promise freshness without evidence.
+   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.

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

@@ -292,6 +292,94 @@ 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.
+
+**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 -- `mr-data receipt RUN --json` carries one entry
+per source with `bytes_fetched`, `rows_kept`, `rows_available` and `truncated`, which is what that
+source actually weighed and how many rows it actually carried. Build once, read that, 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.
+
 ### 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.23.0 → mostlyright_data-0.25.0}/skills/mr-data-build/references/6-build-one-run-sized-to-acquire-every-measured-source-whole.md

@@ -181,11 +181,21 @@ the record — `mr-data run --recipe RECIPE_ID --digest RECIPE_DIGEST --full --c
 held answer prints back as `confirm_command`. Any authenticated surface of the paying workspace may
 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. Author a source window only
-when the publisher has a truthful bounded date endpoint: use query names by default or exact
-`{parameter}` markers in its path, retain a correction lookback, and keep historical sources
-revalidatable unless an explicit closure contract says they cannot change. A refresh merges each
-windowed source slice into retained source state and recomputes the complete transform; unrelated
-snapshot sources are conditionally revalidated or re-acquired as needed. Cursor, pagination and
-new-file discovery need their own supported source contract and must not be represented as a date
-window. A `backfill` may be refused before acquisition; the refusal says so.
+Do not treat the accepted command vocabulary as execution evidence. Before proposing a schedule,
+classify every source under one truthful continuation strategy and record the supporting evidence.
+Normal refresh materializes an all-recorded-stream recipe, or a plan holding at least one direct
+`window.request` source with a compatible partitioned predecessor, `closed` reuse permitted beside
+it. Beside it is not free: as soon as the plan holds more than one source, every window in it must
+agree on one `merge.materialization`, `merge.partition.column` and `merge.partition.key`, and that
+column must be a name the table declares. 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
+that represents the proven strategy. For each incremental source, record the affected key or
+partition and a fixture proving
+that applying its delta to the predecessor produces the same rows as a full build over
+predecessor-plus-delta. A `backfill` may be refused before acquisition; the refusal says so.

{mostlyright_data-0.23.0 → mostlyright_data-0.25.0}/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 narrows each source that declares a supported address window and merges its returned relation into retained source state; unwindowed sources are conditionally revalidated or re-acquired whole, then the full declared transform runs. `--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. |
@@ -29,7 +29,7 @@ gap rather than doing anything, and `export-hosted-candidate`, which is a backen
 | `mr-data diff` | Compare two runs and say what changed. |
 | `mr-data connections` | List saved workspace connections and their current recipe coordinates; `--dataset ID` filters to connections granted to that dataset. No credential values are returned. |
 | `mr-data keys` | Enrol a source credential by name, list the names with their created and rotated times, and delete one. `keys set` reads the value from a file or from standard input and never from the command line; no command prints a value back. |
-| `mr-data stream` | Record a public `wss://` venue so a build can read it. `stream document register --file F` admits the connector document, `stream registry create --digest D` admits a set of them, `stream probe` listens briefly and seals nothing, `stream capture --seconds N` records a bounded window, `stream subscribe` keeps recording, `stream subscription {show|pause|resume|stop} ID` moves one, `stream status ID` reads a capture or a probe, and `stream recordings --document-digest D` names what a build could read and until when. `--seconds` is at most 600. `mr-data run` takes no duration: a build reads sealed batches and is bounded by them. |
+| `mr-data stream` | Record a public `wss://` venue so a build can read it. `stream document register --file F` admits the connector document, `stream registry create --digest D` admits a set of them, `stream probe` listens briefly and seals nothing, `stream capture --seconds N` records a bounded window, and `stream subscribe` keeps recording. `stream subscription {show|pause|resume|stop} ID` retains the legacy full-record interface. `stream subscription quiescence ID` reads the bounded server-computed proof; `pause-cas` and `resume-cas` read its ETag and make one conditional bounded write. An ambiguous CAS failure is not retried until a fresh invocation observes the resource again. `stream status ID` reads a capture or probe, and `stream recordings --document-digest D` names what a build could read and until when. `--seconds` is at most 600. `mr-data run` takes no duration: a build reads sealed batches and is bounded by them. |
 | `mr-data open` | Mint a single-use, short-lived address that continues this session in a browser at one dashboard path, and print it. `--open` hands it to the platform opener. The credential decides who mints: a device credential — what `mr-data login` stores — mints at Cloud, and a personal access token mints at Studio. |
 | `mr-data promote` | Record the cadence one table refreshes on and the reasoning behind it. A table's first succeeded run goes live on its own, so this is not what makes it readable; it is idempotent on a table that is already live, and it is how a withdrawn table is put back. The Harness worker does not perform the catch-up or scheduled refresh; report those only when another deployed component returns durable evidence that it did. |
 | `mr-data reschedule` | Change how often one live table refreshes, without the demote and promote that would reset its bookkeeping and buy a catch-up run. `--cadence` takes a cron expression or an interval such as `every 6h`; `--why` records the reasoning. It starts no run. `--lock` freezes the schedule so Studio stops adjusting it; `--unlock` lets it follow the source again. |
@@ -38,6 +38,24 @@ gap rather than doing anything, and `export-hosted-candidate`, which is a backen
 | `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. |
 
+### Strict refresh controls
+
+`mr-data recipe readiness` pages Studio's immutable-revision inventory and reports predecessor,
+incremental-materialization, and differential-proof readiness, every source's classified next
+action, and blocking source names. It reads persisted facts; it does not authorize a schedule.
+
+A refresh executes only Studio's persisted source-action plan. The classifier may name closed
+reuse, a request window or collection delta, or recorded input, but current normal refresh
+materializes only a plan carrying at least one direct `partition_replace` request window with a
+compatible predecessor, or an all-recorded-stream plan. `closed` siblings may reuse their sealed
+bytes beside a window; a lone window needs a retained source-history record, and several windows
+must agree on materialization and partition layout. 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.
+
 `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.23.0 → mostlyright_data-0.25.0}/skills/mr-data-build/references/live-run.md

@@ -57,6 +57,14 @@ full of a sample-first pair: its bounded preview must seal a downloadable table
 though it could. Keep the raw state internal: say what product decision is needed and give the
 person the single action that lets the build continue.
 
+**`build_scope` says what the build covers, not what it is doing.** A `failed` or `cancelled` run
+covers nothing and says so. A `succeeded` one reports what `coverage.truncated` recorded. Anything
+else states the bound it ran under — a `sample` its ceilings, a `full` the whole dataset, and a
+`full` at `awaiting_sample_approval` the whole dataset plus the preview it waits on. The mode
+alone never establishes a truncation, which is the rule reference 6 states: a sample sized above
+every measured source cut nothing and is the build. It is absent on `refresh`, `backfill`,
+`compact` and `replay`, and it is never evidence that a run is executing; `status` is.
+
 **A failed run always carries the same three members** — `failure_code`, `failure_detail` and
 `failed_stage` — on three surfaces: the run record, the terminal event on the stream, and every
 refusal a command raises about it. `mr-data status` and `mr-data runs` add a fourth reading beside

{mostlyright_data-0.23.0 → mostlyright_data-0.25.0}/skills/mr-data-build/references/promote.md

@@ -44,13 +44,19 @@ Studio stops adjusting it, which is how a person overrides the evidence; `--unlo
 the source again. Do not lock a schedule on your own judgement — it is the same kind of decision as
 the cadence itself, and it belongs to the user.
 
-This call records a schedule; it is not proof of data continuation. The current Harness worker
-can execute a supported refresh, including declared source windows, but it does not make a frozen
-date, a generic cursor or a file listing advance by inference. It also does not attach or execute a
-warehouse schedule. Another deployed Studio or warehouse component may do that work, but only its
-returned state and durable run evidence support a claim that the table is live, caught up, or
-refreshing. If that evidence is absent, report that a schedule was recorded and that ongoing
-freshness is unavailable; do not imply that recording it filled the gap.
+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 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.23.0 → mostlyright_data-0.25.0}/skills/mr-data-build/references/reference-pages.md

@@ -24,8 +24,9 @@ https://mostlyright.md/docs/recipes/ lists all thirteen: `city-temperatures`, `c
 CSV file, one table), `json-api` (records pointer and pagination), `html-collection` (many HTML
 pages, one table), `document-extraction` (PDF projection), `weather-grib` (GRIB2 and the scientific
 Readers), `websocket-stream` (a `wss://` venue), `multi-source-join` (two sources joined, with
-checks), `market-settlement-join`, `forecast-vs-observation`, `snapshot-window` (a listing replaced
-on refresh), `many-station-weather` (twenty station feeds unioned) and `stream-to-bars`.
+checks), `market-settlement-join`, `forecast-vs-observation`, `snapshot-window` (a point-in-time
+source whose normal refresh currently requires explicit resync), `many-station-weather` (twenty
+station feeds unioned) and `stream-to-bars`.
 
 The build guides run one per stage, at https://mostlyright.md/docs/build/NAME/ where NAME is
 `probe-sources`, `write-a-recipe`, `run-and-inspect`, `publish-and-refresh`, `credentials`,

{mostlyright_data-0.23.0 → mostlyright_data-0.25.0}/skills/mr-data-build/references/sources.md

@@ -20,15 +20,23 @@
 - Preserve event time, available time, acquisition time, source revision, and timezone. Do not use
   post-cutoff information in targets, labels, features, joins, or validation decisions.
 - When the question is **what changed over time**, or the table needs point-in-time features, and
-  the source answers only with the present, declare a `snapshot` window on that source: Studio's
-  worker stamps every row with the UTC day it acquired the source on and keeps one partition per
-  day. Compute a transition with
+  the source answers only with the present, a `snapshot` window expresses the intended future
+  daily partition model. It is not executable as normal refresh in this release: Studio returns
+  `RESYNC_REQUIRED` before acquisition. Explicit resync is full with no predecessor and replaces
+  the table with the current observation; it does not retain earlier days. Once the bounded
+  snapshot materializer ships, compute a transition with
   `lag(column) over (partition by <identity> order by <snapshot column>)` and keep
   the rows where the two are `is distinct from` each other. Never diff two sealed versions by hand;
   a version is not a date, and nothing outside the seal can be replayed.
 
 ### Authoring a collection source
 
+Current execution boundary: an initial full or explicit table resync may acquire a collection,
+but collection-only and mixed normal refreshes return `RESYNC_REQUIRED` before acquisition. An
+explicit resync is full, has no predecessor, and starts collection discovery from the beginning.
+The ledger continuation rules below describe historical receipts and a future bounded materializer,
+not a current normal-refresh action.
+
 A corpus published as an index plus many detail pages is **one** source through
 `public.https.collection@2.0.0`, not one source per page. Source count and publisher count are
 unaffected by how many pages sit behind it: 2,819 pages is one source, one publisher, one line on
@@ -79,17 +87,16 @@ column reaches the transform as `VARCHAR`; selecting `page_ordinal` bare while d
 `TIMESTAMP WITH TIME ZONE` and nothing else.
 
 **A listing that could not be read says so.** The coverage block carries `discovery_failure`:
-`null`, or the code and one sentence for the first listing request the run was refused. A refresh
-that already holds pages keeps every row and succeeds; a FIRST run whose listing is refused has
-nothing to continue from and fails with `COLLECTION_DISCOVERY_FAILED` rather than sealing an empty
-corpus. If a run reports zero discovered, read that member before concluding the publisher's index
-is empty.
+`null`, or the code and one sentence for the first listing request the run was refused. A full
+resync whose listing is refused has nothing to continue from and fails with
+`COLLECTION_DISCOVERY_FAILED` rather than sealing an empty corpus. If a run reports zero
+discovered, read that member before concluding the publisher's index is empty.
 
-**Expect the first run not to finish, and say so.** A run that spends its fetch budget still
-SUCCEEDS; its coverage block reports `complete: false` and names the budget that ended it. The
-next refresh continues from the ledger — new pages first, then failures oldest first, then
-revisits — and every row of a page this run did not fetch survives byte for byte. Report the
-shortfall as what it is, a backfill in progress, not as a failure and not as a complete corpus.
+**A partial full/resync result must be reported as partial.** A run that spends its fetch budget
+still SUCCEEDS; its coverage block reports `complete: false` and names the budget that ended it.
+Do not call that a backfill in progress: no current normal refresh can continue the ledger, and a
+later explicit resync starts discovery over. Report it as an incomplete corpus and either accept
+that limitation or revise the bounded recipe before another explicit resync.
 
 A page that disappears from the index deletes nothing. A page answering with different content
 replaces exactly its own rows, increments `page_revision`, and keeps the previous digest: that is

{mostlyright_data-0.23.0 → mostlyright_data-0.25.0}/src/mostlyright/data_harness/page_coverage.py

@@ -37,9 +37,9 @@ __all__ = [
 #: ``{"code", "detail"}`` of the first listing request this run could not read. It is stated
 #: because a discovery that failed and a corpus that is empty produce the same counts, and a
 #: reader with only the counts cannot tell an unreachable index from a publisher who has stopped
-#: publishing. A run that had nothing to continue from does not report it -- it fails, under
-#: ``COLLECTION_DISCOVERY_FAILED`` -- so a block carrying it is always a refresh that kept its
-#: rows.
+#: publishing. A full/resync run with no listing and no rows fails under
+#: ``COLLECTION_DISCOVERY_FAILED``. Historical refresh receipts may carry the member after keeping
+#: predecessor rows, but current collection refresh is refused before acquisition.
 PAGE_COVERAGE_FIELDS: tuple[str, ...] = (
     "discovered",
     "discovery_requests",
@@ -103,5 +103,5 @@ def page_coverage_sentence(block: Mapping[str, Any]) -> str:
         parts.append(f"the page listing could not be read ({listing['code']})")
     if failed:
         parts.append(f"{failed:,} failed")
-    parts.append("continues on the next refresh")
+    parts.append("requires another explicit resync, which starts from the beginning")
     return "; ".join(parts)