mostlyright-data 0.18.2__tar.gz → 0.19.0__tar.gz

mostlyright_data-0.19.0/.gitignore

@@ -0,0 +1,25 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.py[cod]
+dist/
+build/
+*.egg-info/
+.env
+.DS_Store
+.work/
+
+# A generator that stages a rewrite beside the file it is replacing and moves it into place
+# leaves nothing behind on success; if an interruption leaves one behind, it is not a source file
+# somebody should be offered the chance to commit. The Reader and operation table generator that
+# wrote these went to Studio with the registries it read.
+*.generated
+
+# The performance suite builds its fixture inside the repository root rather than in a temporary
+# directory, so an interrupted or parallel run leaves one of these behind. Nothing in one is a
+# source file: it is a generated build folder holding a hundred thousand rows of synthetic data,
+# under directories the build seals read-only, and `git add -A` in that window commits the lot.
+# Recorded as issue #311; ignored here so the window cannot cost anybody a rewritten branch in
+# the meantime.
+.mostlyright-performance-*/

mostlyright_data-0.19.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.4
+Name: mostlyright-data
+Version: 0.19.0
+Summary: Mostly Right hosted CLI for reviewed datasets
+Project-URL: Homepage, https://mostlyright.md/
+Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/
+Requires-Python: >=3.13
+Provides-Extra: build
+Requires-Dist: hatchling==1.28.0; extra == 'build'
+Requires-Dist: uv-build==0.11.3; extra == 'build'
+Description-Content-Type: text/markdown
+
+# mostlyright-data
+
+Browse datasets built by our community or create your own with agents that find the sources and
+configure the pipeline. Mostly Right treats a successful run as one readable dataset version;
+publishing that version does not by itself prove that catch-up or scheduled refresh is running.
+
+`mostlyright-data` is the command-line client. It probes sources, registers one recipe document,
+starts and follows hosted dataset runs, reads what they delivered, and downloads the datasets after
+they finish.
+
+## Requirements
+
+Use CPython 3.13 or newer.
+
+## Install
+
+```bash
+python -m pip install mostlyright-data
+```
+
+That is the whole install. There is no second profile and no lane to choose: every `mr-data`
+command sends its work to the backend, and it works on Linux, macOS, and Windows.
+
+It also carries the `mr-data-build` agent skill, which Claude Code and Codex read to author a
+recipe without rediscovering the contract a run at a time. The first `mr-data` command you run
+places it in your agent's skill directory; there is nothing to install by hand. A skill you have
+edited yourself is never replaced, and `MOSTLYRIGHT_SKILL_AUTOINSTALL=0` switches the placement
+off.
+
+## Sign in
+
+```bash
+mr-data login
+mr-data whoami
+```
+
+`login` stores a device key on the current machine. `whoami` checks that key.
+
+## Check the installation
+
+```bash
+mr-data --version
+mr-data --help
+```
+
+## Build a dataset
+
+Create the dataset, choose its primary category from the fixed vocabulary, then register a recipe document with the sources, table schema, transformations and checks. Use the created dataset ID in the recipe:
+
+```bash
+mr-data dataset create --name "Dataset title" --json
+mr-data dataset categories --json
+mr-data dataset set DATASET_ID --category climate-environment
+mr-data recipe recipe.json --json
+mr-data run --recipe RECIPE_ID --digest RECIPE_DIGEST --full
+mr-data status RUN_ID
+mr-data checks RUN_ID
+mr-data download RUN_ID --output ./out
+```
+
+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.
+
+To request an offline replay of retained inputs with a registered revision:
+
+```bash
+mr-data run --recipe RECIPE_ID --digest RECIPE_DIGEST --mode replay --sources-from RUN_ID
+```
+
+Studio must have replay enabled and the named successful run must belong to the same table with
+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.
+
+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
+TABLE_ID` records how often it refreshes and why, and puts back a table that was withdrawn. Claim
+a table is live and current only when Studio returns that evidence.
+
+## There is no local execution
+
+There used to be. A second product lane built datasets on your own machine, and `mr-data` carried
+about fifty commands for making, running, serving, indexing, checking and signing a build here.
+That lane is gone: the engine it ran now ships only inside the backend's worker images.
+
+`mr-data --help` lists every command this product has. The execution engine and its dependency
+closure live in Mostly Right Studio's `apps/worker`; this repository ships no engine extras,
+worker executables or image publisher.
+
+## Documentation
+
+- [CLI guide](https://mostlyright.md/docs/guides/cli/)
+- [Hosted research sessions](https://mostlyright.md/docs/guides/hosted-research/)
+- [Credentials](https://mostlyright.md/docs/guides/credentials/)
+- [Public datasets](https://mostlyright.md/docs/guides/use-public-datasets/)
+- [Certified document extraction](docs/DOCUMENT-EXTRACTION.md)
+
+Use `mr-data --help` for the full command list and options. Commands that support
+`--json` write one JSON object.
+
+`--output` may use a relative path.
+
+## Behavior and limits
+
+- Weather Reader versions 1 and 2 accept one extracted GRIB2 record and refuse a multi-record GFS
+  or HRRR file. Version 3 reads a bounded collection and selects exactly one sealed record.
+- A single-address credential-free public HTTPS source uses the reviewed hosted route. Bounded
+  collections have no route at all; the retired local lane was their only route.
+- A recipe supports up to 256 declared sources. Source count is separate from bounded request concurrency and resource limits. Existing source adapters and Readers retain their own format, pagination, byte, row and credential contracts; a URL collection is not an implicit permission to crawl arbitrary links.
+- A keyed stream venue is named by a credential reference the backend holds, never by a value. No command flag takes a secret as an argument. Venues reached over an actual WebSocket are covered; a venue whose credential comes from an interactive human login, or that is not WebSocket at all, is not.
+
+## Verification
+
+```bash
+make test
+```
+
+`make test` runs the thin client suite while editing. `make verify` is required
+before review or merge.
+
+## Development
+
+```bash
+uv sync --locked
+```
+
+There is no `dev` extra to ask for -- `uv run --extra dev` answers
+``error: Extra `dev` is not defined in the project's `optional-dependencies` table``. The test
+tooling is the default dependency group, which `uv sync` installs.
+
+`make lint` is the repository's one lint set (`uv run ruff check .` plus `uv lock --check`); it is
+the first thing `make verify` runs and the same target the Linux leg of `thin-client-smoke.yml`
+runs, so the two cannot disagree about what is linted.
+
+The test suite checks client behavior, contract compatibility and thin package ownership. Backend
+execution and worker-boundary tests run in Studio. The client supports Linux, macOS and Windows.
+
+To update the public Studio contract pin, run `make repin STUDIO_GIT=/path/to/studio STUDIO_REF=<commit>`. It reads committed OpenAPI and JSON Schema bytes, records their hashes and source commit in `vendor/studio-contracts/client-v4-pin.json`, and updates the thin client. Run the cross-repository tests against that Studio revision before release. Worker/client generation and backend job-contract repins now belong to Studio.

{mostlyright_data-0.18.2 → mostlyright_data-0.19.0}/README.md

@@ -10,7 +10,7 @@ they finish.
 
 ## Requirements
 
-Use CPython 3.13 or newer. The retired local execution lane (`[local,scientific]` extras) still needs 3.13.
+Use CPython 3.13 or newer.
 
 ## Install
 
@@ -61,6 +61,16 @@ mr-data download RUN_ID --output ./out
 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.
 
+To request an offline replay of retained inputs with a registered revision:
+
+```bash
+mr-data run --recipe RECIPE_ID --digest RECIPE_DIGEST --mode replay --sources-from RUN_ID
+```
+
+Studio must have replay enabled and the named successful run must belong to the same table with
+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
@@ -83,10 +93,9 @@ There used to be. A second product lane built datasets on your own machine, and
 about fifty commands for making, running, serving, indexing, checking and signing a build here.
 That lane is gone: the engine it ran now ships only inside the backend's worker images.
 
-`mr-data --help` lists every command this product has. A name that is not on it is not a command
-and says so. The distribution still publishes a `[local]` extra — that is the engine's dependency
-closure, which the backend's worker image installs — and installing it makes no command run that
-does not run without it.
+`mr-data --help` lists every command this product has. The execution engine and its dependency
+closure live in Mostly Right Studio's `apps/worker`; this repository ships no engine extras,
+worker executables or image publisher.
 
 ## Documentation
 
@@ -113,17 +122,27 @@ Use `mr-data --help` for the full command list and options. Commands that suppor
 ## Verification
 
 ```bash
