mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/session_probes.py

@@ -0,0 +1,759 @@
+"""The probe vocabulary a research session speaks (ADR 0021).
+
+Studio owns the probe *kind* enum and nothing else about a probe. Its contract says so in as many
+words: a probe request and a probe result are "opaque to Studio", size-bounded, digested, and
+stored uninterpreted, "so the harness can add a probe parameter or a result field without a Studio
+contract change". This module is the other half of that arrangement -- the place where the bodies
+under those four kinds are actually specified, so that "opaque to Studio" does not degrade into
+"unspecified anywhere".
+
+**Why the kind enum is not restated as a choice.** ``research-session.schema.json`` closes
+``probe_kind`` to four values. Restating them here as a *harness* decision would invite the two
+spellings to drift; :data:`PROBE_KINDS` is therefore the same four, and
+``tests/test_session_probes.py`` asserts it equals the generated ``ContractProbeKind`` enum. What
+the harness decides is the body, and only the body.
+
+**Why the schemas are data and the validators are code.** Every schema below is a JSON Schema
+object, and every one of them is enforced at runtime by a hand-written validator rather than by a
+schema library. That is not duplication for its own sake: ``jsonschema`` is a development and
+release dependency and is deliberately absent from ``[local]``, which is the only extra the worker
+image installs, so a runtime schema check would be a runtime import the image cannot satisfy. The
+schemas are the statement, the validators are the enforcement, and
+``test_session_probes.py`` runs both over the same corpus and refuses any input the two disagree
+about. A drifted validator is a red test rather than a silently widened probe.
+
+**Why every request names a source.** All four kinds carry ``source_id``, including
+``evaluate_expression``. It costs one field and buys two things. Probe progress can then be emitted
+as the ``source_probe_started`` / ``source_probe_settled`` pair -- which travel as Studio's
+``attempt_progress`` and ``source_probe_completed`` event types, exactly the two the
+research-session design names -- without mislabelling a probe id as a source id. And the session's
+``context.source_ids`` becomes an enforceable allowlist: a probe that names a source the session
+was not opened against is refused before anything is read, which is the whole of a probe's
+authority check.
+
+**Why expressions are an AST and never a string.** ``evaluate_expression`` is the one kind a caller
+could reasonably expect to accept a little language. It does not. The request carries a closed,
+bounded, non-recursive-by-construction operator tree; there is no parser, no ``eval``, no
+comprehension over caller text, and no operator whose cost is superlinear in anything the caller
+controls. A probe body arrives from Studio having been stored uninterpreted, which means it arrives
+with exactly as much trust as the client that submitted it -- that is to say, none.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Mapping, Sequence
+from typing import Any, Final
+
+from mostlyright.data_harness.canonical import canonical_json_bytes
+
+#: The vocabulary's own version, carried on every result body. It is not Studio's
+#: ``schema_version``: Studio versions the envelope, this versions what the harness puts inside it,
+#: and the point of the arrangement is that this number can move without Studio moving.
+PROBE_SCHEMA_VERSION: Final = "mr-session-probes.v1"
+
+#: Studio's closed enum, restated so this module loads without the generated client (the
+#: ``progress_events`` precedent) and asserted equal to it by the test suite.
+PROBE_KINDS: Final[tuple[str, ...]] = (
+    "source_inspect",
+    "sample_rows",
+    "profile_columns",
+    "evaluate_expression",
+)
+
+#: Studio's own bounds on the two opaque bodies, restated because the worker must refuse an
+#: oversized result *before* spending a request on it. Studio enforces these too; a worker that
+#: relied on that alone would learn about the ceiling by being rejected, after the work.
+PROBE_REQUEST_MAX_BYTES: Final = 64 * 1024
+PROBE_RESULT_MAX_BYTES: Final = 256 * 1024
+
+#: How many rows any probe may pull back, and how many any probe may look at. The first bounds the
+#: answer, the second bounds the work: a profile over a million rows is not an interactive probe.
+MAX_SAMPLE_ROWS: Final = 200
+MAX_SCAN_ROWS: Final = 50_000
+DEFAULT_SCAN_ROWS: Final = 10_000
+#: A cell is rendered as a short token or a number. A probe answer is a preview, not an export, so
+#: a long string is truncated in the answer rather than the answer being refused.
+MAX_CELL_CHARS: Final = 512
+MAX_PROFILE_COLUMNS: Final = 256
+#: Expression trees are bounded twice: by depth, so nesting cannot be used to build a large tree
+#: from a small body, and by operand count at each node.
+MAX_EXPRESSION_DEPTH: Final = 8
+MAX_EXPRESSION_OPERANDS: Final = 16
+
+#: The aggregate an ``evaluate_expression`` probe may compute. Closed, and every member is one
+#: pass over at most ``MAX_SCAN_ROWS`` values.
+AGGREGATES: Final[tuple[str, ...]] = ("count", "sum", "min", "max", "avg")
+
+#: The predicate operators a filter may use. Closed, and every member is one comparison between one
+#: cell and one caller literal. Nothing here matches, searches, or concatenates.
+COMPARISONS: Final[tuple[str, ...]] = ("eq", "ne", "lt", "le", "gt", "ge")
+UNARY_TESTS: Final[tuple[str, ...]] = ("is_null", "is_not_null")
+CONNECTIVES: Final[tuple[str, ...]] = ("and", "or", "not")
+
+
+class ProbeVocabularyError(ValueError):
+    """A probe body that is not in the vocabulary. Carries the code the probe fails with."""
+
+    def __init__(self, code: str, detail: str) -> None:
+        super().__init__(f"{code}: {detail}")
+        self.code = code
+        self.detail = detail
+
+
+# ------------------------------------------------------------------------------------------
+# The declared schemas. Documentation and test oracle; never the runtime check -- see the module
+# docstring for why the worker image cannot afford a schema library.
+# ------------------------------------------------------------------------------------------
+
+_UUID_PATTERN: Final = "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+_COLUMN: Final = {"type": "string", "minLength": 1, "maxLength": 256}
+_SCALAR: Final = {
+    "description": "One caller literal. Numbers, booleans, null and short strings only.",
+    "type": ["string", "number", "boolean", "null"],
+    "maxLength": MAX_CELL_CHARS,
+}
+
+
+def _predicate_schema(depth: int) -> dict[str, Any]:
+    """The predicate grammar, unrolled to :data:`MAX_EXPRESSION_DEPTH`.
+
+    Unrolled rather than expressed with ``$ref`` back to itself, because a self-referential schema
+    states a grammar with no depth bound and this grammar's depth bound is a security property.
+    The unrolled form makes the ceiling visible in the schema instead of only in the validator.
+    """
+
+    branches: list[dict[str, Any]] = [
+        {
+            "type": "object",
+            "additionalProperties": False,
+            "required": ["op", "column", "value"],
+            "properties": {
+                "op": {"enum": list(COMPARISONS)},
+                "column": _COLUMN,
+                "value": _SCALAR,
+            },
+        },
+        {
+            "type": "object",
+            "additionalProperties": False,
+            "required": ["op", "column"],
+            "properties": {"op": {"enum": list(UNARY_TESTS)}, "column": _COLUMN},
+        },
+    ]
+    if depth > 1:
+        inner = _predicate_schema(depth - 1)
+        branches.append(
+            {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["op", "operands"],
+                "properties": {
+                    "op": {"enum": ["and", "or"]},
+                    "operands": {
+                        "type": "array",
+                        "minItems": 1,
+                        "maxItems": MAX_EXPRESSION_OPERANDS,
+                        "items": inner,
+                    },
+                },
+            }
+        )
+        branches.append(
+            {
+                "type": "object",
+                "additionalProperties": False,
+                "required": ["op", "operand"],
+                "properties": {"op": {"const": "not"}, "operand": inner},
+            }
+        )
+    return {"oneOf": branches}
+
+
+PREDICATE_SCHEMA: Final[dict[str, Any]] = _predicate_schema(MAX_EXPRESSION_DEPTH)
+
+PROBE_REQUEST_SCHEMA: Final[Mapping[str, dict[str, Any]]] = {
+    "source_inspect": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "title": "source_inspect request",
+        "description": (
+            "What shape is this source? Reports the detected format, the column names and their "
+            "inferred types, and the schema digest -- and no cell values at all, which is what "
+            "separates it from sample_rows."
+        ),
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["source_id"],
+        "properties": {
+            "source_id": {"type": "string", "pattern": _UUID_PATTERN},
+            "scan_rows": {"type": "integer", "minimum": 1, "maximum": MAX_SCAN_ROWS},
+        },
+    },
+    "sample_rows": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "title": "sample_rows request",
+        "description": "The first `limit` rows after `offset`, rendered as preview cells.",
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["source_id", "limit"],
+        "properties": {
+            "source_id": {"type": "string", "pattern": _UUID_PATTERN},
+            "limit": {"type": "integer", "minimum": 1, "maximum": MAX_SAMPLE_ROWS},
+            "offset": {"type": "integer", "minimum": 0, "maximum": MAX_SCAN_ROWS},
+            "columns": {
+                "description": "Project to these columns. Absent means every column.",
+                "type": "array",
+                "minItems": 1,
+                "maxItems": MAX_PROFILE_COLUMNS,
+                "uniqueItems": True,
+                "items": _COLUMN,
+            },
+        },
+    },
+    "profile_columns": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "title": "profile_columns request",
+        "description": (
+            "Per-column null counts, distinct counts and extremes over a bounded scan. Distinct "
+            "is exact over the scanned rows and is reported with the number scanned, because a "
+            "distinct count without its denominator is a number nobody can use."
+        ),
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["source_id"],
+        "properties": {
+            "source_id": {"type": "string", "pattern": _UUID_PATTERN},
+            "scan_rows": {"type": "integer", "minimum": 1, "maximum": MAX_SCAN_ROWS},
+            "columns": {
+                "type": "array",
+                "minItems": 1,
+                "maxItems": MAX_PROFILE_COLUMNS,
+                "uniqueItems": True,
+                "items": _COLUMN,
+            },
+        },
+    },
+    "evaluate_expression": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "title": "evaluate_expression request",
+        "description": (
+            "One aggregate over an optionally filtered bounded scan. The expression is an "
+            "operator tree, never a string: there is no parser here and nothing a caller sends "
+            "is ever compiled, evaluated, or matched as a pattern."
+        ),
+        "type": "object",
+        "additionalProperties": False,
+        "required": ["source_id", "expression"],
+        "properties": {
+            "source_id": {"type": "string", "pattern": _UUID_PATTERN},
+            "scan_rows": {"type": "integer", "minimum": 1, "maximum": MAX_SCAN_ROWS},
+            # Two arms, not one with an optional column: `count` counts matched ROWS and takes no
+            # column, because `count(column)` would silently mean either rows or non-null values
+            # and an exploratory caller has no way to tell which they got. Every other aggregate
+            # needs a column and says so here rather than only in the validator.
+            "expression": {
+                "oneOf": [
+                    {
+                        "type": "object",
+                        "additionalProperties": False,
+                        "required": ["aggregate"],
+                        "properties": {
+                            "aggregate": {"const": "count"},
+                            "where": PREDICATE_SCHEMA,
+                        },
+                    },
+                    {
+                        "type": "object",
+                        "additionalProperties": False,
+                        "required": ["aggregate", "column"],
+                        "properties": {
+                            "aggregate": {"enum": [name for name in AGGREGATES if name != "count"]},
+                            "column": _COLUMN,
+                            "where": PREDICATE_SCHEMA,
+                        },
+                    },
+                ]
+            },
+        },
+    },
+}
+
+_RESULT_ENVELOPE: Final[dict[str, Any]] = {
+    "schema_version": {"const": PROBE_SCHEMA_VERSION},
+    "probe_kind": {"enum": list(PROBE_KINDS)},
+    "source_id": {"type": "string", "pattern": _UUID_PATTERN},
+    "content_sha256": {"type": "string", "pattern": "^[0-9a-f]{64}$"},
+    "content_bytes": {"type": "integer", "minimum": 0},
+    "data_format": {"type": "string", "minLength": 1, "maxLength": 64},
+    "sandbox_policy_digest": {"type": "string", "minLength": 1, "maxLength": 256},
+    "rows_scanned": {"type": "integer", "minimum": 0},
+    "truncated": {"type": "boolean"},
+}
+_ENVELOPE_REQUIRED: Final = (
+    "schema_version",
+    "probe_kind",
+    "source_id",
+    "content_sha256",
+    "content_bytes",
+    "data_format",
+    "sandbox_policy_digest",
+    "rows_scanned",
+    "truncated",
+)
+
+_COLUMN_SHAPE: Final[dict[str, Any]] = {
+    "type": "object",
+    "additionalProperties": False,
+    "required": ["name", "inferred_type"],
+    "properties": {
+        "name": _COLUMN,
+        "inferred_type": {"enum": ["string", "integer", "number", "boolean", "null", "mixed"]},
+    },
+}
+
+PROBE_RESULT_SCHEMA: Final[Mapping[str, dict[str, Any]]] = {
+    "source_inspect": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "additionalProperties": False,
+        "required": [*_ENVELOPE_REQUIRED, "columns", "schema_digest"],
+        "properties": {
+            **_RESULT_ENVELOPE,
+            "media_type": {"type": "string", "minLength": 1, "maxLength": 256},
+            "schema_digest": {"type": "string", "minLength": 1, "maxLength": 256},
+            "columns": {
+                "type": "array",
+                "maxItems": MAX_PROFILE_COLUMNS,
+                "items": _COLUMN_SHAPE,
+            },
+        },
+    },
+    "sample_rows": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "additionalProperties": False,
+        "required": [*_ENVELOPE_REQUIRED, "columns", "rows"],
+        "properties": {
+            **_RESULT_ENVELOPE,
+            "columns": {
+                "type": "array",
+                "maxItems": MAX_PROFILE_COLUMNS,
+                "items": _COLUMN,
+            },
+            "rows": {
+                "type": "array",
+                "maxItems": MAX_SAMPLE_ROWS,
+                "items": {
+                    "type": "array",
+                    "maxItems": MAX_PROFILE_COLUMNS,
+                    "items": {"type": ["string", "number", "boolean", "null"]},
+                },
+            },
+        },
+    },
+    "profile_columns": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "additionalProperties": False,
+        "required": [*_ENVELOPE_REQUIRED, "columns"],
+        "properties": {
+            **_RESULT_ENVELOPE,
+            "columns": {
+                "type": "array",
+                "maxItems": MAX_PROFILE_COLUMNS,
+                "items": {
+                    "type": "object",
+                    "additionalProperties": False,
+                    "required": ["name", "inferred_type", "non_null", "nulls", "distinct"],
+                    "properties": {
+                        **_COLUMN_SHAPE["properties"],
+                        "non_null": {"type": "integer", "minimum": 0},
+                        "nulls": {"type": "integer", "minimum": 0},
+                        "distinct": {"type": "integer", "minimum": 0},
+                        "minimum": {"type": ["string", "number", "boolean", "null"]},
+                        "maximum": {"type": ["string", "number", "boolean", "null"]},
+                    },
+                },
+            },
+        },
+    },
+    "evaluate_expression": {
+        "$schema": "http://json-schema.org/draft-07/schema#",
+        "type": "object",
+        "additionalProperties": False,
+        "required": [*_ENVELOPE_REQUIRED, "aggregate", "value", "rows_matched"],
+        "properties": {
+            **_RESULT_ENVELOPE,
+            "aggregate": {"enum": list(AGGREGATES)},
+            "column": _COLUMN,
+            "value": {"type": ["string", "number", "boolean", "null"]},
+            "rows_matched": {"type": "integer", "minimum": 0},
+        },
+    },
+}
+
+
+# ------------------------------------------------------------------------------------------
+# Runtime validation. Hand written, total, and refusing rather than coercing.
+# ------------------------------------------------------------------------------------------
+
+
+def _require(condition: bool, code: str, detail: str) -> None:
+    if not condition:
+        raise ProbeVocabularyError(code, detail)
+
+
+def _object(value: Any, label: str) -> dict[str, Any]:
+    _require(
+        isinstance(value, dict) and all(isinstance(key, str) for key in value),
+        "PROBE_REQUEST_INVALID",
+        f"{label} must be an object with string keys",
+    )
+    return dict(value)
+
+
+def _exact_keys(value: Mapping[str, Any], required: set[str], optional: set[str]) -> None:
+    present = set(value)
+    missing = sorted(required - present)
+    _require(not missing, "PROBE_REQUEST_INVALID", f"missing field(s): {', '.join(missing)}")
+    unknown = sorted(present - required - optional)
+    _require(not unknown, "PROBE_REQUEST_INVALID", f"unknown field(s): {', '.join(unknown)}")
+
+
+def _uuid_text(value: Any, label: str) -> str:
+    _require(isinstance(value, str), "PROBE_REQUEST_INVALID", f"{label} must be a string")
+    text = str(value)
+    parts = text.split("-")
+    shape = [8, 4, 4, 4, 12]
+    ok = len(parts) == 5 and all(
+        len(part) == width and all(character in "0123456789abcdef" for character in part)
+        for part, width in zip(parts, shape, strict=True)
+    )
+    _require(ok, "PROBE_REQUEST_INVALID", f"{label} must be a lowercase UUID")
+    return text
+
+
+def _bounded_int(value: Any, label: str, *, minimum: int, maximum: int) -> int:
+    # `type(...) is int` rather than isinstance: bool is a subclass of int, and a caller that sent
+    # `true` for a row limit made a mistake that must surface as one.
+    _require(type(value) is int, "PROBE_REQUEST_INVALID", f"{label} must be an integer")
+    _require(
+        minimum <= value <= maximum,
+        "PROBE_REQUEST_INVALID",
+        f"{label} must be in [{minimum}, {maximum}]",
+    )
+    return int(value)
+
+
+def _column_name(value: Any, label: str) -> str:
+    _require(
+        isinstance(value, str) and 1 <= len(value) <= 256,
+        "PROBE_REQUEST_INVALID",
+        f"{label} must be a string of 1..256 characters",
+    )
+    return str(value)
+
+
+def _column_list(value: Any, label: str) -> tuple[str, ...]:
+    _require(isinstance(value, list), "PROBE_REQUEST_INVALID", f"{label} must be an array")
+    _require(
+        1 <= len(value) <= MAX_PROFILE_COLUMNS,
+        "PROBE_REQUEST_INVALID",
+        f"{label} must name between 1 and {MAX_PROFILE_COLUMNS} columns",
+    )
+    names = tuple(_column_name(item, f"{label} entry") for item in value)
+    _require(len(set(names)) == len(names), "PROBE_REQUEST_INVALID", f"{label} repeats a column")
+    return names
+
+
+def _scalar(value: Any, label: str) -> Any:
+    if value is None or isinstance(value, bool):
+        return value
+    if isinstance(value, str):
+        _require(
+            len(value) <= MAX_CELL_CHARS,
+            "PROBE_REQUEST_INVALID",
+            f"{label} exceeds {MAX_CELL_CHARS} characters",
+        )
+        return value
+    if type(value) in {int, float}:
+        _require(
+            not isinstance(value, float) or math.isfinite(value),
+            "PROBE_REQUEST_INVALID",
+            f"{label} must be a finite number",
+        )
+        return value
+    raise ProbeVocabularyError("PROBE_REQUEST_INVALID", f"{label} is not an admitted literal")
+
+
+def _predicate(value: Any, *, depth: int) -> dict[str, Any]:
+    _require(
+        depth <= MAX_EXPRESSION_DEPTH,
+        "PROBE_EXPRESSION_TOO_DEEP",
+        f"predicate nests deeper than {MAX_EXPRESSION_DEPTH}",
+    )
+    node = _object(value, "predicate")
+    operator = node.get("op")
+    _require(isinstance(operator, str), "PROBE_REQUEST_INVALID", "predicate op must be a string")
+    if operator in COMPARISONS:
+        _exact_keys(node, {"op", "column", "value"}, set())
+        return {
+            "op": operator,
+            "column": _column_name(node["column"], "predicate column"),
+            "value": _scalar(node["value"], "predicate value"),
+        }
+    if operator in UNARY_TESTS:
+        _exact_keys(node, {"op", "column"}, set())
+        return {"op": operator, "column": _column_name(node["column"], "predicate column")}
+    if operator in {"and", "or"}:
+        _exact_keys(node, {"op", "operands"}, set())
+        operands = node["operands"]
+        _require(
+            isinstance(operands, list) and 1 <= len(operands) <= MAX_EXPRESSION_OPERANDS,
+            "PROBE_REQUEST_INVALID",
+            f"{operator} takes 1..{MAX_EXPRESSION_OPERANDS} operands",
+        )
+        return {
+            "op": operator,
+            "operands": [_predicate(item, depth=depth + 1) for item in operands],
+        }
+    if operator == "not":
+        _exact_keys(node, {"op", "operand"}, set())
+        return {"op": "not", "operand": _predicate(node["operand"], depth=depth + 1)}
+    raise ProbeVocabularyError(
+        "PROBE_REQUEST_INVALID", f"predicate op {operator!r} is not admitted"
+    )
+
+
+def probe_kind(value: Any) -> str:
+    """Admit one Studio probe kind, or refuse with the code the probe fails under."""
+
+    _require(
+        isinstance(value, str) and value in PROBE_KINDS,
+        "PROBE_KIND_UNSUPPORTED",
+        f"probe kind {value!r} is not in the vocabulary",
+    )
+    return str(value)
+
+
+def validate_probe_request(kind: str, request: Any) -> dict[str, Any]:
+    """Admit one probe request body and return it normalized, with defaults filled in.
+
+    Normalizing here rather than at each use is deliberate: the executor should never see an
+    absent ``scan_rows`` and choose a default of its own, because two executors choosing two
+    defaults is how a probe stops being reproducible.
+    """
+
+    kind = probe_kind(kind)
+    body = _object(request, "probe request")
+    encoded = canonical_json_bytes(body)
+    _require(
+        len(encoded) <= PROBE_REQUEST_MAX_BYTES,
+        "PROBE_REQUEST_TOO_LARGE",
+        f"probe request is {len(encoded)} canonical bytes, over {PROBE_REQUEST_MAX_BYTES}",
+    )
+    if kind == "source_inspect":
+        _exact_keys(body, {"source_id"}, {"scan_rows"})
+        return {
+            "source_id": _uuid_text(body["source_id"], "source_id"),
+            "scan_rows": _bounded_int(
+                body.get("scan_rows", DEFAULT_SCAN_ROWS),
+                "scan_rows",
+                minimum=1,
+                maximum=MAX_SCAN_ROWS,
+            ),
+        }
+    if kind == "sample_rows":
+        _exact_keys(body, {"source_id", "limit"}, {"offset", "columns"})
+        normalized: dict[str, Any] = {
+            "source_id": _uuid_text(body["source_id"], "source_id"),
+            "limit": _bounded_int(body["limit"], "limit", minimum=1, maximum=MAX_SAMPLE_ROWS),
+            "offset": _bounded_int(
+                body.get("offset", 0), "offset", minimum=0, maximum=MAX_SCAN_ROWS
+            ),
+        }
+        if "columns" in body:
+            normalized["columns"] = list(_column_list(body["columns"], "columns"))
+        return normalized
+    if kind == "profile_columns":
+        _exact_keys(body, {"source_id"}, {"scan_rows", "columns"})
+        profiled: dict[str, Any] = {
+            "source_id": _uuid_text(body["source_id"], "source_id"),
+            "scan_rows": _bounded_int(
+                body.get("scan_rows", DEFAULT_SCAN_ROWS),
+                "scan_rows",
+                minimum=1,
+                maximum=MAX_SCAN_ROWS,
+            ),
+        }
+        if "columns" in body:
+            profiled["columns"] = list(_column_list(body["columns"], "columns"))
+        return profiled
+    _exact_keys(body, {"source_id", "expression"}, {"scan_rows"})
+    expression = _object(body["expression"], "expression")
+    _exact_keys(expression, {"aggregate"}, {"column", "where"})
+    aggregate = expression["aggregate"]
+    _require(
+        isinstance(aggregate, str) and aggregate in AGGREGATES,
+        "PROBE_REQUEST_INVALID",
+        f"aggregate {aggregate!r} is not admitted",
+    )
+    normalized_expression: dict[str, Any] = {"aggregate": str(aggregate)}
+    if aggregate == "count":
+        # `count` over a column would silently mean one of two different things -- rows, or
+        # non-null values in that column -- so it takes no column at all and always means rows.
+        _require(
+            "column" not in expression,
+            "PROBE_REQUEST_INVALID",
+            "count takes no column; it counts matched rows",
+        )
+    else:
+        _require(
+            "column" in expression,
+            "PROBE_REQUEST_INVALID",
+            f"{aggregate} requires a column",
+        )
+        normalized_expression["column"] = _column_name(expression["column"], "expression column")
+    if "where" in expression:
+        normalized_expression["where"] = _predicate(expression["where"], depth=1)
+    return {
+        "source_id": _uuid_text(body["source_id"], "source_id"),
+        "scan_rows": _bounded_int(
+            body.get("scan_rows", DEFAULT_SCAN_ROWS), "scan_rows", minimum=1, maximum=MAX_SCAN_ROWS
+        ),
+        "expression": normalized_expression,
+    }
+
+
+def validate_probe_result(kind: str, result: Any) -> dict[str, Any]:
+    """Admit one probe result body before it is sent, so an over-budget answer is ours to refuse.
+
+    Studio bounds the result too. Checking here as well is not belt-and-braces: an answer refused
+    by Studio has already cost the probe its one settlement, and the probe cannot be answered
+    again. Refusing locally converts that into an ordinary ``failed`` outcome with a code.
+    """
+
+    kind = probe_kind(kind)
+    body = _object(result, "probe result")
+    encoded = canonical_json_bytes(body)
+    _require(
+        len(encoded) <= PROBE_RESULT_MAX_BYTES,
+        "PROBE_RESULT_TOO_LARGE",
+        f"probe result is {len(encoded)} canonical bytes, over {PROBE_RESULT_MAX_BYTES}",
+    )
+    schema = PROBE_RESULT_SCHEMA[kind]
+    required = set(schema["required"])
+    optional = set(schema["properties"]) - required
+    _exact_keys(body, required, optional)
+    _require(
+        body["schema_version"] == PROBE_SCHEMA_VERSION,
+        "PROBE_RESULT_INVALID",
+        "probe result schema_version is not this vocabulary",
+    )
+    _require(
+        body["probe_kind"] == kind,
+        "PROBE_RESULT_INVALID",
+        "probe result names a different kind than the probe",
+    )
+    return body
+
+
+def preview_cell(value: Any) -> Any:
+    """Render one parsed cell as a JSON-safe preview value.
+
+    A parsed cell can be a decimal, a date, or a very long string; a probe answer is a preview and
+    must be small, canonical-JSON encodable, and finite. Anything that is not already an admitted
+    literal is rendered as its ``str`` and truncated, and truncation is visible in the string
+    rather than silent, because a preview that lies about being complete is worse than no preview.
+    """
+
+    if value is None or isinstance(value, bool):
+        return value
+    if type(value) is int:
+        # Canonical JSON refuses integers outside the exactly representable range; a count that
+        # cannot survive the wire is reported as text rather than rounded.
+        return value if abs(value) <= 2**53 - 1 else f"{value}"[:MAX_CELL_CHARS]
+    if type(value) is float:
+        return value if math.isfinite(value) else None
+    text = value if isinstance(value, str) else str(value)
+    if len(text) > MAX_CELL_CHARS:
+        return text[: MAX_CELL_CHARS - 1] + "…"
+    return text
+
+
+def inferred_type(values: Sequence[Any]) -> str:
+    """Name the one type a column's scanned values share, or ``mixed``/``null``."""
+
+    seen: set[str] = set()
+    for value in values:
+        if value is None:
+            continue
+        if isinstance(value, bool):
+            seen.add("boolean")
+        elif type(value) is int:
+            seen.add("integer")
+        elif type(value) is float:
+            seen.add("number")
+        elif isinstance(value, str):
+            seen.add("string")
+        else:
+            seen.add("string")
+        if len(seen) > 1:
+            return "mixed"
+    if not seen:
+        return "null"
+    return seen.pop()
+
+
+def _compare(cell: Any, literal: Any) -> int | None:
+    """Order one cell against one literal, or ``None`` when the two are not comparable.
+
+    Incomparable is a third answer rather than an exception or a coerced ``False``: a predicate
+    over a mixed column must exclude the rows it cannot judge, and must not decide that a string
+    is less than a number on the strength of Python's willingness to say so (it is not, and in
+    Python 3 it raises).
+    """
+
+    if cell is None or literal is None:
+        return None
+    if isinstance(cell, bool) != isinstance(literal, bool):
+        return None
+    if isinstance(cell, bool):
+        return (cell > literal) - (cell < literal)
+    numeric = (int, float)
+    if type(cell) in numeric and type(literal) in numeric:
+        return (cell > literal) - (cell < literal)
+    if isinstance(cell, str) and isinstance(literal, str):
+        return (cell > literal) - (cell < literal)
+    return None
+
+
+def evaluate_predicate(predicate: Mapping[str, Any], row: Mapping[str, Any]) -> bool:
+    """Decide one validated predicate against one row. Total, and never raises on data."""
+
+    operator = predicate["op"]
+    if operator in {"and", "or"}:
+        results = (evaluate_predicate(item, row) for item in predicate["operands"])
+        return all(results) if operator == "and" else any(results)
+    if operator == "not":
+        return not evaluate_predicate(predicate["operand"], row)
+    # A predicate naming a column the source does not have is False for every row rather than an
+    # error. The column list is already in the source_inspect answer, so a caller that wants the
+    # difference between "no such column" and "no matching row" can see it there; failing the
+    # whole probe instead would make an exploratory typo cost a round trip.
+    cell = row.get(predicate["column"])
+    if operator == "is_null":
+        return cell is None
+    if operator == "is_not_null":
+        return cell is not None
+    order = _compare(cell, predicate["value"])
+    if order is None:
+        return False
+    return {
+        "eq": order == 0,
+        "ne": order != 0,
+        "lt": order < 0,
+        "le": order <= 0,
+        "gt": order > 0,
+        "ge": order >= 0,
+    }[operator]