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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.25.5
+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/
@@ -86,6 +86,10 @@ Full builds are progressive by default: one acquisition exposes an inspection ch
 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.
 

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

@@ -74,6 +74,10 @@ Full builds are progressive by default: one acquisition exposes an inspection ch
 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.
 

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

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

{mostlyright_data-0.25.5 → 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 = "8af29918f5568dcc64d104f137dbf6bf88562e0687c9fb054ea9266cf4c5146b"
-PINNED_V4_CONTRACT_VERSION = "4.11.0"
+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.5 → 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.5 → 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,
         *,
@@ -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)
 
 
@@ -1527,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: