mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/serving_edge.py

@@ -0,0 +1,590 @@
+"""The serving edge: the key, then the quota, then the read, and never out of order.
+
+This module puts two checks in front of every data read, in the only order that makes either check
+meaningful:
+
+1. **The key is verified.** Either it arrived already verified from the Studio API edge, or it is
+   verified here against cloud's verify surface through :mod:`key_seam`.
+2. **The quota is reserved.** A slot and its declared cost are charged to
+   :class:`governors.CapLedger` before anything is read.
+3. **Only then is anything read.** :func:`serving.describe_dataset` and :func:`serving.serve_rows`
+   are entered after both gates have passed and never before.
+
+``hosted_bootstrap.launch`` already established this discipline on the build side: the gate sits at
+the first moment the tenant coordinate is known and before anything is allocated for the work, so a
+refused run "creates no descriptor, holds no memory, and above all never reaches execve". The same
+sentence in this surface's words: **a refused READ opens no run directory, reads no Parquet, and
+allocates no buffer.** That is a property of the call order in :func:`serve_read`, and
+``tests/test_serving_edge.py`` proves it by instrumenting the read core and asserting it is never
+entered.
+
+**Nothing here is a second implementation of anything.** The key check is :mod:`key_seam`, which is
+a complete fail-closed verifier whose real enforcement point is already recorded in
+:data:`key_seam.CONSUMER_CALL_SITE`; this module adds :data:`SERVING_CONSUMER_CALL_SITE` beside it
+and invents no second auth mechanism. The quota is :class:`governors.CapLedger`, and this surface is
+the caller of its ``"key"`` subject.
+
+**This is the only module on the serving path permitted to reach the network, and it reaches exactly
+one place:** cloud's verify surface, over https, through :func:`key_seam.verify_api_key`. The
+carve-out is named here because an unexplained exception in a security ban is how the ban rots.
+``serving.py`` reaches nothing; it reads sealed
+bytes off a local run directory and that is all it can do.
+
+**Nothing here interprets a dataset.** The edge decides whether a caller may read; ``serving.py``
+decides what a read answers. No field of a filter, a pin or a schema is examined in this file, and a
+refusal produced here names a credential or a cap and never a column.
+
+**Two topologies, both supported, and the module says which is which rather than assuming.**
+
+* **PRODUCTION.** The Studio API edge verifies the customer key before this function runs. Without
+  a verified key id, the read is refused.
+* **LOCAL proof.** Verification runs in process against a configured https verify URL, through
+  :func:`key_seam.verify_api_key`.
+
+There is no third mode in which verification is off. A cap a caller can switch off is not a cap
+(``hosted_bootstrap.py:629-631``), and the same is true one gate over. No parameter, no argument and
+no environment variable read by this module turns either check off, and
+``tests/test_serving_edge.py`` asserts that over the signature and over the source rather than
+leaving it to a reader's goodwill.
+
+**The verify transport is passed through and never interpreted.** :func:`serve_read` forwards the
+``transport`` parameter to :func:`key_seam.verify_api_key`. The transport supplies response bytes;
+``key_seam`` computes the verdict. This module must not inspect or branch on the transport.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import replace
+from datetime import datetime
+from functools import wraps
+from pathlib import Path
+from typing import Any
+
+from mostlyright.data_harness import key_seam, serving
+from mostlyright.data_harness.governors import (
+    KEY_ID_PATTERN,
+    CapExceeded,
+    CapLedger,
+    CapPolicy,
+    CapStoreError,
+    FileCapStore,
+)
+
+#: Where a presented API key is actually refused or allowed for a SERVING read, recorded in code for
+#: the reason :data:`key_seam.CONSUMER_CALL_SITE` is: the check runs somewhere this repository does
+#: not contain, and an unrecorded consumer reads as a missing one.
+#:
+#: In production the customer key is verified at the **Studio API edge**, before a serving request
+#: reaches the harness at all, and :func:`serve_read` receives the resulting key id. The
+#: harness-side implementation in this module is the reference for that check and the local proof of
+#: it — the same posture ``key_seam`` holds on the build side, one surface over.
+SERVING_CONSUMER_CALL_SITE = (
+    "mostlyright-studio API edge verifies the customer key before a serving request reaches the "
+    "harness; serving_edge.serve_read is the harness-side reference implementation and the local "
+    "proof of that check"
+)
+
+#: What this deployment declares one READ costs, in cost units (one cent each). See
+#: :func:`declared_read_cost_units`. Deliberately NOT ``hosted_bootstrap.RUN_COST_UNITS_ENV``: a
+#: read and a build run are different work at different prices, and one variable for both would make
+#: pricing a read impossible without repricing every build.
+READ_COST_UNITS_ENV = "MOSTLYRIGHT_READ_COST_UNITS"
+
+#: The path of the cap store the SERVING ledger counts in. Deliberately NOT
+#: ``hosted_bootstrap.CAP_STORE_ENV``, and the separation is load-bearing rather than tidy: both
+#: ledgers file 16-lowercase-hex coordinates into structurally identical files, and
+#: :data:`governors.KEY_ID_PATTERN` cannot tell a workspace hash from an API key id. One file
+#: holding both would let a workspace's builds and a key's reads share a counter — a tenant's build
+#: allowance silently spent by somebody else's reads, with nothing anywhere raising.
+SERVING_CAP_STORE_ENV = "MOSTLYRIGHT_SERVING_CAP_STORE"
+
+#: The refusal code a credential refusal carries, in the bracketed idiom every ``serving.py``
+#: refusal already uses. A transport maps it to 401; nothing else may.
+CREDENTIAL_REFUSAL_CODE = "SERVING_CREDENTIAL"
+
+#: The refusal code a reached cap carries. A transport maps it to 429.
+QUOTA_REFUSAL_CODE = "SERVING_QUOTA"
+
+#: The refusal code counters that could not be read carry. It is distinct from
+#: :data:`QUOTA_REFUSAL_CODE` on purpose: "this key has used its allowance" and "this deployment
+#: cannot tell what this key has used" are different facts for an operator, and only the first one
+#: is the product working.
+QUOTA_UNREADABLE_REFUSAL_CODE = "SERVING_QUOTA_UNREADABLE"
+
+#: The refusal code a misconfigured declared read cost carries.
+READ_COST_REFUSAL_CODE = "SERVING_READ_COST"
+
+#: The refusal code a read asked for in a shape this surface does not answer carries.
+READ_SHAPE_REFUSAL_CODE = "SERVING_READ_SHAPE"
+
+#: Every security scheme ``mostlyright-studio/contracts/openapi/studio-v3.yaml`` declares today,
+#: read off that document and recorded here as data so :data:`STUDIO_WIRE_BINDING`'s claim is
+#: checkable rather than rhetorical. Not one of them is an ``x-api-key`` scheme, and the contract
+#: declares no path for a keyed data read. These are FOREIGN identifiers quoted from another
+#: repository's contract, so they are not bound by ``docs/VOCABULARY.md`` the way a sentence this
+#: surface emits is; nothing here reaches a response.
+STUDIO_SECURITY_SCHEMES = (
+    "userBearer",
+    "automationBearer",
+    "interactiveStepUp",
+    "producerCapability",
+    "verifierCapability",
+    "studioController",
+)
+
+#: The current Studio contract has no keyed data-read path. Adding one requires a Studio contract
+#: update, generated-client refresh, and rotation of
+#: :data:`studio_boundary.PINNED_OPENAPI_SOURCE_SHA256`.
+STUDIO_WIRE_BINDING = (
+    "studio-v3.yaml declares six bearer security schemes and no x-api-key scheme, and no path for "
+    "a keyed data read; this surface therefore has no wire binding in the Studio contract yet. "
+    "Writing one means a Studio branch, a client regeneration and a rotation of "
+    "studio_boundary.PINNED_OPENAPI_SOURCE_SHA256, and it belongs to the staging apply"
+)
+
+#: The two shapes a read may take. Closed, and the same two functions ``serving.py`` exports: the
+#: edge routes to one of them and can invent neither a third shape nor a variant of these two.
+READ_SHAPES = ("describe", "rows")
+
+
+class ServingEdgeError(RuntimeError):
+    """The edge is misconfigured, so no read may be decided from it.
+
+    Raised only for an operator configuration fault — a declared read cost that is not a whole
+    number of cost units. It is never a rejected caller: a rejected caller is a refusing
+    :class:`serving.ServingResult`, exactly as a rejected key is a denying
+    :class:`key_seam.KeyVerdict` rather than an exception.
+
+    Like everything else on this path, the message never contains a credential.
+    """
+
+
+def declared_read_cost_units() -> int:
+    """Return what this deployment says one read costs, or refuse a value nobody wrote.
+
+    Same character as ``hosted_bootstrap.declared_run_cost_units``, and the same honest gap, one
+    work item over: this is a **declared budget, not a measurement**. Nothing on this path can
+    observe what a read really costs, so what it can do is charge the monthly spend ledger the
+    amount the operator says one read is worth at worst — reserve the worst case, admit only if it
+    fits.
+
+    - **Unset** — every read is charged zero, so the monthly spend ceiling in
+      :class:`governors.CapPolicy` cannot trip no matter how many reads are admitted. This is a real
+      gap, not a degraded-but-safe default. The monthly read allowance still applies where
+      :data:`SERVING_CAP_STORE_ENV` names shared storage (:func:`serving_ledger`). The concurrency
+      cap does not apply across one-process-per-request workers.
+    - **Set to a whole number of cost units** — each admitted read reserves that much against the
+      monthly ceiling before anything is read and commits the same amount on the way out, so the
+      ceiling binds at ``max_monthly_cost_units / declared`` reads.
+
+    A value that cannot be read as a whole number of cost units refuses the read rather than
+    defaulting to zero: "this budget is misconfigured" and "this read is free" must never be the
+    same answer.
+
+    Raises:
+        ServingEdgeError: when the variable is set to something that is not a whole number.
+    """
+
+    configured = os.environ.get(READ_COST_UNITS_ENV)
+    if configured is None or configured == "":
+        return 0
+    # str.isdigit is the check rather than int(): it refuses the signs, the underscores, the
+    # surrounding whitespace and the unicode digits that int() would otherwise accept and turn
+    # into a number nobody wrote.
+    if not configured.isascii() or not configured.isdigit():
+        raise ServingEdgeError(
+            f"{READ_COST_UNITS_ENV} must be a whole number of cost units, zero or more"
+        )
+    return int(configured)
+
+
+def serving_ledger(*, policy: CapPolicy | None = None) -> CapLedger:
+    """Build the ledger the serving gate charges, and say what it actually enforces.
+
+    The ledger counts by ``subject="key"`` and ``work_unit="read"``. Both nouns are declarations and
+    neither can be inferred: a 16-lowercase-hex coordinate looks identical whether a workspace or an
+    API key was hashed into it, and a counter looks identical whether it counted builds or reads. A
+    customer refused a read who is told they have used their monthly RUN allowance is being sent to
+    a different product surface to look for a number that will not be there, which is the failure
+    :data:`governors.CAP_SUBJECTS` and :data:`governors.CAP_WORK_UNITS` exist to prevent.
+
+    **The store is separate from the worker's, and that is not tidiness.** This ledger is backed by
+    :data:`SERVING_CAP_STORE_ENV` and the build-side admission ledger by
+    ``hosted_bootstrap.CAP_STORE_ENV``. Both write structurally identical files keyed by 16-hex
+    coordinates, and :data:`governors.KEY_ID_PATTERN` accepts either kind. Pointed at one file they
+    would share counters: a workspace's build allowance would be spent by some key's reads, and
+    nothing on either side would raise. The two variables must therefore name two paths.
+
+    **The honest state of the ceiling.** ``governors.MAX_RUNS_PER_MONTH`` bounds work items per
+    calendar month per coordinate whatever the work item is called, so what this product enforces
+    today is **10,000 reads per key per month**, and for a production query API that is low. Raising
+    it is not a wording decision and is not taken here: the same constant bounds the build-side
+    allowance, so raising it weakens that cap too. Separate read counters require a
+    ``governors.CAP_STORE_SCHEMA`` migration.
+
+    With :data:`SERVING_CAP_STORE_ENV` unset the counters live in this process only, so the monthly
+    read allowance is not enforced across processes at all — the same real gap
+    ``hosted_bootstrap.admission_ledger`` records for the build side.
+
+    Raises:
+        CapStoreError: when the configured store cannot be read. It is deliberately allowed to
+            propagate out of construction: a ledger over counters that cannot be read must fail
+            where the caller can still refuse the read, rather than succeed with empty counters and
+            admit everything.
+    """
+
+    configured = os.environ.get(SERVING_CAP_STORE_ENV)
+    if configured:
+        return CapLedger(
+            policy,
+            store=FileCapStore(Path(configured)),
+            subject="key",
+            work_unit="read",
+        )
+    return CapLedger(policy, subject="key", work_unit="read")
+
+
+def _refused(dataset_id: Any, pin: Any, reason: str, code: str) -> serving.ServingResult:
+    """Turn one edge refusal into the one envelope every serving caller already renders.
+
+    Both digest fields are null and that is the honest answer: a refusal taken at the key or at the
+    cap never resolved a pin, so there is no version to name and inventing one would be worse than
+    saying nothing. A refusal taken INSIDE the read core comes back from ``serving.py`` instead,
+    already carrying the version the pin bound.
+
+    The bracketed code is appended, never substituted into the sentence: a governors' refusal must
+    reach a customer in the governors' own words (``deploy.py:390-393`` is the same refusal to write
+    a second wording of one fact), and a transport needs a machine handle to map onto a status code.
+    """
+
+    return _envelope(dataset_id, pin, (f"{reason} [{code}]",))
+
+
+def _envelope(dataset_id: Any, pin: Any, refusals: tuple[str, ...]) -> serving.ServingResult:
+    """The one refusing envelope this module builds, whatever declined the read.
+
+    What the caller asked for is echoed through ``serving._asked_for`` and never straight out of the
+    argument: that function holds the plain-line rule and the length bound the library's own
+    grammar owns, and a second, weaker coercion here would be the transport bound and the library
+    bound disagreeing inside one process.
+    """
+
+    return serving.ServingResult(
+        ok=False,
+        refusals=refusals,
+        status=serving.STATUS_REFUSED,
+        dataset_id=serving._asked_for(dataset_id, serving.MAX_DATASET_ID_CHARS),
+        pin=serving._asked_for(pin, serving.MAX_PIN_CHARS),
+        pin_kind=None,
+        version_id=None,
+        version_number=None,
+        version_digest=None,
+        table_digest=None,
+        payload=None,
+    )
+
+
+def v3_coordinates(
+    result: serving.ServingResult, parent_dataset_id: Any, table_id: Any
+) -> serving.ServingResult:
+    """Render a V3 envelope with its requested Dataset parent and Table child.
+
+    The read core remains historical table-only.  This single adapter belongs at the V3 edge so
+    every refusal -- including one taken before authentication, during an index refresh, or while
+    translating a core exception -- carries the same two requested coordinates.
+    """
+
+    table = serving._asked_for(table_id, serving.MAX_DATASET_ID_CHARS)
+    return replace(
+        result,
+        dataset_id=serving._asked_for(parent_dataset_id, serving.MAX_DATASET_ID_CHARS),
+        table_id=table or None,
+    )
+
+
+def _preserve_v3_coordinates(function: Any) -> Any:
+    """Apply V3 Dataset/Table rendering after every return from one read path."""
+
+    @wraps(function)
+    def wrapped(
+        index: serving.VersionIndex, dataset_id: str, pin: str, *args: Any, **kwargs: Any
+    ) -> serving.ServingResult:
+        result = function(index, dataset_id, pin, *args, **kwargs)
+        if kwargs.get("api_version") == "v3":
+            return v3_coordinates(result, kwargs.get("parent_dataset_id"), dataset_id)
+        return result
+
+    return wrapped
+
+
+def _verified_upstream_key_id(value: Any) -> str | None:
+    """Return an already-verified key id, or nothing when it is not one.
+
+    The Studio API edge verifies the customer key before this process receives the request. The key
+    id is checked
+    against :data:`governors.KEY_ID_PATTERN` — the same check that makes it impossible to file a raw
+    credential where an identifier belongs, since no credential this product mints is 16 lowercase
+    hex characters.
+    """
+
+    if isinstance(value, str) and KEY_ID_PATTERN.match(value) is not None:
+        return value
+    return None
+
+
+def _read(
+    index: serving.VersionIndex,
+    dataset_id: str,
+    pin: str,
+    *,
+    shape: str,
+    predicates: Any,
+    offset: int,
+    limit: int,
+    max_bytes: int | None,
+) -> serving.ServingResult:
+    """Enter the read core. Reached only after both gates have passed, and never before.
+
+    Nothing is decided here. The shape was already checked against :data:`READ_SHAPES`, so this is a
+    routing step onto the two functions ``serving.py`` exports and it can invent no third.
+    """
+
+    if shape == "describe":
+        return serving.describe_dataset(index, dataset_id, pin)
+    return serving.serve_rows(
+        index,
+        dataset_id,
+        pin,
+        predicates=predicates,
+        offset=offset,
+        limit=limit,
+        max_bytes=max_bytes,
+    )
+
+
+@_preserve_v3_coordinates
+def serve_read(
+    index: serving.VersionIndex,
+    dataset_id: str,
+    pin: str,
+    *,
+    shape: str,
+    ledger: CapLedger,
+    now: datetime,
+    index_path: Path | None = None,
+    verified_key_id: str | None = None,
+    key: str | None = None,
+    verify_url: str | None = None,
+    transport: key_seam.VerifyTransport | None = None,
+    predicates: Any = None,
+    offset: int = 0,
+    limit: int = serving.MAX_SERVED_ROWS,
+    max_bytes: int | None = None,
+    parent_dataset_id: str | None = None,
+    api_version: str = "historical",
+) -> serving.ServingResult:
+    """Verify the key, reserve the quota, and only then read. Never in any other order.
+
+    Exactly one credential form must be supplied:
+
+    * ``verified_key_id`` — PRODUCTION. The Studio API edge already verified the customer key and
+      this is the key id it produced. Its shape is checked and nothing is re-verified, because the
+      key itself never reached this process.
+    * ``key`` with ``verify_url`` — the LOCAL proof. The key is verified in process against cloud's
+      verify surface through :func:`key_seam.verify_api_key`.
+
+    Both together are refused rather than one being picked, and neither is refused too: a read with
+    no credential is a read by nobody.
+
+    ``index_path`` is how ``current`` stays current in a process that outlives a move of Current.
+    Given one, the document is read again through :func:`serving.read_version_index` for THIS read,
+    and the ``index`` argument is the copy the caller parsed at start-up — kept as the argument that
+    proves the document was readable before a socket existed, and superseded for the read itself. It
+    is read INSIDE the reservation, after both gates, so an unverified caller still causes no
+    filesystem access at all, and an index that has become unreadable or invalid refuses under the
+    same counted read as any other refusal. Without it, the passed ``index`` is what the read
+    resolves against, and ``current`` then means current as of whenever that value was parsed.
+
+    ``ledger`` and ``now`` are explicit so a test can drive them. Neither is an off-switch: there is
+    no ledger a caller can pass that admits more than its policy allows, and there is no value of
+    ``now`` at which the key check does not run.
+
+    The gate order is the whole contract, and every line of it is asserted rather than described. A
+    refused read **opens no run directory, reads no Parquet, and allocates no buffer** — the same
+    sentence ``hosted_bootstrap.launch`` earns on the build side, where a refused run "creates no
+    descriptor, holds no memory, and above all never reaches execve".
+
+    Returns:
+        A :class:`serving.ServingResult` — the one envelope, answering or refusing. A refusal from
+        either gate carries null digests, because no version was bound; a refusal from inside the
+        read core carries whatever ``serving.py`` bound before it declined.
+    """
+
+    if api_version not in {"historical", "v3"}:
+        return _refused(
+            dataset_id,
+            pin,
+            "this read does not name a supported serving contract",
+            READ_SHAPE_REFUSAL_CODE,
+        )
+    if api_version == "v3" and parent_dataset_id is None:
+        return _refused(
+            dataset_id,
+            pin,
+            "a V3 read must name both its Dataset parent and Table child "
+            "[SERVING_TABLE_SCOPE_MISMATCH]",
+            "SERVING_TABLE_SCOPE_MISMATCH",
+        )
+    if shape not in READ_SHAPES:
+        return _refused(
+            dataset_id,
+            pin,
+            "a read asks a dataset to describe itself or to hand back rows, and nothing else",
+            READ_SHAPE_REFUSAL_CODE,
+        )
+
+    if parent_dataset_id is not None and index.table(parent_dataset_id, dataset_id) is None:
+        return _refused(
+            dataset_id,
+            pin,
+            "the requested Dataset/Table pair is not listed [SERVING_TABLE_SCOPE_MISMATCH]",
+            "SERVING_TABLE_SCOPE_MISMATCH",
+        )
+
+    # Verify the key before any read work.
+    # Nothing below this block runs for a caller who is not allowed to be here.
+    if verified_key_id is not None and key is not None:
+        return _refused(
+            dataset_id,
+            pin,
+            "a read presents an already-verified key or a key to verify, never both",
+            CREDENTIAL_REFUSAL_CODE,
+        )
+    if verified_key_id is not None:
+        upstream = _verified_upstream_key_id(verified_key_id)
+        if upstream is None:
+            return _refused(
+                dataset_id,
+                pin,
+                "this read did not present a usable credential",
+                CREDENTIAL_REFUSAL_CODE,
+            )
+        key_id = upstream
+    elif key is not None:
+        if not isinstance(verify_url, str) or not verify_url:
+            return _refused(
+                dataset_id,
+                pin,
+                "this deployment cannot verify a key, so no read was served",
+                CREDENTIAL_REFUSAL_CODE,
+            )
+        try:
+            # The verdict belongs to key_seam, which denies on any non-200, any redirect, any
+            # transport fault, any non-strict-JSON or oversized body, and any body whose key id does
+            # not match the presented key — so a transport can be refused but cannot be laundered
+            # into an allow. A branch here on what the transport is would be the beginning of a
+            # second verifier, which is the thing this module exists not to build.
+            verdict = key_seam.verify_api_key(key, base_url=verify_url, transport=transport)
+        except key_seam.KeySeamError:
+            return _refused(
+                dataset_id,
+                pin,
+                "this deployment cannot verify a key, so no read was served",
+                CREDENTIAL_REFUSAL_CODE,
+            )
+        if not verdict.ok:
+            return _refused(dataset_id, pin, verdict.reason, CREDENTIAL_REFUSAL_CODE)
+        key_id = verdict.key_id
+    else:
+        return _refused(
+            dataset_id,
+            pin,
+            "this read presented no credential",
+            CREDENTIAL_REFUSAL_CODE,
+        )
+
+    # The raw key stops HERE. It went into key_seam and into nothing else, and unbinding the name
+    # makes that a property of the function rather than a promise about it: any later line that
+    # reached for it would raise instead of carrying a credential further into the read path.
+    del key
+
+    # Reserve quota after authentication and before opening data.
+    try:
+        cost_units = declared_read_cost_units()
+    except ServingEdgeError:
+        # The operator's sentence names the variable and stays in the exception, where an operator
+        # reads it. What a customer gets back says the deployment could not price the read and
+        # names no environment variable: a response is not a place to publish deployment internals.
+        return _refused(
+            dataset_id,
+            pin,
+            "this deployment cannot price a read, so no read was served",
+            READ_COST_REFUSAL_CODE,
+        )
+    try:
+        reservation = ledger.reserve(key_id, now=now, estimated_cost_units=cost_units)
+    except CapExceeded as error:
+        # Preserve the governor's refusal text so all read-cap callers report the same reason.
+        return _refused(dataset_id, pin, str(error), QUOTA_REFUSAL_CODE)
+    except CapStoreError as error:
+        # Fail closed, exactly as ``hosted_bootstrap._reserve_run_slot`` does. Counters that cannot
+        # be read are not counters that say zero.
+        return _refused(dataset_id, pin, str(error), QUOTA_UNREADABLE_REFUSAL_CODE)
+
+    # Perform the read only while its quota reservation is held.
+    # Inside the reservation's block, so a fault gives the slot back instead of leaving it held by a
+    # read that never happened.
+    with reservation:
+        try:
+            bound = index if index_path is None else serving.read_version_index(index_path)
+        except serving.ServingRefused as refusal:
+            # An index that stopped being readable or valid while this process ran is a refusal
+            # with the reader's own reasons, not a fault: the module's contract is that a corrupt
+            # index can only ever make a read decline. It is still committed below, because the
+            # gates ran.
+            result = _envelope(dataset_id, pin, refusal.reasons)
+        else:
+            if parent_dataset_id is not None and bound.table(parent_dataset_id, dataset_id) is None:
+                result = _refused(
+                    dataset_id,
+                    pin,
+                    "the requested Dataset/Table pair is not listed [SERVING_TABLE_SCOPE_MISMATCH]",
+                    "SERVING_TABLE_SCOPE_MISMATCH",
+                )
+                reservation.commit(actual_cost_units=cost_units)
+                return result
+            result = _read(
+                bound,
+                dataset_id,
+                pin,
+                shape=shape,
+                predicates=predicates,
+                offset=offset,
+                limit=limit,
+                max_bytes=max_bytes,
+            )
+        # Committed whether the core answered or declined, because either way the read path ran and
+        # the work was done. Refunding a refusal would let a caller drive the whole verification and
+        # replay path without bound for free, which is the cap this gate exists to hold.
+        reservation.commit(actual_cost_units=cost_units)
+    return result
+
+
+__all__ = [
+    "CREDENTIAL_REFUSAL_CODE",
+    "QUOTA_REFUSAL_CODE",
+    "QUOTA_UNREADABLE_REFUSAL_CODE",
+    "READ_COST_REFUSAL_CODE",
+    "READ_COST_UNITS_ENV",
+    "READ_SHAPES",
+    "READ_SHAPE_REFUSAL_CODE",
+    "SERVING_CAP_STORE_ENV",
+    "SERVING_CONSUMER_CALL_SITE",
+    "STUDIO_SECURITY_SCHEMES",
+    "STUDIO_WIRE_BINDING",
+    "ServingEdgeError",
+    "declared_read_cost_units",
+    "serve_read",
+    "serving_ledger",
+]