-make test-fast
+make test
 ```
 
-`make test-fast` is non-authoritative and is useful while editing. `make verify` is required
+`make test` runs the thin client suite while editing. `make verify` is required
 before review or merge.
 
 ## Development
 
 ```bash
-uv sync --locked --extra dev --extra local-search-neural
+uv sync --locked
 ```
 
-The test suite drives the execution engine in-process, and requires Linux for the worker-boundary
-tests. The client itself is tested on Linux, macOS, and Windows.
+There is no `dev` extra to ask for -- `uv run --extra dev` answers
+``error: Extra `dev` is not defined in the project's `optional-dependencies` table``. The test
+tooling is the default dependency group, which `uv sync` installs.
+
+`make lint` is the repository's one lint set (`uv run ruff check .` plus `uv lock --check`); it is
+the first thing `make verify` runs and the same target the Linux leg of `thin-client-smoke.yml`
+runs, so the two cannot disagree about what is linted.
+
+The test suite checks client behavior, contract compatibility and thin package ownership. Backend
+execution and worker-boundary tests run in Studio. The client supports Linux, macOS and Windows.
+
+To update the public Studio contract pin, run `make repin STUDIO_GIT=/path/to/studio STUDIO_REF=<commit>`. It reads committed OpenAPI and JSON Schema bytes, records their hashes and source commit in `vendor/studio-contracts/client-v4-pin.json`, and updates the thin client. Run the cross-repository tests against that Studio revision before release. Worker/client generation and backend job-contract repins now belong to Studio.

mostlyright_data-0.19.0/pyproject.toml

@@ -0,0 +1,131 @@
+[project]
+name = "mostlyright-data"
+version = "0.19.0"
+description = "Mostly Right hosted CLI for reviewed datasets"
+readme = "README.md"
+requires-python = ">=3.13"
+# The published Harness package is a pure-Python, stdlib-only hosted client.  Dataset execution,
+# native readers, and worker publication live in Mostly Right Studio.
+dependencies = []
+
+[project.urls]
+Homepage = "https://mostlyright.md/"
+Documentation = "https://mostlyright.md/docs/guides/cli/"
+
+[project.scripts]
+mr-data = "mostlyright.data_harness.thin.router:main"
+
+[project.optional-dependencies]
+build = [
+    "hatchling==1.28.0",
+    "uv-build==0.11.3",
+]
+
+[dependency-groups]
+dev = [
+    "cmarkgfm>=2025.10.22",
+    "jsonschema[format]>=4.23,<5",
+    "pytest>=8.3",
+    "pytest-xdist>=3.6",
+    # Test-only, and only for `tests/test_thin_v4_contract.py`'s cross-check of its hand-written
+    # OpenAPI scan against a real parser.  It never enters the distribution, whose runtime
+    # dependency list is empty; the guard it unblocks was unreachable in every configuration
+    # while the extra that used to carry pyyaml no longer existed.
+    "pyyaml>=6.0",
+    "referencing>=0.35,<1",
+    "ruff>=0.9",
+]
+pypi-release = ["twine==6.2.0"]
+
+[build-system]
+requires = ["hatchling==1.28.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+sources = ["src"]
+only-include = [
+    "src/mostlyright/data_harness/__init__.py",
+    "src/mostlyright/data_harness/canonical.py",
+    "src/mostlyright/data_harness/formats.py",
+    "src/mostlyright/data_harness/hosted_crawler_protocol.py",
+    "src/mostlyright/data_harness/key_seam.py",
+    "src/mostlyright/data_harness/page_coverage.py",
+    "src/mostlyright/data_harness/part_check_evidence.py",
+    "src/mostlyright/data_harness/session_probes.py",
+    "src/mostlyright/data_harness/skill_assets.py",
+    "src/mostlyright/data_harness/table_manifest.py",
+    "src/mostlyright/data_harness/thin",
+    "src/mostlyright/data_harness/ux/__init__.py",
+    "src/mostlyright/data_harness/ux/attendance.py",
+    "src/mostlyright/data_harness/ux/clarification.py",
+    "src/mostlyright/data_harness/ux/cloud_auth.py",
+    "src/mostlyright/data_harness/ux/credential_native.py",
+    "src/mostlyright/data_harness/ux/credential_store.py",
+    "src/mostlyright/data_harness/ux/credentials.py",
+    "src/mostlyright/data_harness/ux/login.py",
+    "src/mostlyright/data_harness/ux/path_kind.py",
+    "src/mostlyright/data_harness/ux/plain_file.py",
+    "src/mostlyright/data_harness/ux/remediation.py",
+    "src/mostlyright/data_harness/ux/render.py",
+    "src/mostlyright/data_harness/ux/commands/__init__.py",
+    "src/mostlyright/data_harness/ux/commands/auth.py",
+    "src/mostlyright/data_harness/ux/commands/clarify.py",
+    "src/mostlyright/data_harness/ux/commands/login.py",
+    "src/mostlyright/data_harness/ux/commands/whoami.py",
+]
+
+[tool.hatch.build.targets.wheel.force-include]
+"skills/mr-data-build" = "mostlyright/data_harness/skill_tree/mr-data-build"
+
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "scripts/hatch_build.py",
+    "skills/mr-data-build",
+    "src/mostlyright/data_harness/__init__.py",
+    "src/mostlyright/data_harness/canonical.py",
+    "src/mostlyright/data_harness/formats.py",
+    "src/mostlyright/data_harness/hosted_crawler_protocol.py",
+    "src/mostlyright/data_harness/key_seam.py",
+    "src/mostlyright/data_harness/page_coverage.py",
+    "src/mostlyright/data_harness/part_check_evidence.py",
+    "src/mostlyright/data_harness/session_probes.py",
+    "src/mostlyright/data_harness/skill_assets.py",
+    "src/mostlyright/data_harness/table_manifest.py",
+    "src/mostlyright/data_harness/thin",
+    "src/mostlyright/data_harness/ux/__init__.py",
+    "src/mostlyright/data_harness/ux/attendance.py",
+    "src/mostlyright/data_harness/ux/clarification.py",
+    "src/mostlyright/data_harness/ux/cloud_auth.py",
+    "src/mostlyright/data_harness/ux/credential_native.py",
+    "src/mostlyright/data_harness/ux/credential_store.py",
+    "src/mostlyright/data_harness/ux/credentials.py",
+    "src/mostlyright/data_harness/ux/login.py",
+    "src/mostlyright/data_harness/ux/path_kind.py",
+    "src/mostlyright/data_harness/ux/plain_file.py",
+    "src/mostlyright/data_harness/ux/remediation.py",
+    "src/mostlyright/data_harness/ux/render.py",
+    "src/mostlyright/data_harness/ux/commands",
+]
+
+[tool.hatch.build.hooks.custom]
+path = "scripts/hatch_build.py"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra --strict-markers"
+markers = [
+    "cross_repo: requires the exact sibling Studio contract/client tree",
+    "scale: exercises product-sized fixtures or a complete input domain",
+    "isolated_install: builds and exercises an isolated installed distribution",
+    "repository_scan: scans the complete live repository tree",
+    "contention_sensitive: crosses a wall-clock deadline -- its own or one the production code it drives enforces -- or measures RSS or a thread race, so it observes an idle machine",
+]
+tmp_path_retention_policy = "failed"
+tmp_path_retention_count = 96
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "RUF"]

{mostlyright_data-0.18.2 → mostlyright_data-0.19.0}/scripts/hatch_build.py

@@ -22,9 +22,9 @@ from hatchling.builders.hooks.plugin.interface import BuildHookInterface
 # The platform-specific tags this hook used to emit (`cp313-cp313-macosx_11_0_arm64`,
 # `cp313-cp313-linux_x86_64`) were a local-lane policy fence, never a statement about the
 # wheel's bytes. That fence kept Windows from having a wheel at all and held the thin-client
-# smoke to Linux. Where a platform restriction still exists it belongs to what needs it: the
-# native Reader binding selected by the `[local]` extra carries its own OS markers and its own
-# platform-tagged wheels, and the supported interpreter is `requires-python`'s to state.
+# smoke to Linux. Where a platform restriction still exists it belongs to what needs it, and
+# nothing this distribution ships needs one: the native Reader bindings and their platform-tagged
+# wheels are Studio's (ADR 0032), and the supported interpreter is `requires-python`'s to state.
 WHEEL_TAG = "py3-none-any"
 
 #: Every platform's spelling of "this is a compiled artifact", not merely this build host's. The

{mostlyright_data-0.18.2 → mostlyright_data-0.19.0}/skills/mr-data-build/SKILL.md

@@ -122,9 +122,9 @@ 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; `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. `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 command accepts `--sample`, `--full`, `--refresh`, `--backfill` and `--window`, and the worker executes `--sample`, `--full` and `--refresh`. 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` and a `--window` on a sample or full are refused before acquisition. `--max-rows` and `--max-source-bytes` remain supported, and each bounds ONE SOURCE rather than the finished table. A large run is held for a spend confirmation, which `--confirm` settles; a sample-first held full requires Studio's interactive human approval instead. `--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 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; a sample-first held full requires Studio's interactive human approval instead. `--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 and where. 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. `--status` and `--mode` narrow it and are refused for a word outside the seven or the four; `--limit` says how many, and pages are followed to reach it. |
+| `mr-data runs` | Report this workspace's own runs: identifier, mode, state and creation time, plus the failure triple of any that failed. `--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. |
 | `mr-data watch` | Stream one run's live progress under the durable event type of each stage, resuming across stream cuts. Exits non-zero when the run failed. |
 | `mr-data query` | Run one bounded read-only SQL statement over a finished run's own table and print the rows. Bounded on rows, on answer bytes and on time, and refused by name when a bound is crossed. |
 | `mr-data peek` | Print the columns, their logical types and the first rows of one run's table. The type comes off the run's own column profile where the preview carries none, so `type` is null only for a run that sealed no profile. |
