mostlyright-data 0.14.2__tar.gz → 0.15.0__tar.gz

{mostlyright_data-0.14.2 → mostlyright_data-0.15.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mostlyright-data
-Version: 0.14.2
+Version: 0.15.0
 Summary: Mostly Right CLI for reproducible, reviewed Parquet datasets
 Project-URL: Homepage, https://mostlyright.md/
 Project-URL: Documentation, https://mostlyright.md/docs/guides/cli/

{mostlyright_data-0.14.2 → mostlyright_data-0.15.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "mostlyright-data"
-version = "0.14.2"
+version = "0.15.0"
 description = "Mostly Right CLI for reproducible, reviewed Parquet datasets"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{mostlyright_data-0.14.2 → mostlyright_data-0.15.0}/skills/mr-data-build/SKILL.md

@@ -102,7 +102,7 @@ absence as a defect.
 
 ## Commands
 
-These twenty-eight are the whole surface, alongside `acquire-slices`, which names a capability
+These thirty are the whole surface, alongside `acquire-slices`, which names a capability
 gap rather than doing anything, and `export-hosted-candidate`, which is a backend operator step.
 
 | Command | What it does |
@@ -124,7 +124,9 @@ gap rather than doing anything, and `export-hosted-candidate`, which is a backen
 | `mr-data receipt` | Print what one run recorded about how it was built: every source it fetched and what those bytes hashed to, the coverage it delivered, and the members of its raw snapshot. |
 | `mr-data checks` | Report how each check the recipe declared came out — the name, whether it passed, what it found. Exits non-zero when one did not pass. |
 | `mr-data note` | Write one cell of a run's decision record — a heading, a body, and the typed blocks that carry a source, a decision or a clarification onto the stage its phase names. The body comes from `--markdown-file FILE`, which is the form to use; standard input is read when no file is named and is refused when it is a terminal or empty. `--list` reads back what is written. |
-| `mr-data download` | Bring one run's artifacts back to this computer, each one's bytes checked against the digest Studio sealed them under. `--kind` selects out of `table_parquet`, `column_profile`, `preview`, `receipt` and `raw_snapshot`; without it, the table and the receipt. |
+| `mr-data download` | Bring one run's artifacts back to this computer, each one's bytes checked against the digest Studio sealed them under. `--kind` selects out of `table_parquet`, `table_manifest`, `table_part`, `column_profile`, `preview`, `receipt` and `raw_snapshot`; without it, the table and the receipt — and for a run whose table is a manifest over parts, the manifest, its parts and the receipt, written as `table/manifest.json` beside `table/parts/<part_key>.parquet`. |
+| `mr-data verify` | Hold one run's sealed table manifest against the parts it names, and report every disagreement. Without `--deep` it fetches the manifest alone; with `--deep` it fetches every part the run sealed and re-hashes it against the digest the manifest states. Exits non-zero when anything disagrees. |
+| `mr-data parts` | List one table version's parts — the identifier, the row count, the byte size and the recorded bounds of each — so a training loader can shard them across workers and read a table no single file should hold. `--version` names a version rather than the live one, and `--from`/`--to` keep only the parts a value range cannot rule out. Nothing is downloaded by listing them; see [training loaders](../../docs/TRAINING-LOADERS.md) for the pattern. |
 | `mr-data diff` | Compare two runs and say what changed. |
 | `mr-data keys` | Enrol a source credential by name, list the names with their created and rotated times, and delete one. `keys set` reads the value from a file or from standard input and never from the command line; no command prints a value back. |
 | `mr-data stream` | Record a public `wss://` venue so a build can read it. `stream document register --file F` admits the connector document, `stream registry create --digest D` admits a set of them, `stream probe` listens briefly and seals nothing, `stream capture --seconds N` records a bounded window, `stream subscribe` keeps recording, `stream subscription {show|pause|resume|stop} ID` moves one, `stream status ID` reads a capture or a probe, and `stream recordings --document-digest D` names what a build could read and until when. `--seconds` is at most 600. `mr-data run` takes no duration: a build reads sealed batches and is bounded by them. |
@@ -137,8 +139,9 @@ gap rather than doing anything, and `export-hosted-candidate`, which is a backen
 | `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. |
 
 `auth`, `login`, `whoami` and `clarify` are the same implementation in both profiles, and
-`clarify` alone reaches nothing at all. The other twenty-four answer from Studio. Eight only
-read: `status`, `runs`, `watch`, `peek`, `receipt`, `checks`, `download` and `diff`.
+`clarify` alone reaches nothing at all. The other twenty-six answer from Studio. Ten only
+read: `status`, `runs`, `watch`, `peek`, `receipt`, `checks`, `download`, `verify`, `parts` and
+`diff`.
 Sixteen start or change something: `dataset`, `recipe`, `cover`, `run`, `query`, `probe`, `keys`,
 `stream`, `open`, `note`, `promote`, `reschedule`, `table`, `pin`, `unpin` and `demote`. The split
 is over names, not over invocations: `table TABLE` reads and `table rename` writes, and the name
@@ -248,8 +251,8 @@ every stage below writes to it as it goes rather than composing the page at the
 Authenticate first: run the Cloud authentication preflight above once, before the first cloud
 command of the session.
 
-**Then stage 1, and nothing before it.** `mr-data dataset create` and `mr-data open` are the first
-two commands of the session after the preflight. They come before the durable notes are read,
+**Then stage 1, and nothing before it.** `mr-data dataset create --handoff` and opening its navigation URL are the first
+two actions of the session after the preflight. They come before the durable notes are read,
 before `mr-data runs`, before a catalog is searched, before a provider's documentation is opened
 and before any URL is fetched. The lookups below are research, research is what fills the page, and
 a page created after the research has already happened is the assertion this stage exists to
@@ -291,14 +294,13 @@ message that contradicts you.
 Create the dataset from a working title and put it in front of whoever is watching, **before any
 source lookup**. These are the first two commands after the preflight — nothing reads a note,
 searches a catalog, opens a provider page or fetches a URL until they have both returned. It costs
-two commands and it is what turns a build into something a person can follow:
+one command and one host navigation, and it is what turns a build into something a person can follow:
 
 ```sh
-mr-data dataset create --name "Kathmandu monsoon flooding" --json
-mr-data open /datasets/DATASET_ID
+mr-data dataset create --name "Kathmandu monsoon flooding" --handoff --json
 ```
 
-Navigate the host's in-app browser to that address immediately, and keep that one tab for the whole
+Consume the creation receipt’s `navigation.url` immediately in the host’s in-app browser. Creation has succeeded even if `navigation.status` says `handoff_unavailable`; open the fallback URL or retry only `mr-data open`, never create again. Navigate to that address immediately, and keep that one tab for the whole
 build. The working title is allowed to be provisional — stage 4 writes the title it settles on —
 and a title that never changes is fine too. Where the address cannot be minted, carry on with the
 plain dashboard address rather than blocking.
@@ -478,8 +480,7 @@ mr-data dataset set DATASET_ID --description-file DESCRIPTION.md --json
 Two calls rather than one, so the person watching sees the title land and then the text arrive.
 Each call reads the version first and writes under it, so a description you wrote against a page
 somebody else has since edited is retried once and then reported rather than silently overwriting
-them. Write the description COMPLETE the first time — it is documentation, not a placeholder — and
-do not send it in pieces.
+them. While composing, send bounded snapshots with `mr-data dataset draft DATASET_ID --description-file DRAFT.md --expected-version VERSION --json`. Chain the returned version into the next snapshot, writing a meaningful paragraph at a time. These snapshots are temporary and do not replace the saved description. Commit the complete documentation with `mr-data dataset set DATASET_ID --description-file DESCRIPTION.md --expected-version VERSION --json`. If another edit moved that version, stop the draft and reconcile it with the user’s text; never retry by blindly advancing the version. Do not send fabricated partial text or delay completed text to simulate writing.
 
 **The dataset description is the documentation, and it is read by people and by search engines.**
 `dataset.description` is Markdown, rendered on the dataset page with headings and lists, and it
@@ -1700,3 +1701,11 @@ When comparing sources, use a compact `Source | Decision | Evidence` table, then
 source and its main limitation in one sentence each. Use field and quality tables for contracts.
 Give fields readable descriptions; do not rely on names such as `pm25_daily_mean` to explain
 themselves. Do not present a sequence of unlabeled paragraphs or default to a bullet dump.
+
+### Agent presence lifecycle
+
+The floating pill represents only your active work. Start `dataset activity` immediately after creation, update the sentence when your task changes, and renew at least once a minute while you are actively working. The default lease is two minutes. Do not leave a detached heartbeat running after your turn ends. Worker ingestion progress has its own table surface and is not proof that you are working.
+
+When recovering, report what you are trying now; an earlier failed attempt belongs in the record. Before every final handoff, cancellation, or exhausted stop, report `--phase done` with a truthful final sentence (for example, “Dataset ready to explore” or “Stopped before the build completed”). Do this even when tables are not enabled. Only use `waiting_on_you` when you have actually asked for an answer. Promotion does not finish your agent session.
+
+The host opens the dataset before research begins and keeps the same tab. Enable its optional Follow agent control for a watch-along experience; manual scrolling pauses it and must never be overridden.

{mostlyright_data-0.14.2 → mostlyright_data-0.15.0}/src/mostlyright/data_harness/acquisition/http.py

@@ -755,6 +755,138 @@ class ByteRange:
 _PRESENCE_PROBE_RANGE = ByteRange(first_byte=0, last_byte=0)
 
 
+NOT_MODIFIED_STATUS = 304
+# ``entity-tag = [ weak ] opaque-tag`` with ``etagc = %x21 / %x23-7E`` (RFC 9110 8.8.3).  The
+# obs-text range is excluded: a validator this boundary cannot spell back byte for byte is a
+# validator it will not send.  The length bound is the one the response-header reader already
+# holds validators to elsewhere in this repository.
+_ENTITY_TAG = re.compile(r'(?:W/)?"[\x21\x23-\x7e]{0,256}"')
+# ``IMF-fixdate``, and only that.  RFC 9110 5.6.7 requires a sender to use it and permits a
+# recipient to parse the two obsolete forms; a recipient that RE-SENDS what it parsed is a
+# sender, so the obsolete forms are refused here rather than normalized.  A publisher whose
+# ``Last-Modified`` is not an IMF-fixdate simply has no reusable date validator.
+#
+# The calendar is NOT checked -- a 31st of February matches -- and that is the right depth for
+# what this pattern is for.  The value is echoed back to the publisher that minted it, never
+# interpreted as a moment, so what has to be guaranteed is the shape a request header may carry:
+# a fixed length, a fixed field order, and no character that could end the header line.
+_IMF_FIXDATE = re.compile(
+    r"(?:Mon|Tue|Wed|Thu|Fri|Sat|Sun), [0-3][0-9] "
+    r"(?:Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) "
+    r"[0-9]{4} [0-2][0-9]:[0-5][0-9]:[0-6][0-9] GMT"
+)
+
+
+@dataclass(frozen=True)
+class ConditionalValidators:
+    """What a publisher said about an edition, offered back to it as a precondition.
+
+    A conditional request is ordered through this typed value rather than through a caller
+    supplied header mapping, for the reason :class:`ByteRange` is: a general ``extra_headers``
+    argument would put a header-injection surface at the most security-sensitive seam in this
+    package.  A validator validates itself against the grammar its own header field names and
+    renders to exactly the header values that grammar admits, so no caller composes a request
+    header character by character.
+
+    Both members are publisher-controlled text.  Nothing here interprets them -- no comparison
+    is made against a later response, no edition is inferred -- because the only party that can
+    say whether an entity tag still names the current edition is the publisher that minted it.
+    They are carried, spelled back, and otherwise opaque.
+
+    A WEAK ENTITY TAG IS A VALID PRECONDITION HERE.  ``If-None-Match`` uses the weak comparison
+    function (RFC 9110 8.8.3.2), so ``W/"..."`` is exactly as usable as a strong tag for asking
+    "has this changed"; it is only ``If-Match`` and ranged revalidation that need a strong one,
+    and neither is ordered through this type.
+    """
+
+    etag: str | None = None
+    last_modified: str | None = None
+
+    def __post_init__(self) -> None:
+        if self.etag is None and self.last_modified is None:
+            raise AcquisitionSecurityError(
+                "CONDITIONAL_VALIDATOR",
+                "a conditional request states at least one validator",
+            )
+        if self.etag is not None and (
+            not isinstance(self.etag, str) or _ENTITY_TAG.fullmatch(self.etag) is None
+        ):
+            raise AcquisitionSecurityError(
+                "CONDITIONAL_VALIDATOR",
+                "the entity tag is not an RFC 9110 entity-tag",
+            )
+        if self.last_modified is not None and (
+            not isinstance(self.last_modified, str)
+            or _IMF_FIXDATE.fullmatch(self.last_modified) is None
+        ):
+            raise AcquisitionSecurityError(
+                "CONDITIONAL_VALIDATOR",
+                "the modification date is not an IMF-fixdate",
+            )
+
+    @classmethod
+    def from_values(
+        cls, etag: str | None, last_modified: str | None
+    ) -> ConditionalValidators | None:
+        """The validators worth offering back, or ``None`` when neither is.
+
+        A publisher that stated something this boundary will not spell back -- an obsolete date
+        form, a tag with a character the grammar excludes -- gets a full request next time, which
+        is the outcome that already exists.  Refusing the whole acquisition over it would turn a
+        saving into an outage.
+        """
+
+        tag = etag if isinstance(etag, str) and _ENTITY_TAG.fullmatch(etag) else None
+        date = (
+            last_modified
+            if isinstance(last_modified, str) and _IMF_FIXDATE.fullmatch(last_modified)
+            else None
+        )
+        if tag is None and date is None:
+            return None
+        return cls(etag=tag, last_modified=date)
+
+    def header_values(self) -> tuple[tuple[str, str], ...]:
+        """The exact request headers this precondition renders to.
+
+        The entity tag is preferred and the date accompanies it: a publisher evaluates
+        ``If-None-Match`` and ignores ``If-Modified-Since`` when both are present (RFC 9110
+        13.2.2), so sending both costs nothing and leaves a date-only publisher answerable.
+        """
+
+        headers: list[tuple[str, str]] = []
+        if self.etag is not None:
+            headers.append(("If-None-Match", self.etag))
+        if self.last_modified is not None:
+            headers.append(("If-Modified-Since", self.last_modified))
+        return tuple(headers)
+
+
+class NotModified(AcquisitionSecurityError):
+    """The publisher answered a precondition with 304: this edition is the one already held.
+
+    It carries the same measured hop evidence a retrieval carries, because a 304 exchange is a
+    real exchange -- a DNS epoch, a pinned connection, a response with headers -- and the bytes
+    it did not cost are as much a fact of the run as the bytes a 200 did.  There is no content
+    and no media type: nothing was delivered, which is the point.
+
+    Raised rather than returned so the retriever's one success shape stays
+    :class:`RetrievedBytes`, and only a caller that asked a question by sending a precondition
+    can be answered with it.
+    """
+
+    def __init__(
+        self,
+        *,
+        hops: tuple[RetrievalHop, ...],
+        transport_evidence_digest: str,
+    ) -> None:
+        self.hops = hops
+        self.transport_evidence_digest = transport_evidence_digest
+        self.total_response_body_size_bytes = sum(hop.response_body_size_bytes for hop in hops)
+        super().__init__("NOT_MODIFIED", "source answered the precondition with 304")
+
+
 @dataclass(frozen=True)
 class RetrievalLimits:
     max_response_bytes: int = 16 * 1024 * 1024
@@ -1477,17 +1609,48 @@ class PinnedHttpsRetriever:
             clock=self._clock,
         )
 
-    def retrieve(self, url: str, *, byte_range: ByteRange | None = None) -> RetrievedBytes:
+    def retrieve(
+        self,
+        url: str,
+        *,
+        byte_range: ByteRange | None = None,
+        validators: ConditionalValidators | None = None,
+    ) -> RetrievedBytes:
+        """Retrieve one address, optionally conditioned on the edition already held.
+
+        ``validators`` makes this a conditional GET.  A publisher that answers 304 has stated
+        that the edition named by the precondition is still the current one, and that answer is
+        raised as :class:`NotModified` rather than returned: nothing was delivered, so there are
+        no bytes to hand back.  Every other answer is retrieved exactly as an unconditional one
+        would be, including a 200 whose entity tag has not moved -- what the bytes are is decided
+        by the bytes.
+        """
+
         if byte_range is not None and not isinstance(byte_range, ByteRange):
             raise AcquisitionSecurityError(
                 "BYTE_RANGE",
                 "a slice is ordered only through a validated byte range",
             )
+        if validators is not None and not isinstance(validators, ConditionalValidators):
+            raise AcquisitionSecurityError(
+                "CONDITIONAL_VALIDATOR",
+                "a precondition is ordered only through validated conditional validators",
+            )
+        if validators is not None and byte_range is not None:
+            # A conditional ranged request is two questions in one exchange and the answers do
+            # not compose: 304 speaks about the whole representation while 206 speaks about the
+            # span, and the delivery check below has nothing to hold a 304 against.  Ranged
+            # revalidation belongs to ``If-Range`` and is not ordered here.
+            raise AcquisitionSecurityError(
+                "CONDITIONAL_VALIDATOR",
+                "a precondition and a slice are not ordered in one request",
+            )
         return self._fetch(
             url,
             byte_range=byte_range,
             presence_probe=False,
             datagov_authorization=None,
+            validators=validators,
         )
 
     def retrieve_datagov_v4(
@@ -1639,7 +1802,24 @@ class PinnedHttpsRetriever:
         frozen_headers: Mapping[str, str] | None = None,
         frozen_method: str = "GET",
         frozen_body: bytes | None = None,
+        validators: ConditionalValidators | None = None,
     ) -> RetrievedBytes:
+        if validators is not None and (
+            presence_probe
+            or byte_range is not None
+            or datagov_authorization is not None
+            or authenticated_authorization is not None
+            or frozen_headers is not None
+        ):
+            # A precondition is offered on the plain public path and nowhere else.  A probe keeps
+            # nothing, so it has no edition to condition on; the credentialed paths compose their
+            # request headers under an authorization that rejects echoes and pins its own exact
+            # shape, and a second source of headers there would be a second thing to reason about
+            # at the seam that most needs one.
+            raise AcquisitionSecurityError(
+                "CONDITIONAL_VALIDATOR",
+                "a precondition is offered only on an unauthenticated whole-document retrieval",
+            )
         started = float(self._clock())
         current_url = url
         hops: list[RetrievalHop] = []
@@ -1678,6 +1858,13 @@ class PinnedHttpsRetriever:
             }
             if frozen_headers is not None:
                 headers.update(frozen_headers)
+            if validators is not None:
+                # Offered on every hop of the chain rather than on the first alone.  A
+                # precondition is a fact about the representation the address names, and an
+                # address that redirects still names it; dropping the precondition at a redirect
+                # would turn a revalidation into a full download at exactly the sources that
+                # front their objects behind one.
+                headers.update(validators.header_values())
             if datagov_authorization is not None:
                 name, value = datagov_authorization.header_for(target.normalized_url)
                 headers[name] = value
@@ -1925,6 +2112,49 @@ class PinnedHttpsRetriever:
                     peer_attempts,
                     hops,
                 )
+            # THE ANSWER TO A PRECONDITION, AND ONLY WHEN ONE WAS ASKED.  A 304 to a request that
+            # sent no validator is a publisher answering a question nobody put, so it falls
+            # through to the generic status refusal below and stays a failure.
+            #
+            # IT IS SETTLED BEFORE THE REPRESENTATION CHECKS BECAUSE A 304 DESCRIBES A
+            # REPRESENTATION IT DID NOT SEND.  RFC 9110 9.3.1 lets a 304 carry the header fields
+            # a 200 would have carried, so its ``Content-Length`` states the size of the object
+            # that was NOT transferred and its ``Content-Encoding`` names how that object would
+            # have been encoded.  Held against the empty body those two are a mismatch and a
+            # forbidden encoding, and the exchange that saved the whole download would be refused
+            # as malformed.  The body is checked against nothing else: a 304 carrying one is
+            # refused outright.
+            if validators is not None and response.status == NOT_MODIFIED_STATUS:
+                if response.body:
+                    self._raise_peer_failure(
+                        "NOT_MODIFIED_BODY",
+                        "source answered 304 with a response body",
+                        peer_attempts,
+                        hops,
+                    )
+                hops.append(
+                    RetrievalHop(
+                        url=target.normalized_url,
+                        resolution_digest=target.resolution_digest,
+                        connected_peer=peer,
+                        status=response.status,
+                        response_headers_digest=canonical_sha256(normalized_headers),
+                        response_body_size_bytes=0,
+                        response_body_sha256=sha256_bytes(b""),
+                        requested_range=None,
+                        observed_content_range=None,
+                        etag=self._response_header(response, "etag", peer_attempts, hops),
+                        last_modified=self._response_header(
+                            response, "last-modified", peer_attempts, hops
+                        ),
+                        peer_attempts=tuple(peer_attempts),
+                        approved_ips=target.approved_ips,
+                    )
+                )
+                raise NotModified(
+                    hops=tuple(hops),
+                    transport_evidence_digest=canonical_sha256([item.to_dict() for item in hops]),
+                )
             content_length = self._response_header(response, "content-length", peer_attempts, hops)
             declared_length: int | None = None
             if content_length is not None:

{mostlyright_data-0.14.2 → mostlyright_data-0.15.0}/src/mostlyright/data_harness/bounded_query.py

@@ -32,12 +32,19 @@ enumerated here because a reader who wants to weaken one should have to argue wi
    named here rather than left for a reader to discover.
 
 3. **One view, over this run's own parquet, and no path is ever built from caller input.** The only
-   file name this module composes is the local path it was HANDED -- the temporary file the claim
-   loop downloaded ``table_session.signed_url`` into. ``allowed_paths`` is set to exactly that one
-   file (plus, by DuckDB itself, the throwaway catalog it must read), which is what lets the bound
-   view resolve while every other path on the same disk stays unreachable. The caller's ``sql`` is
-   passed to the engine and to nothing else: it is never concatenated into a path, a setting, or a
-   view definition.
+   file names this module composes are the local paths it was HANDED -- the temporary files the
+   claim loop downloaded this version's selected parts into. ``allowed_paths`` is set to exactly
+   those files (plus, by DuckDB itself, the throwaway catalog it must read), which is what lets the
+   bound view resolve while every other path on the same disk stays unreachable. The caller's
+   ``sql`` is passed to the engine and to nothing else: it is never concatenated into a path, a
+   setting, or a view definition.
+
+   **A table version is a list of parts, and the list is what is admitted.** A v1 version hands one
+   path and a partitioned one hands the parts Studio's ``prune`` block selected; the property is
+   unchanged either way, because the admitted set is still exactly the files this claim delivered
+   and is still composed from arguments rather than from ``sql``. :data:`MAX_QUERY_PARTS` bounds
+   how long that list may be, so a version with four thousand parts is a named refusal rather than
+   four thousand open file handles.
 
 4. **The caps.** Rows TRUNCATE at the ``max_rows`` Studio sent and the answer says ``truncated``;
    bytes and time REFUSE. The byte ceiling is a refusal and never a truncation, because "a short
@@ -107,6 +114,12 @@ QUERY_RESULT_MAX_BYTES = 262_144
 #: all. Property 4 says the boundary is the worker's; a cap the worker does not check is Studio's.
 MAX_QUERY_ROWS = 1_000_000
 
+#: How many parts one bounded question may be bound over. A pruned one-day range on the format's
+#: reference table selects one or two; an unpruned read of a billion-row table selects three
+#: hundred and eighteen. The ceiling is where the list stops being a query and starts being an
+#: export, and the refusal names ``prune`` as the fix rather than raising the ceiling.
+MAX_QUERY_PARTS = 512
+
 #: How many rows are taken from the engine at a time. The running byte budget is checked BETWEEN
 #: chunks, so what a refused answer materializes on the Python side is bounded by ONE chunk rather
 #: than by the row cap -- ``fetchmany(max_rows + 1)`` took every cell of every row before anything
@@ -162,6 +175,10 @@ QUERY_RESULT_TOO_LARGE = "QUERY_RESULT_TOO_LARGE"
 #: The worker's own wall clock ran out, before the statement or during it.
 QUERY_TIMEOUT = "QUERY_TIMEOUT"
 
+#: The claim named more parts than one bounded question binds. Its sentence names ``prune``,
+#: because the fix is to ask for a slice of the table rather than for a larger engine.
+QUERY_TOO_MANY_PARTS = "QUERY_TOO_MANY_PARTS"
+
 #: What an engine failure whose class name cannot be rendered as Studio's grammar reports as.
 #:
 #: NOT in ``WORKER_REFUSAL_CODES`` and not in the inventory's ``worker_refusals``, because it is
@@ -181,6 +198,7 @@ WORKER_REFUSAL_CODES: tuple[str, ...] = (
     QUERY_STATEMENT_NOT_SINGLE,
     QUERY_RESULT_TOO_LARGE,
     QUERY_TIMEOUT,
+    QUERY_TOO_MANY_PARTS,
 )
 
 #: Studio's grammar for a worker-reported ``failure_code``
@@ -277,7 +295,7 @@ def _import_engine() -> Any:
     return duckdb
 
 
-def _confine(connection: Any, *, table_path: Path, duckdb: Any) -> None:
+def _confine(connection: Any, *, table_paths: Sequence[Path], duckdb: Any) -> None:
     """Establish the four properties plus the pinned clock, in the one order that makes them true.
 
     ``allowed_paths`` first, because it is what will let the bound view read the one file once the
@@ -298,9 +316,9 @@ def _confine(connection: Any, *, table_path: Path, duckdb: Any) -> None:
     five must not answer.
     """
 
-    literal = str(table_path).replace("'", "''")
+    admitted = ", ".join(_path_literal(path) for path in table_paths)
     settings = (
-        f"set allowed_paths = ['{literal}']",
+        f"set allowed_paths = [{admitted}]",
         "set enable_external_access = false",
         f"set memory_limit = '{MEMORY_LIMIT}'",
         "set TimeZone = 'UTC'",
@@ -316,6 +334,17 @@ def _confine(connection: Any, *, table_path: Path, duckdb: Any) -> None:
             ) from error
 
 
+def _path_literal(path: Path) -> str:
+    """One local path as a single-quoted SQL literal, with its own quotes doubled.
+
+    The path never comes from ``sql`` -- property 3 -- so this is not an escaping defence against
+    the caller; it is what keeps a path a legal literal when the container's own scratch directory
+    contains an apostrophe.
+    """
+
+    return "'" + str(path).replace("'", "''") + "'"
+
+
 def _require_single_statement(connection: Any, sql: str, *, duckdb: Any) -> None:
     """Ask DuckDB's own parser how many statements this is.
 
@@ -342,18 +371,19 @@ def _require_single_statement(connection: Any, sql: str, *, duckdb: Any) -> None
 def execute_bounded_query(
     *,
     sql: str,
-    table_path: Path,
+    table_paths: Sequence[Path],
     max_rows: int,
     deadline_seconds: float,
     max_result_bytes: int = QUERY_RESULT_MAX_BYTES,
     monotonic: Callable[[], float] = time.monotonic,
     timer_factory: Callable[[float, Callable[[], None]], Any] = threading.Timer,
 ) -> BoundedQueryResult:
-    """Answer one bounded statement against one run's parquet, inside the four properties.
+    """Answer one bounded statement against one table version's parts, inside the four properties.
 
-    ``table_path`` is the local file the claim loop downloaded this run's ``table_session`` into.
-    It is the ONLY file name this function composes, and it is composed from this argument and
-    never from ``sql``.
+    ``table_paths`` are the local files the claim loop downloaded this version's selected parts
+    into -- one for a v1 version, and whatever Studio's ``prune`` block selected for a partitioned
+    one. They are the ONLY file names this function composes, and they are composed from this
+    argument and never from ``sql``.
 
     ``timer_factory`` exists so the deadline can be asserted without spending one: it decides WHEN
     the engine is interrupted and can neither weaken nor widen anything the connection is confined
@@ -372,11 +402,25 @@ def execute_bounded_query(
             f"a bounded query runs under a row cap of 1..{MAX_QUERY_ROWS}; this one asked for "
             f"{max_rows}",
         )
-    resolved = table_path.resolve()
-    if not resolved.is_file():
+    if len(table_paths) > MAX_QUERY_PARTS:
+        raise HostedWorkerError(
+            "QUERY_TOO_MANY_PARTS",
+            f"this question binds {len(table_paths)} parts against a ceiling of "
+            f"{MAX_QUERY_PARTS}; narrow it with a prune block naming a field range or a partition",
+        )
+    if not table_paths:
+        raise HostedWorkerError(
+            "QUERY_TABLE_UNAVAILABLE",
+            "this question selected no part of the table; a prune block that matches nothing has "
+            "no rows to read and no schema to bind",
+        )
+    resolved = [path.resolve() for path in table_paths]
+    missing = [path for path in resolved if not path.is_file()]
+    if missing:
         raise HostedWorkerError(
             "QUERY_TABLE_UNAVAILABLE",
-            "this run's table is not on local disk; the download did not produce a file",
+            f"{len(missing)} of this version's {len(resolved)} parts are not on local disk; the "
+            "download did not produce every file",
         )
     started = monotonic()
 
@@ -392,9 +436,9 @@ def execute_bounded_query(
                 "QUERY_ENGINE_UNCONFINED", f"the engine would not start: {_sentence(error)}"
             ) from error
         try:
+            listed = ", ".join(_path_literal(path) for path in resolved)
             builder.execute(
-                f"create view {BOUND_VIEW_NAME} as "
-                f"select * from read_parquet('{str(resolved).replace(chr(39), chr(39) * 2)}')"
+                f"create view {BOUND_VIEW_NAME} as select * from read_parquet([{listed}])"
             )
         except duckdb.Error as error:
             raise HostedWorkerError(
@@ -412,7 +456,7 @@ def execute_bounded_query(
                 f"the engine would not re-open read-only: {_sentence(error)}",
             ) from error
         try:
-            _confine(connection, table_path=resolved, duckdb=duckdb)
+            _confine(connection, table_paths=resolved, duckdb=duckdb)
             _require_single_statement(connection, sql, duckdb=duckdb)
             remaining = deadline_seconds - (monotonic() - started)
             if remaining <= 0:
@@ -650,6 +694,7 @@ __all__ = [
     "FETCH_CHUNK_ROWS",
     "MATERIALIZATION_FACTOR",
     "MAX_FAILURE_DETAIL",
+    "MAX_QUERY_PARTS",
     "MAX_QUERY_ROWS",
     "MEMORY_LIMIT",
     "QUERY_ENGINE_REFUSED",
@@ -660,6 +705,7 @@ __all__ = [
     "QUERY_STATEMENT_NOT_SINGLE",
     "QUERY_TABLE_UNAVAILABLE",
     "QUERY_TIMEOUT",
+    "QUERY_TOO_MANY_PARTS",
     "WORKER_REFUSAL_CODES",
     "BoundedQueryError",
     "BoundedQueryResult",