mostlyright-data 0.25.4__tar.gz → 0.25.6__tar.gz

{mostlyright_data-0.25.4 → mostlyright_data-0.25.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.25.4
+Version: 0.25.6
 Summary: Mostly Right hosted CLI for reviewed datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/
@@ -82,6 +82,17 @@ mr-data checks RUN_ID
 mr-data download RUN_ID --output ./out
 ```
 
+Full builds are progressive by default: one acquisition exposes an inspection checkpoint after
+about five minutes and continues toward the finished table. Inspect it with
+`mr-data status RUN_ID --inspection --json`; the checkpoint does not pause for approval or start
+another full acquisition. Any required spend confirmation happens before acquisition.
+When a run has sealed queryable table checkpoints, `mr-data status RUN_ID --checkpoints --json`
+lists their exact immutable identifiers and `mr-data query RUN_ID "SELECT …" --checkpoint
+CHECKPOINT_ID` reads one without advancing underneath the query. These workspace-private snapshots
+remain incomplete, keep checks pending, and never become the serving table.
+`--progressive` remains a compatibility alias. Use `--sample` only for an explicit standalone
+bounded inspection; row ceilings do not impose a five-minute acquisition limit.
+
 Run submission is idempotent: sending identical recipe, mode and bounds returns the same run,
 including a previous failure. The CLI reports a non-queued result as `run_returned` and exits
 with code 2 when that run failed. Read its failure before retrying; `mr-data run --retry RUN_ID`
@@ -94,9 +105,9 @@ falls back to a mutable whole-source fetch. `mr-data table resync TABLE_ID --req
 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,
+the run, projection and exact `mr-data run --confirm-held RUN_ID` action. New full resyncs use
+progressive acquisition too. Existing legacy sample-first pairs can still finish through their
+original confirmation and approval actions. `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.

{mostlyright_data-0.25.4 → mostlyright_data-0.25.6}/README.md

@@ -70,6 +70,17 @@ mr-data checks RUN_ID
 mr-data download RUN_ID --output ./out
 ```
 
+Full builds are progressive by default: one acquisition exposes an inspection checkpoint after
+about five minutes and continues toward the finished table. Inspect it with
+`mr-data status RUN_ID --inspection --json`; the checkpoint does not pause for approval or start
+another full acquisition. Any required spend confirmation happens before acquisition.
+When a run has sealed queryable table checkpoints, `mr-data status RUN_ID --checkpoints --json`
+lists their exact immutable identifiers and `mr-data query RUN_ID "SELECT …" --checkpoint
+CHECKPOINT_ID` reads one without advancing underneath the query. These workspace-private snapshots
+remain incomplete, keep checks pending, and never become the serving table.
+`--progressive` remains a compatibility alias. Use `--sample` only for an explicit standalone
+bounded inspection; row ceilings do not impose a five-minute acquisition limit.
+
 Run submission is idempotent: sending identical recipe, mode and bounds returns the same run,
 including a previous failure. The CLI reports a non-queued result as `run_returned` and exits
 with code 2 when that run failed. Read its failure before retrying; `mr-data run --retry RUN_ID`
@@ -82,9 +93,9 @@ falls back to a mutable whole-source fetch. `mr-data table resync TABLE_ID --req
 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,
+the run, projection and exact `mr-data run --confirm-held RUN_ID` action. New full resyncs use
+progressive acquisition too. Existing legacy sample-first pairs can still finish through their
+original confirmation and approval actions. `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.

{mostlyright_data-0.25.4 → mostlyright_data-0.25.6}/pyproject.toml

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

{mostlyright_data-0.25.4 → mostlyright_data-0.25.6}/skills/mr-data-build/SKILL.md

@@ -62,13 +62,16 @@ references. Load the reference for the current stage only, not the entire librar
    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.
+   Use `--full` for the requested build: it is progressive by default, with a five-minute
+   inspection checkpoint while the same acquisition continues. Choose bounds from measured
+   source size; row and byte clamps apply per source, not elapsed time. Use explicit `--sample`
+   only for a deliberate standalone inspection. Preserve the agreed semantics and quality checks.
 7. Follow the returned run with `mr-data watch RUN_ID --json`. Read `run.status`: returning an
    existing run does not mean new work was queued. Resume the known run after an interruption,
    using the saved cursor where available. Read [run lifecycle](references/live-run.md) for
-   holds and continuation commands. Spend confirmation and releasing a held full are distinct
-   actions. Honor the user's authorization; do not request an existing delegation again. Send a
+   holds and continuation commands. Confirm projected spend before acquisition when required;
+   the progressive checkpoint needs no approval or second full run. Honor the user's
+   authorization; do not request an existing delegation again. Send a
    concise chat update for each newly observed meaningful lifecycle transition: accepted or
    queued, released after confirmation, started, failed, retried or replaced, completed, and
    verified. Include the run ID so the user can tell attempts apart; state the supported failure

{mostlyright_data-0.25.4 → mostlyright_data-0.25.6}/skills/mr-data-build/references/3-probe-read-a-source-before-committing-to-it.md

@@ -86,22 +86,22 @@ happens AFTER stage 2's answers arrive — or at once under a delegation. What c
 wait is research that submits nothing: documentation, publisher comparison, catalog.
 
 ```sh
-mr-data run --recipe RECIPE_ID --digest RECIPE_DIGEST --sample --max-rows 400000 --json
+mr-data run --recipe RECIPE_ID --digest RECIPE_DIGEST --full --json
+mr-data status RUN --inspection --json  # inspect while the same full acquisition continues
 mr-data peek RUN --json      # the columns and types the run sealed
 mr-data query RUN "select count(*) from run_table" --json
 mr-data receipt RUN --json   # what was fetched and what those bytes hashed to
 ```
 
-**Size it to measure rather than to sip.** A ceiling under the real size reports the ceiling back
-rather than the source: every larger feed comes back at exactly that number with `truncated` true,
-and a stage-6 ceiling set above THAT is a number this run invented. Set it high enough that the
-feeds come back whole, then keep the row counts off `coverage` — a source still truncated here is
-a source nobody measured, the one reason stage 6 falls back to a preview.
+**Inspect the full build while it runs.** Its progressive checkpoint appears after about five
+minutes without stopping acquisition. Use an explicit `--sample` only for a deliberate standalone
+experiment: a row ceiling can truncate output after every collection page was fetched and does
+not promise a short acquisition. Never derive source size from a truncated sample's ceiling.
 
 **A reading run that came back whole IS the build, so stage 6 adopts it rather than repeating
 it.** Untruncated everywhere is the build, whichever stage started the run: keep this `run_id`.
-Nor is the ceiling above sneaked past anybody — this run meets the same spend confirmation and
-sample-first threshold as every other, so a large one is held rather than quietly spent.
+The run meets the ordinary spend confirmation before acquisition; its checkpoint requires no
+second approval or second full build.
 
 That is stages 5 through 7 run once to settle the shape. Where the deployment does answer a probe,
 keep its status, reason code and exit value internal and describe only what it settled.

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

@@ -5,28 +5,25 @@
 nothing here. Re-running the coordinate replays it; a different ceiling buys only another
 acquisition.
 
-**Otherwise the first run is the build, and is sized to be one.** Stage 3 opened these feeds and
-knows roughly how many rows each carries. Set the row ceiling comfortably above the LARGEST and
-every source is acquired whole: no artificial seams, every declared check meaningful, and
-`coverage.truncated` false on every entry — which makes this finished work rather than a shape
-test.
+**Otherwise start one progressive full build.** Use the registered recipe and measured bounds
+for the requested coverage. Every full run is progressive by default; agents do not choose
+between progressive and sample-first acquisition.
 
 ```sh
-mr-data run --recipe RECIPE_ID --digest RECIPE_DIGEST --sample --max-rows 400000 --json
+mr-data run --recipe RECIPE_ID --digest RECIPE_DIGEST --full --json
 ```
 
-`sample` is a machine word for the run MODE and is not what the run is called. When `truncated` is
-false on every coverage entry, this is **the build**: the table a full run would have sealed,
-already live, presented as the build at stage 9. Do not run it again in another mode to change the
-word on it — the record keeps `mode: sample` for ever either way, and what makes the table finished
-is its coverage. Where somebody reads that word off the page and asks, say so: the mode is how the
-run was bounded, and nothing was cut.
+After about five minutes, inspect `mr-data status RUN_ID --inspection --json` while the same
+acquisition continues. This checkpoint is read-only, not a second approval gate or a hard runtime
+limit. A short build can finish before a checkpoint is needed. Do not submit another full run
+after inspecting it. Required spend confirmation happens before acquisition. The older
+`--progressive` flag is accepted for compatibility but is unnecessary.
 
-**Two thousand rows is only for a source nobody measured.** Where stage 3 could not open a feed and
-its size is a guess, `--max-rows 2000` exercises every column, cast and declared check and comes
-back while the person who asked is still watching. A run bounded that way is a **preview**, not the
-build, and is presented as one: say which source stopped short and at which row — both are on
-`coverage` — what a full build would cover, and ask whether to run it.
+**A standalone sample is an explicit inspection choice.** Use `--sample --max-rows 2000` only
+when a separate bounded experiment is needed. Rows are clamped after acquisition, so a collection
+may still fetch every page and take longer than five minutes. For an already authorized full
+build, use the progressive checkpoint. A truncated sample is a preview: report its actual
+coverage and the full build's proposed coverage before requesting any missing authorization.
 
 > The preview stopped at 2,000 rows on `asos_observations`, which is the ceiling rather than the
 > end of the feed; the other three sources came back whole. The full build would cover 2000 to 2026
@@ -39,22 +36,19 @@ ask again: state the projection and run it. A narrower delegation does not autho
 mr-data run --recipe RECIPE_ID --digest RECIPE_DIGEST --full --json
 ```
 
-**A held full is released with one command.** Over the sample-first threshold Studio does not start
-the full: it starts a bounded preview and holds the linked full at `awaiting_sample_approval`. Read
-`sample_run_id` off that status, interrogate that preview as stage 7 says, and present it as one.
-Then, on the user's word or under a delegation:
+**Existing legacy pairs can finish.** New full runs never create a linked sample/full pair.
+If adopting a legacy full already at `awaiting_sample_approval`, read `sample_run_id`, verify
+that preview, and release the held full under the user's authorization:
 
 ```sh
 mr-data run --approve-full RUN_ID --json
 ```
 
 `RUN_ID` may be either half of the pair: the held full, or the preview, whose `full_run_id` this
-command follows. It reads the run for its version and releases it under that version, so a pair
-that moved is refused rather than released against a record you did not read. **A deployment that
-still wants a person at a browser answers `THIN_INTERACTIVE_HUMAN_REQUIRED`, and today that is the
-usual answer** — Studio's own change is what makes it succeed. That is a typed refusal with a human
-fallback, never a crash: say the release needs them on the run page, give them the address the
-refusal names, and stop. Do not offer `--confirm`; it cannot settle this state.
+command follows. It releases under the version read. If a deployment returns
+`THIN_INTERACTIVE_HUMAN_REQUIRED`, report its named browser action. Do not offer `--confirm`;
+it cannot settle this legacy state. An existing untruncated sample that already satisfies the
+brief remains the completed build; never acquire it again merely to change its mode label.
 
 A stated `--window` may be refused before acquisition; report the typed code it answers with
 rather than retrying the same run in another mode.
@@ -84,6 +78,12 @@ attempt. Do not repeat either update while polling the same state.
 mr-data run --retry RUN_ID --json
 ```
 
+  For a failed progressive full, this also names the failed run as the capture ancestor, letting
+  Studio reuse compatible sealed pages. For a cancelled progressive full, or a failure outside
+  the supported room-fault retry set, start an authorized replacement with
+  `--full --resume-capture-run-id RUN_ID` and the registered recipe and digest. Legacy full runs
+  do not provide progressive captures.
+
   It re-states that run's own recipe, digest, mode and ceilings under one byte ceiling above what
   the recipe declares, because Studio replays a terminal result for an identical command and the
   coordinate has to move — and the number that ceiling must clear is what the run is projected to

{mostlyright_data-0.25.4 → mostlyright_data-0.25.6}/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 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 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 an existing legacy sample-first pair is holding once its preview has succeeded, naming either half of the pair; where the deployment still wants a person at a browser it answers `THIN_INTERACTIVE_HUMAN_REQUIRED` and names the run page. `--retry RUN_ID` tries one failed run again when its triple carries `room_fault: true`, re-stating that run's own coordinate under a byte ceiling that cannot narrow it, and refuses with the triple when the recipe was at fault. `--cancel RUN` stops one. |
 | `mr-data status` | Report which of the seven states one run is in, what it delivered and whether a ceiling cut it short, and — on a failure — what failed, where, and whether the fault was the execution room's rather than the recipe's. Exits non-zero on a failed run. |
 | `mr-data runs` | Report this workspace's own runs: identifier, mode, state and creation time, plus the failure triple of any that failed and whether that failure was the execution room's. `--status` and `--mode` narrow it and are refused `THIN_ARGUMENT_INVALID` for a word outside the seven states or the six modes; `--limit` says how many, and pages are followed to reach it. A narrow filter over a workspace of thousands of runs reads a long way to find its matches, and a listing that does not end says how many were read and suggests a smaller `--limit`. |
 | `mr-data 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. |
@@ -38,14 +38,14 @@ 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. |
 
-For a large full build on a deployment that serves progressive runs, add `--progressive` to
-`mr-data run --mode full`. Studio admits one full run and keeps acquisition moving while the
+Every `mr-data run --full` or `--mode full` build is progressive by default. The old
+`--progressive` flag remains a compatibility alias. Studio admits one full run and keeps acquisition moving while the
 owner inspects its five-minute checkpoint. A spend confirmation, when required, still comes
 before acquisition. Read `mr-data status RUN_ID --inspection --json` for the declared columns,
 missing-data policy, every source's bounded progress, and any observed table evidence. Source
 relation rows are not finished table rows; unknown transformed values remain null. A failed or
 cancelled progressive run may be followed by a new
-`--progressive --mode full --resume-capture-run-id RUN_ID` request under a registered compatible
+`--mode full --resume-capture-run-id RUN_ID` request under a registered compatible
 recipe. Studio decides which sealed captures can be reused. Keep the returned new run ID and
 verify its final receipt.
 
@@ -64,8 +64,8 @@ must agree on materialization and partition layout. Closed-only, any plan carryi
 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.
+prints `mr-data run --confirm-held RUN_ID` for that exact run. New full resyncs are progressive;
+an existing legacy sample-first resync still uses `--approve-full` after its preview succeeds.
 
 **`--refresh` states its own range, and a run that starts one by hand must pass it.** `mr-data run
 --refresh` sends what it is given. A refresh of a recipe carrying a non-snapshot request window

{mostlyright_data-0.25.4 → mostlyright_data-0.25.6}/skills/mr-data-build/references/live-run.md

@@ -50,14 +50,22 @@ what it proved, and a run that emitted none produces the same build as one that
 them. Never turn a progress count into a percentage, never infer activity from elapsed time, and
 never cite a progress event where a receipt is what was asked for.
 
-**Seven states, one machine.** A run is `queued`, `running`, `awaiting_confirmation`,
+**Full builds are progressive.** `--full` and `--mode full` acquire once and expose a checkpoint
+after about five minutes while that same run continues. Read it with
+`mr-data status RUN_ID --inspection --json`. It is an inspection point, not a five-minute hard
+timeout or an approval gate. Do not submit another full run after inspecting it. A short build
+can finish before a checkpoint is needed. `--sample` remains an explicit standalone bounded run;
+its row ceiling does not bound acquisition time.
+
+**Seven states, including legacy holds.** A run is `queued`, `running`, `awaiting_confirmation`,
 `awaiting_sample_approval`, `succeeded`, `failed` or `cancelled`; three are terminal and end a
 watch. `awaiting_confirmation` is the ordinary spend gate: nothing has been executed, and the same
 run command with `--confirm` on the end of it releases it. `awaiting_sample_approval` is the held
-full of a sample-first pair: its bounded preview must seal a downloadable table first, and then
+full of an existing legacy sample-first pair: its bounded preview must seal a downloadable table
+first, and then
 `mr-data run --approve-full RUN_ID` releases it — `--confirm` cannot, and must never be offered as
-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.
+though it could. New full builds never create these pairs. 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

{mostlyright_data-0.25.4 → mostlyright_data-0.25.6}/src/mostlyright/data_harness/thin/v4.py

@@ -119,8 +119,8 @@ from mostlyright.data_harness.thin.transport import ThinLaneError
 #: ``JOB_INVALID`` outright, which in production was every refresh a collection epoch was offered
 #: for rather than only the collection runs. This package must not reach a Studio older than the
 #: commit it pins; ``docs/V4-WORKER-PROTOCOL.md`` states it beside the layout's own ordering rule.
-PINNED_V4_OPENAPI_SOURCE_SHA256 = "0cfa1dda766dfc8861286a3cf8bfa5a86cd71d396f49b134882a6e8c95e9ca50"
-PINNED_V4_CONTRACT_VERSION = "4.10.1"
+PINNED_V4_OPENAPI_SOURCE_SHA256 = "2f4e1f566bfd788ba1f9981d8b214c62e43294320da87167ced462a527abe848"
+PINNED_V4_CONTRACT_VERSION = "4.12.0"
 
 # --------------------------------------------------------------------------------------------
 # The routes
@@ -215,6 +215,14 @@ RUN_PROGRESS_PATH = "/v4/runs/{run_id}/progress"
 #: ``GET`` -- declared shape and bounded observed evidence for a progressive full run.
 RUN_INSPECTION_PATH = "/v4/runs/{run_id}/inspection"
 
+#: ``GET`` -- the bounded list of immutable, workspace-private snapshots this run has sealed.
+RUN_CHECKPOINTS_PATH = "/v4/runs/{run_id}/checkpoints"
+
+#: ``GET`` -- one exact immutable build checkpoint. ``POST :resolve`` on the same path belongs to
+#: Cloud's query executor; the thin client queries through the ordinary run query route instead
+#: of receiving artifact storage coordinates.
+RUN_CHECKPOINT_PATH = "/v4/runs/{run_id}/checkpoints/{checkpoint_id}"
+
 # Reader recovery uses Studio's versioned authority. These routes deliberately live beside the
 # other V4 wire constants so a client cannot silently turn transport canonicalisation into reader
 # validation.
@@ -603,6 +611,8 @@ DECLARED_V4_PATHS: frozenset[str] = frozenset(
         RUN_EVENTS_PATH,
         RUN_PROGRESS_PATH,
         RUN_INSPECTION_PATH,
+        RUN_CHECKPOINTS_PATH,
+        RUN_CHECKPOINT_PATH,
         # ⚠ PROMOTED OUT OF `PENDING_V4_PATHS` IN THE COMMIT THAT STARTED CALLING THEM. Studio
         # shipped the whole promotion surface while this client was being written against the
         # contract for it, and the ledger in `tests/test_thin_v4_contract.py` went red naming all
@@ -944,6 +954,8 @@ __all__ = [
     "RESCHEDULE_TABLE_PATH",
     "RESYNC_TABLE_PATH",
     "RUN_ARTIFACTS_PATH",
+    "RUN_CHECKPOINTS_PATH",
+    "RUN_CHECKPOINT_PATH",
     "RUN_EVENTS_PATH",
     "RUN_INSPECTION_PATH",
     "RUN_PROGRESS_PATH",

{mostlyright_data-0.25.4 → mostlyright_data-0.25.6}/src/mostlyright/data_harness/thin/v4_query.py

@@ -38,6 +38,7 @@ hop later.
 from __future__ import annotations
 
 import argparse
+import re
 import time
 from collections.abc import Callable, Mapping
 from typing import Any
@@ -114,6 +115,8 @@ MASKED_SCAN_WARNING = (
     'export is refused; writing that identifier in "double quotes" puts it outside the scan'
 )
 
+_CONTENT_DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")
+
 #: The four refusals that happen BEFORE anything is queued, and the fifth that bounds the body,
 #: each with the sentence this command adds to Studio's own message. Keyed by Studio's code, which
 #: is what ``thin.runs._studio_refusal`` carries through verbatim as ``THIN_STUDIO_{code}``.
@@ -199,7 +202,8 @@ class StudioV4QueryClient(StudioV4Client):
         """Queue one bounded read. ``202`` on a new query AND on a repeat of an identical one.
 
         ⚠ ``202`` IS THE ONLY ACCEPTED STATUS, and a repeat is not a second status. Studio derives
-        the identifier from the digest of the canonical ``{sql, max_rows}`` command, so two
+        the identifier from the digest of the canonical command, including its immutable
+        checkpoint coordinate when present, so two
         identical submits converge on one query and the second answers ``202`` again with
         ``Idempotent-Replay: true``. Reading the header is what lets this command say which of the
         two happened; treating the replay as a fresh execution would tell an agent it had spent
@@ -295,7 +299,9 @@ def declare_arguments(parser: argparse.ArgumentParser) -> None:
         f"for at most {int(MAX_QUERY_WAIT_SECONDS)} seconds, whichever comes first -- it is never "
         "a long poll. A wait that ends first leaves the question running and prints its "
         "identifier; running the same command again reads that same one back, because the "
-        "identifier is derived from the statement, the row limit and the prune block. "
+        "identifier is derived from the statement, the row limit, the prune block and the "
+        "optional checkpoint. A checkpoint is already one exact immutable snapshot, so it "
+        "cannot be combined with --field, --from, --to or --partition. "
         "A table version is many Parquet parts and a bounded read may open only so many of "
         "them, so a question about a wide table is narrowed with --field plus --from/--to, or "
         "with --partition; Studio evaluates that against the part list before a worker is woken, "
@@ -317,6 +323,13 @@ def declare_arguments(parser: argparse.ArgumentParser) -> None:
         help="stop at this many rows; left out, the server's own ceiling applies. A number above "
         "that ceiling is refused rather than lowered",
     )
+    parser.add_argument(
+        "--checkpoint",
+        metavar="CHECKPOINT_ID",
+        help="ask one immutable build checkpoint instead of the run's final table. The result "
+        "stays bound to this exact checkpoint while newer build data arrives; it cannot be "
+        "combined with --field, --from, --to or --partition",
+    )
     parser.add_argument(
         "--field",
         help="which field --from and --to are about, by column name. Without --from or --to it "
@@ -369,10 +382,10 @@ def _client(args: argparse.Namespace) -> StudioV4QueryClient:
 def submit_body(args: argparse.Namespace) -> dict[str, Any]:
     """The ``submit_query_command`` this invocation means, checked before anything is sent.
 
-    Two members, because Studio decides everything else: the run names the table, the bearer names
-    the workspace, and the deadline is deployment policy. ``max_rows`` is left OUT rather than sent
-    as ``null`` when the caller states none -- "as many as the server allows" is a member absent,
-    and a null would be refused by a command schema that admits two properties and no nulls.
+    The run names the table, the bearer names the workspace, and the deadline is deployment
+    policy. ``max_rows`` and ``checkpoint_id`` are left OUT rather than sent as ``null`` when the
+    caller states none. An absent checkpoint asks the final run table; an exact checkpoint keeps
+    the answer stable while later build data arrives.
     """
 
     statement = str(getattr(args, "sql", "") or "")
@@ -382,7 +395,16 @@ def submit_body(args: argparse.Namespace) -> dict[str, Any]:
             'mr-data query needs the question to ask: mr-data query RUN "SELECT ..."',
         )
     body: dict[str, Any] = {"sql": statement}
+    checkpoint = getattr(args, "checkpoint", None)
+    if checkpoint is not None:
+        body["checkpoint_id"] = identifier(str(checkpoint), "checkpoint identifier")
     prune = _prune(args)
+    if checkpoint is not None and prune:
+        raise ThinLaneError(
+            "THIN_REQUEST_INVALID",
+            "--checkpoint already names one exact immutable snapshot and cannot be combined "
+            "with --field, --from, --to or --partition",
+        )
     if prune:
         body["prune"] = prune
     max_rows = getattr(args, "max_rows", None)
@@ -464,6 +486,40 @@ def _record_identifier(record: Mapping[str, Any], run_id: str) -> str:
     return query_id
 
 
+def _checkpoint_binding(
+    record: Mapping[str, Any],
+    checkpoint_id: str | None,
+    checkpoint_content_digest: str | None = None,
+) -> str | None:
+    """Validate the immutable coordinate on every submit and poll response."""
+
+    actual_id = record.get("checkpoint_id")
+    actual_digest = record.get("checkpoint_content_digest")
+    if checkpoint_id is None:
+        if actual_id is not None or actual_digest is not None:
+            raise ThinLaneError(
+                "THIN_RESPONSE_INVALID",
+                "Studio bound a final-table query to an unexpected build checkpoint",
+            )
+        return None
+    if actual_id != checkpoint_id:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID",
+            "Studio answered with a query bound to another or no build checkpoint",
+        )
+    if not isinstance(actual_digest, str) or _CONTENT_DIGEST.fullmatch(actual_digest) is None:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID",
+            "Studio answered a checkpoint query without its sealed content digest",
+        )
+    if checkpoint_content_digest is not None and actual_digest != checkpoint_content_digest:
+        raise ThinLaneError(
+            "THIN_RESPONSE_INVALID",
+            "Studio changed the checkpoint content digest while the query was running",
+        )
+    return actual_digest
+
+
 def _named_refusal(refusal: ThinLaneError) -> ThinLaneError:
     """One pre-queue refusal, with the sentence this command adds and the ``details`` it carries.
 
@@ -547,6 +603,8 @@ def _answer(record: Mapping[str, Any]) -> dict[str, Any]:
         "state": record.get("state"),
         "sql": record.get("sql"),
         "max_rows": record.get("max_rows"),
+        "checkpoint_id": record.get("checkpoint_id"),
+        "checkpoint_content_digest": record.get("checkpoint_content_digest"),
         # How much of the table this answer is an answer about. Studio records it because a
         # caller who pruned should be able to see that a one-day window read two parts rather
         # than be told to trust that it did.
@@ -606,7 +664,16 @@ def query(
                 again.retry_after_seconds = window  # type: ignore[attr-defined]
             raise _named_refusal(again) from None
     try:
-        payload = _settled(selected, args, run_id, record, headers, sleep=sleep, clock=clock)
+        payload = _settled(
+            selected,
+            args,
+            run_id,
+            record,
+            headers,
+            checkpoint_id=body.get("checkpoint_id"),
+            sleep=sleep,
+            clock=clock,
+        )
     finally:
         closed = warm.close() if warm is not None else None
     if warm is not None:
@@ -625,6 +692,7 @@ def _settled(
     record: Mapping[str, Any],
     headers: Mapping[str, str],
     *,
+    checkpoint_id: str | None,
     sleep: Callable[[float], None],
     clock: Callable[[], float],
 ) -> dict[str, Any]:
@@ -636,7 +704,16 @@ def _settled(
         or str(headers.get(IDEMPOTENT_REPLAY_HEADER.lower(), "")).lower() == "true"
     )
     query_id = _record_identifier(record, run_id)
-    record, read = _poll(selected, run_id, query_id, sleep=sleep, clock=clock)
+    checkpoint_content_digest = _checkpoint_binding(record, checkpoint_id)
+    record, read = _poll(
+        selected,
+        run_id,
+        query_id,
+        checkpoint_id=checkpoint_id,
+        checkpoint_content_digest=checkpoint_content_digest,
+        sleep=sleep,
+        clock=clock,
+    )
     head: dict[str, Any] = {
         "schema_version": QUERY_SCHEMA,
         "lane": "hosted",
@@ -656,12 +733,15 @@ def _settled(
             "state": state,
             "sql": record.get("sql"),
             "max_rows": record.get("max_rows"),
+            "checkpoint_id": record.get("checkpoint_id"),
+            "checkpoint_content_digest": record.get("checkpoint_content_digest"),
             "deadline_at": record.get("deadline_at"),
             "note": (
                 f"This command read the answer back {read} times and it is still {state}. The "
                 "query is unaffected: Studio terminalizes it at its own deadline above, and "
                 "running this same command again reads it back rather than executing a second, "
-                "because the identifier is derived from the statement and the row limit."
+                "because the identifier is derived from the statement, row limit, pruning and "
+                "checkpoint."
             ),
         }
     payload: dict[str, Any] = {**head, "status": "query_answered", **_answer(record)}
@@ -673,8 +753,8 @@ def _settled(
         )
     if replayed:
         notes.append(
-            "This statement and row limit had already been asked of this run, so Studio answered "
-            "with that one query rather than executing a second."
+            "This statement, row limit, pruning and checkpoint had already been asked of this "
+            "run, so Studio answered with that one query rather than executing a second."
         )
     if notes:
         payload["note"] = " ".join(notes)
@@ -763,6 +843,8 @@ def _poll(
     run_id: str,
     query_id: str,
     *,
+    checkpoint_id: str | None,
+    checkpoint_content_digest: str | None,
     sleep: Callable[[float], None],
     clock: Callable[[], float],
 ) -> tuple[dict[str, Any], int]:
@@ -791,6 +873,7 @@ def _poll(
             raise ThinLaneError(
                 "THIN_RESPONSE_INVALID", "Studio answered with a query belonging to another run"
             )
+        _checkpoint_binding(record, checkpoint_id, checkpoint_content_digest)
         if record.get("state") in TERMINAL_QUERY_STATES:
             break
     return record, read

{mostlyright_data-0.25.4 → mostlyright_data-0.25.6}/src/mostlyright/data_harness/thin/v4_runs.py

@@ -47,6 +47,8 @@ from mostlyright.data_harness.thin.v4 import (
     CREATE_RUN_PATH,
     GET_RUN_PATH,
     LIST_RUNS_PATH,
+    RUN_CHECKPOINT_PATH,
+    RUN_CHECKPOINTS_PATH,
     RUN_INSPECTION_PATH,
     bare_digest,
     identifier,
@@ -277,6 +279,45 @@ class StudioV4RunClient(StudioV4NarrativeClient):
             raise ThinLaneError("THIN_RESPONSE_INVALID", "Studio returned another run's inspection")
         return answer
 
+    def checkpoints(self, run_id: str) -> dict[str, Any]:
+        """Read the bounded discoverable checkpoint list for one run."""
+
+        answer = self._call("GET", RUN_CHECKPOINTS_PATH.format(run_id=run_id), expected=(200,))
+        if answer.get("schema_version") != "mostlyright-run-checkpoint.v1":
+            raise ThinLaneError(
+                "THIN_RESPONSE_INVALID", "Studio returned an invalid run checkpoint list"
+            )
+        rows = answer.get("checkpoints")
+        if answer.get("run_id") != run_id or not isinstance(rows, list):
+            raise ThinLaneError(
+                "THIN_RESPONSE_INVALID", "Studio returned another run's checkpoint list"
+            )
+        if any(
+            not isinstance(row, Mapping)
+            or row.get("schema_version") != "mostlyright-run-checkpoint.v1"
+            or row.get("run_id") != run_id
+            or not isinstance(row.get("checkpoint_id"), str)
+            for row in rows
+        ):
+            raise ThinLaneError(
+                "THIN_RESPONSE_INVALID", "Studio returned an invalid checkpoint in the run list"
+            )
+        return answer
+
+    def checkpoint(self, run_id: str, checkpoint_id: str) -> dict[str, Any]:
+        """Read one exact immutable checkpoint without resolving its artifact bytes."""
+
+        answer = self._call(
+            "GET",
+            RUN_CHECKPOINT_PATH.format(run_id=run_id, checkpoint_id=checkpoint_id),
+            expected=(200,),
+        )
+        if answer.get("schema_version") != "mostlyright-run-checkpoint.v1":
+            raise ThinLaneError("THIN_RESPONSE_INVALID", "Studio returned an invalid checkpoint")
+        if answer.get("run_id") != run_id or answer.get("checkpoint_id") != checkpoint_id:
+            raise ThinLaneError("THIN_RESPONSE_INVALID", "Studio returned another checkpoint")
+        return answer
+
     def runs(
         self,
         *,
@@ -400,8 +441,8 @@ def declare_run_arguments(parser: argparse.ArgumentParser) -> None:
         dest="mode",
         action="store_const",
         const="full",
-        help="build the whole dataset; over the projection threshold Studio holds it for your "
-        "confirmation, and above the sample-first threshold it holds it for a bounded preview",
+        help="build the whole dataset progressively; inspect its five-minute checkpoint while "
+        "acquisition continues, with spend confirmation before acquisition when required",
     )
     mode.add_argument(
         "--refresh",
@@ -445,7 +486,7 @@ def declare_run_arguments(parser: argparse.ArgumentParser) -> None:
     parser.add_argument(
         "--progressive",
         action="store_true",
-        help="start a full acquisition with a five-minute inspection checkpoint while it continues",
+        help="compatibility alias: every full run already uses progressive acquisition",
     )
     parser.add_argument(
         "--resume-capture-run-id",
@@ -481,7 +522,7 @@ def declare_run_arguments(parser: argparse.ArgumentParser) -> None:
         "--approve-full",
         dest="approve_full",
         metavar="RUN_ID",
-        help="release the full run a sample-first pair is holding, once its preview has "
+        help="release an existing legacy sample-first full run, once its preview has "
         "succeeded; names the held full or the preview it is linked to",
     )
 
@@ -495,6 +536,17 @@ def declare_status_arguments(parser: argparse.ArgumentParser) -> None:
         action="store_true",
         help="include the run's declared shape and observed checkpoint",
     )
+    selected = parser.add_mutually_exclusive_group()
+    selected.add_argument(
+        "--checkpoints",
+        action="store_true",
+        help="include the bounded list of immutable workspace build checkpoints",
+    )
+    selected.add_argument(
+        "--checkpoint",
+        metavar="CHECKPOINT_ID",
+        help="include one exact immutable build checkpoint",
+    )
     parser.add_argument("--receipts", action="store_true", help=_NO_EFFECT_RECEIPTS)
 
 
@@ -683,14 +735,12 @@ def create_run_body(args: argparse.Namespace) -> dict[str, Any]:
             "state --mode replay or drop the flag",
         )
     resource_class = getattr(args, "resource_class", None)
-    progressive = bool(getattr(args, "progressive", False))
+    progressive_requested = bool(getattr(args, "progressive", False))
     resume_capture_run_id = getattr(args, "resume_capture_run_id", None)
-    if progressive and mode != "full":
+    if progressive_requested and mode != "full":
         raise ThinLaneError(ARGUMENT_INVALID_CODE, "--progressive requires --full")
-    if resume_capture_run_id and not progressive:
-        raise ThinLaneError(
-            ARGUMENT_INVALID_CODE, "--resume-capture-run-id requires --progressive --full"
-        )
+    if resume_capture_run_id and mode != "full":
+        raise ThinLaneError(ARGUMENT_INVALID_CODE, "--resume-capture-run-id requires --full")
     clamps = _clamps(args)
     if mode == "sample" and not clamps:
         raise ThinLaneError(
@@ -721,7 +771,7 @@ def create_run_body(args: argparse.Namespace) -> dict[str, Any]:
         body["clamps"] = clamps
     if resource_class:
         body["resource_class"] = resource_class
-    if progressive:
+    if mode == "full":
         body["progressive"] = True
     if resume_capture_run_id:
         body["resume_capture_run_id"] = identifier(
@@ -1067,6 +1117,10 @@ def retry_body(run: Mapping[str, Any], run_id: str, *, declared_bytes: int = 0)
             )
         body[member] = stated
     body["clamps"] = retry_clamps(run, declared_bytes=declared_bytes)
+    if body["mode"] == "full":
+        body["progressive"] = True
+        if run.get("progressive") is True:
+            body["resume_capture_run_id"] = identifier(run_id, "capture ancestor run identifier")
     resource_class = run.get("resource_class")
     if isinstance(resource_class, str) and resource_class:
         body["resource_class"] = resource_class
@@ -1261,9 +1315,11 @@ def _retry_cell(
             f"Run {run_id} failed at the {triple['failed_stage']} stage with "
             f"{triple['failure_code']}: {triple['failure_detail']}\n\n"
             "That code is about the room the run landed in rather than about this recipe, so the "
-            "document is unchanged and this is the same command again. Its only difference is a "
-            "byte ceiling above anything the sources can deliver, which is what gives the attempt "
-            "a coordinate of its own; an identical command would have replayed the stored failure."
+            "document is unchanged. A byte ceiling above anything the sources can deliver gives "
+            "the attempt a coordinate of its own; an identical command would have replayed the "
+            "stored failure. Full retries use progressive acquisition. When the failed full was "
+            "already progressive, the retry also names it as the capture ancestor so Studio can "
+            "reuse compatible sealed pages."
         ),
         blocks=[
             {
@@ -1523,6 +1579,12 @@ def status(args: argparse.Namespace, *, client: StudioV4RunClient | None = None)
         payload["flags_without_effect"] = {"--receipts": _NO_EFFECT_RECEIPTS}
     if getattr(args, "inspection", False):
         payload["inspection"] = selected.inspection(run_id)
+    if getattr(args, "checkpoints", False):
+        payload["checkpoints"] = selected.checkpoints(run_id)
+    checkpoint = getattr(args, "checkpoint", None)
+    if checkpoint is not None:
+        checkpoint_id = identifier(str(checkpoint), "checkpoint identifier")
+        payload["checkpoint"] = selected.checkpoint(run_id, checkpoint_id)
     if state == "awaiting_confirmation":
         held = {member: run[member] for member in _PROJECTION_MEMBERS[1:] if member in run}
         if held:

{mostlyright_data-0.25.4 → mostlyright_data-0.25.6}/src/mostlyright/data_harness/thin/v4_tables.py

@@ -687,7 +687,8 @@ def declare_arguments(command: str, parser: argparse.ArgumentParser) -> None:
                 "it before submitting, then reuse it after a lost response to ask for the "
                 "same resync, not another one. If Studio persists it at the spend gate, the "
                 "receipt prints mr-data run --confirm-held RUN_ID for that exact run; a "
-                "sample-first receipt confirms its preview before its linked full can be released"
+                "legacy sample-first receipt confirms its preview before its linked full can "
+                "be released"
             ),
         )
         parser.add_argument(

{mostlyright_data-0.25.4 → mostlyright_data-0.25.6}/src/mostlyright/data_harness/thin/vocabulary.py

@@ -229,11 +229,14 @@ CLASSIFICATION: dict[str, Lane] = {
         HOSTED,
         "it starts one run of a registered recipe in one of the six protocol modes -- sample, "
         "full, refresh, backfill, compact or replay -- under the row and byte ceilings you give "
-        "it, and settles the spend confirmation a large one is held for. A replay names the "
+        "it, and settles the spend confirmation a large one is held for. Full builds are "
+        "progressive by default, with an inspection checkpoint during the same acquisition. "
+        "A replay names the "
         "retained raw inputs of one successful run of the same table with --sources-from, "
         "fetches nothing here and never becomes the live version. --retry names one failed run "
         "and tries it again when what failed was the room rather than the recipe, and "
-        "--approve-full releases the full a sample-first pair is holding once its preview has "
+        "--approve-full releases the full an existing legacy sample-first pair is holding "
+        "once its preview has "
         "succeeded; a deployment that still wants a person at a browser refuses that release by "
         "name and this command says where they settle it",
     ),