@@ -182,9 +182,10 @@ what the submission printed and what the dashboard address contains.
 ## Installation parity
 
 Published distributions install with `pip`, and `pip install mostlyright-data` is the whole of it.
-The distribution also publishes a `[local]` extra: that is the execution engine's dependency
-closure, which the backend's worker image installs, and it makes no `mr-data` command run that does
-not run without it. Do not install it and do not offer it to a user as a way to get a command back.
+There is no extra, no second profile and no native wheel: the distribution resolves no third-party
+package at all, and the execution engine, the readers and the worker image live in Mostly Right
+Studio. Do not offer a user an install as a way to get a command back — there is none, and no
+command's behavior depends on what else a machine has.
 
 From a Harness checkout, install or update the persistent CLI and the complete Codex and Claude
 Code skill trees together:
@@ -209,8 +210,8 @@ neither can interleave with the other. Exact final verification commits the new
 later private-backup cleanup warning does not invalidate it and names the retained recovery path.
 
 That installer is for somebody working ON the Harness repository: it installs from a checkout
-rather than from `pip`, and it also installs the exact pinned wheel for Studio's separately owned
-generated client. A machine that is only using the product installs from `pip` instead.
+rather than from `pip`, and what it installs is exactly the distribution and nothing else. A
+machine that is only using the product installs from `pip` instead.
 
 ## Cloud authentication preflight
 
@@ -801,8 +802,9 @@ the two temperature scales are offsets rather than multipliers.
 ### 5. Build — take an unwindowed sample first
 
 Take an unwindowed sample before a full run. Choose row and source-byte bounds that exercise the
-shape without pretending they selected a time range. The current worker does not render a run
-window into any source request, so any stated `--window` is refused before acquisition.
+shape without pretending they selected a time range. A stated `--window` may be refused by the
+build service before acquisition; report the typed code it answers with rather than retrying the
+same run in another mode.
 
 ```sh
 mr-data run --recipe RECIPE_ID --digest RECIPE_DIGEST --sample --max-rows 2000 --json
@@ -882,14 +884,14 @@ sample. A run's narrative closes with the run, so a cell appended after that ans
 which is the other reason the search belongs there.
 [Narrating the run](#narrating-the-run) is the reference for what either cell may carry.
 
-**The protocol's three clamps do not behave alike, and the executable subset is narrower.** In the
-protocol, on `--sample`, `max_rows` and `window` truncate: the run succeeds at the clamp boundary
-and reports the coverage it actually delivered. `max_source_bytes` refuses in every mode, sample
-included, and on `full`, `refresh` and `backfill`, hitting any clamp is a refusal with
-`CLAMP_EXCEEDED`. The current worker admits `sample`, `full` and `refresh` and refuses `backfill` before applying
-those dispositions. A declared supported source window narrows that source's refresh request; it
-does not make every source or connector incremental. Therefore an executable sample may truncate
-on `max_rows`, and an executable full or refresh refuses a crossed row or byte ceiling.
+**The protocol's three clamps do not behave alike.** On `--sample`, `max_rows` and `window`
+truncate: the run succeeds at the clamp boundary and reports the coverage it actually delivered.
+`max_source_bytes` refuses in every mode, sample included, and on `full`, `refresh` and `backfill`,
+hitting any clamp is a refusal with `CLAMP_EXCEEDED`. Which modes and clamps the build service
+admits before those dispositions run is its own to decide and can be narrower than the protocol;
+a mode or clamp outside it comes back as a typed refusal, which you report rather than work
+around. A declared supported source window narrows that source's refresh request; it does not
+make every source or connector incremental.
 
 **A succeeded run carries `coverage`, and `truncated` is required on every entry.** That is how a
 complete acquired response is told from one cut at fifty thousand rows without opening the
@@ -908,7 +910,7 @@ revalidatable unless an explicit closure contract says they cannot change. A ref
 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` remains refused before acquisition.
+window. A `backfill` may be refused before acquisition; the refusal says so.
 
 ### 6. Interrogate — ask the run what it actually delivered
 
@@ -1665,6 +1667,13 @@ What it costs the protocol, and what to do instead:
   revision behavior, entity and geographic coverage, cost, and refresh fit. Reject prohibited use.
 - 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
+  `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
 

mostlyright_data-0.19.0/src/mostlyright/data_harness/__init__.py

@@ -0,0 +1,46 @@
+"""The hosted ``mr-data`` client package, and the closed public surface it actually provides.
+
+⚠ AN EXPORT IS A PROMISE THE INSTALLED WHEEL HAS TO KEEP. This module used to resolve fifty-eight
+names through a ``__getattr__`` over a table of module coordinates, and the table outlived the
+modules: the execution engine moved to Studio and every coordinate naming ``pipeline``, ``offline``,
+``recipe``, ``contracts``, ``local_contracts``, ``studio_boundary`` or ``review`` became an import
+that raises inside the shipped wheel. A dynamic coordinate is also invisible to the ownership
+scanner, so nothing held the table to the tree. Both problems have the same fix: the exports are
+plain imports of modules this distribution ships, so a missing one is an ImportError at build and
+test time rather than an AttributeError in somebody else's program.
+
+What is left is the canonical-JSON leaf, which the wire contracts share, and the version. Every
+command surface is reached through :mod:`mostlyright.data_harness.thin`.
+"""
+
+from importlib import metadata as _metadata
+
+from mostlyright.data_harness.canonical import (
+    CanonicalJSONError,
+    canonical_json_bytes,
+    canonical_sha256,
+    parse_canonical_json,
+    parse_json,
+)
+
+
+def package_version() -> str:
+    """Return the installed distribution version or an honest source-tree fallback."""
+
+    try:
+        return _metadata.version("mostlyright-data")
+    except _metadata.PackageNotFoundError:
+        return "uninstalled"
+
+
+__version__ = package_version()
+
+__all__ = [
+    "CanonicalJSONError",
+    "__version__",
+    "canonical_json_bytes",
+    "canonical_sha256",
+    "package_version",
+    "parse_canonical_json",
+    "parse_json",
+]