sable-sphynx 0.7.0.dev0__py3-none-any.whl

sphynx/clickhouse_reader.py

@@ -0,0 +1,169 @@
+"""Optional fixed-view snapshot reads with explicit separate credentials.
+
+No environment, API-token, cloud-secret, raw-SQL or writer integration exists.
+The operator must provision a fixed-scope read-only role before using this API.
+"""
+from __future__ import annotations
+
+import base64
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+import http.client
+import ipaddress
+import math
+import re
+import ssl
+from urllib.parse import SplitResult, urlencode, urlsplit
+
+from ._analytical_values import identifier, parse_json, require
+from .analytical_views import ProjectionEventRef, ProjectionPage, ProjectionResult, ProjectionRow
+from .workflow_contracts import WorkflowContractError
+
+_COLUMNS = ('team_id', 'event_id', 'row_id', 'row_hash', 'row_kind', 'record_id',
+            'bank_id', 'release_id', 'cohort_id', 'source_version', 'summary_json',
+            'source_digest', 'plan_digest', 'manifest_digest', 'row_count', 'commit_hash')
+_MAX_RESPONSE = 16 * 1024 * 1024
+
+
+class ReadOnlyClickHouseError(RuntimeError):
+    """Safe connector failure. Credentials and raw response bodies stay hidden."""
+    def __init__(self, code: str):
+        self.code = code
+        super().__init__(code + ': the fixed-view snapshot read could not be verified')
+
+
+@dataclass(frozen=True)
+class ReadOnlyClickHouseConfig:
+    endpoint: str = field(repr=False)
+    database: str
+    view: str
+    username: str = field(repr=False)
+    password: str = field(repr=False)
+    team_id: str
+    bank_id: str
+    release_id: str
+    cohort_id: str
+    connect_proxy: str | None = field(default=None, repr=False)
+    timeout: float = 30
+    allow_local_http: bool = False
+    _target: SplitResult = field(init=False, repr=False)
+    _port: int = field(init=False, repr=False)
+    _proxy: tuple[str, int] | None = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        try:
+            require(type(self.endpoint) is str and 1 <= len(self.endpoint) <= 2048
+                    and not any(char.isspace() or ord(char) < 32 for char in self.endpoint))
+            target = urlsplit(self.endpoint)
+            require(target.hostname and target.path in ('', '/') and not target.username
+                    and not target.password and not target.query and not target.fragment)
+            require(type(self.allow_local_http) is bool)
+            require(target.scheme == 'https' or self.allow_local_http and target.scheme == 'http'
+                    and target.hostname in ('localhost', '127.0.0.1', '::1'))
+            port = target.port or (443 if target.scheme == 'https' else 80)
+            require(1 <= port <= 65535)
+            require(type(self.database) is str and re.fullmatch('[a-z][a-z0-9_]{0,63}', self.database))
+            require(type(self.view) is str and re.fullmatch('sphynx_ro_[a-z][a-z0-9_]{0,47}', self.view))
+            for name in ('team_id', 'bank_id', 'release_id', 'cohort_id'):
+                identifier(getattr(self, name))
+            require(type(self.timeout) in (int, float) and math.isfinite(self.timeout) and 0 < self.timeout <= 120)
+            require(type(self.username) is str and type(self.password) is str
+                    and bool(self.username) and bool(self.password) and ':' not in self.username
+                    and len(self.username.encode('utf-8')) <= 256 and len(self.password.encode('utf-8')) <= 4096
+                    and not any(ord(char) < 32 or ord(char) == 127 for char in self.username + self.password))
+            proxy_address = None
+            if self.connect_proxy is not None:
+                require(type(self.connect_proxy) is str and len(self.connect_proxy) <= 2048
+                        and not any(char.isspace() or ord(char) < 32 for char in self.connect_proxy))
+                proxy = urlsplit(self.connect_proxy)
+                address = ipaddress.ip_address(proxy.hostname or '')
+                require(proxy.scheme == 'http' and address.version == 4
+                        and any(address in ipaddress.ip_network(net) for net in
+                                ('10.0.0.0/8', '172.16.0.0/12', '192.168.0.0/16'))
+                        and proxy.port and proxy.path in ('', '/') and not proxy.username
+                        and not proxy.password and not proxy.query and not proxy.fragment and target.scheme == 'https')
+                assert proxy.port is not None
+                proxy_address = (str(address), proxy.port)
+            object.__setattr__(self, '_target', target)
+            object.__setattr__(self, '_port', port)
+            object.__setattr__(self, '_proxy', proxy_address)
+        except (WorkflowContractError, ValueError, TypeError, UnicodeError, AttributeError):
+            raise ReadOnlyClickHouseError('invalid_readonly_clickhouse_config') from None
+
+
+class ClickHouseReader:
+    """Read only known references through one operator-approved fixed view."""
+    def __init__(self, config: ReadOnlyClickHouseConfig):
+        if not isinstance(config, ReadOnlyClickHouseConfig):
+            raise ReadOnlyClickHouseError('invalid_readonly_clickhouse_config')
+        self._config = config
+
+    def __repr__(self) -> str:
+        return f'ClickHouseReader(database={self._config.database!r}, view={self._config.view!r})'
+
+    def _read(self, refs: tuple[ProjectionEventRef, ...]) -> str:
+        config = self._config
+        sql = ('SELECT DISTINCT ' + ','.join(_COLUMNS) + ' FROM ' + config.database + '.' + config.view
+            + ' WHERE team_id={team:String} AND bank_id={bank:String} AND release_id={release:String}'
+            + " AND (cohort_id={cohort:String} OR (row_kind='audit' AND cohort_id=''))"
+            + " AND event_id IN splitByChar(',',{events:String}) LIMIT 4097 FORMAT JSONEachRow")
+        query = {'database': config.database, 'readonly': '1', 'max_execution_time': '15',
+                 'max_result_rows': '4097', 'output_format_json_quote_64bit_integers': '0',
+                 'param_team': config.team_id, 'param_bank': config.bank_id,
+                 'param_release': config.release_id, 'param_cohort': config.cohort_id,
+                 'param_events': ','.join(ref.event_id for ref in refs)}
+        connection: http.client.HTTPConnection | None = None
+        try:
+            assert config._target.hostname is not None
+            if config._target.scheme == 'https':
+                host, port = config._proxy or (config._target.hostname, config._port)
+                connection = http.client.HTTPSConnection(host, port, timeout=config.timeout,
+                                                         context=ssl.create_default_context())
+                if config._proxy:
+                    connection.set_tunnel(config._target.hostname, config._port)
+            else:
+                connection = http.client.HTTPConnection(config._target.hostname, config._port, timeout=config.timeout)
+            authorization = 'Basic ' + base64.b64encode((config.username + ':' + config.password).encode('utf-8')).decode('ascii')
+            connection.request('POST', '/?' + urlencode(query), body=sql.encode('utf-8'),
+                headers={'Authorization': authorization, 'Content-Type': 'text/plain; charset=utf-8'})
+            with connection.getresponse() as response:
+                if response.status != 200:
+                    raise ReadOnlyClickHouseError('readonly_clickhouse_unavailable')
+                raw = response.read(_MAX_RESPONSE + 1)
+                if len(raw) > _MAX_RESPONSE:
+                    raise ReadOnlyClickHouseError('readonly_clickhouse_response_too_large')
+                return raw.decode('utf-8')
+        except (OSError, ValueError, UnicodeError, http.client.HTTPException):
+            raise ReadOnlyClickHouseError('readonly_clickhouse_unavailable') from None
+        finally:
+            if connection is not None:
+                connection.close()
+
+    def read_events(self, refs: Sequence[ProjectionEventRef]) -> ProjectionPage:
+        """Return historical snapshots. No current review/acceptance authority."""
+        require(isinstance(refs, (tuple, list)) and 1 <= len(refs) <= 25,
+                'read_events needs from 1 to 25 known source references')
+        require(all(isinstance(ref, ProjectionEventRef) for ref in refs))
+        frozen = tuple(refs)
+        require(len({ref.event_id for ref in frozen}) == len(frozen), 'source references must be unique')
+        raw = self._read(frozen)
+        try:
+            expected = {ref.event_id: ref.source_digest for ref in frozen}
+            groups: dict[str, list[ProjectionRow]] = {ref.event_id: [] for ref in frozen}
+            seen: set[tuple[str, str]] = set()
+            for line in raw.splitlines():
+                if not line.strip():
+                    continue
+                require(len(seen) < 4096)
+                row = ProjectionRow.from_dict(parse_json(line, maximum=_MAX_RESPONSE))
+                pair = (row.event_id, row.row_id)
+                require(row.event_id in expected and row.source_digest == expected[row.event_id] and pair not in seen)
+                groups[row.event_id].append(row); seen.add(pair)
+            items = tuple(ProjectionResult(ref.event_id, ref.source_digest,
+                'available' if groups[ref.event_id] else 'unavailable',
+                None if groups[ref.event_id] else 'projection_not_committed', tuple(groups[ref.event_id])) for ref in frozen)
+            config = self._config
+            return ProjectionPage(config.team_id, config.bank_id, config.release_id, config.cohort_id,
+                                  'committed_snapshot_requires_current_service_check', items)
+        except (WorkflowContractError, ValueError, TypeError, KeyError, UnicodeError, RecursionError):
+            raise ReadOnlyClickHouseError('invalid_readonly_clickhouse_response') from None

sphynx/client.py

@@ -0,0 +1,486 @@
+"""Thin authenticated client for hosted submissions and saved grading passes.
+
+Configuration: explicit arguments, SPHYNX_API_URL / SPHYNX_TOKEN, or the private
+~/.sphynx/client.json file. A hosted server must be deployed before this can run.
+"""
+from __future__ import annotations
+import json
+import math
+import os
+import re
+import time
+import urllib.error
+import urllib.request
+import uuid
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .diagnostics import Diagnostic
+    from .progress import ProgressView
+    from .audit_access import ReviewHistoryPage, ReviewOperationReceipt, ReviewTargetPage, TargetReviewPage
+    from .audit_contracts import BankRelease, ReviewContribution
+    from .audit_requests import BankReleaseDeclaration, BankReleaseTransition, ReviewAdjudication
+    from .analytical_views import EvaluationBoardPage, ProjectionPage
+    from .pr_evaluations import PrEvaluationRequest
+    from ._pr_client import PrEvaluation
+from urllib.parse import quote, urlencode, urlsplit
+from .http_transport import open_no_redirect
+
+_MAX_RESPONSE = 4_194_304
+_ID = re.compile(r'^exp_[0-9a-f]{32}$')
+
+def _unique_pairs(pairs):
+    value = {}
+    for key, item in pairs:
+        if key in value: raise ValueError('duplicate JSON field')
+        value[key] = item
+    return value
+
+def _release_ref(value):
+    if not isinstance(value, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:@/-]{0,255}', value):
+        raise ValueError('release must be a stable catalog identifier')
+    return quote(value, safe='')
+def _saved_id(value, prefix):
+    if not isinstance(value, str) or not re.fullmatch(prefix + r'_[0-9a-f]{32}', value):
+        raise ValueError(f'invalid {prefix} ID')
+    return value
+
+def _retry_key(value):
+    key = uuid.uuid4().hex if value is None else value
+    if not isinstance(key, str) or not re.fullmatch('[A-Za-z0-9_-]{16,100}', key):
+        raise ValueError('idempotency_key must contain 16 to 100 letters, numbers, underscores or hyphens')
+    return key
+
+def _response_matches(actual, expected, kind):
+    if actual != expected:
+        raise HostedClientError('invalid_server_response', f'the server returned a different {kind}')
+
+def _unchanged_links(previous, fresh):
+    for name in ('run_id', 'evaluation_id', 'experiment_id'):
+        if previous.get(name) is not None and fresh.get(name) != previous[name]:
+            raise HostedClientError('invalid_server_response', 'the server changed a bound record identity')
+
+def _validate_links(payload):
+    for name, prefix in (('run_id', 'run'), ('evaluation_id', 'eval'), ('experiment_id', 'exp')):
+        if payload.get(name) is not None:
+            try: _saved_id(payload[name], prefix)
+            except ValueError:
+                raise HostedClientError('invalid_server_response', 'the server returned an invalid linked identity') from None
+
+class HostedClientError(RuntimeError):
+    def __init__(self, code: str, message: str, *, experiment_id: str | None = None, handle: object | None = None):
+        self.code, self.experiment_id, self.handle = code, experiment_id, handle
+        super().__init__(f'{code}: {message}')
+
+    @property
+    def diagnostic(self) -> Diagnostic:
+        from .diagnostics import explain_error
+        return explain_error(self)
+
+class HostedResult:
+    """Native hosted report presentation; also available as HostedReport."""
+    def __init__(self, payload: dict): self._payload = payload
+    def to_dict(self): return json.loads(json.dumps(self._payload, allow_nan=False))
+    def summary(self):
+        text = self._payload.get('summary')
+        if not isinstance(text, str): raise HostedClientError('invalid_server_response', 'the report has no readable summary')
+        return text
+
+class Experiment:
+    """Native hosted submission handle; also available as HostedSubmission.
+
+    Native IDs, wire fields, polling, and representations keep their existing
+    identity. This handle coordinates work; it is not a run or an assessment.
+    """
+    def __init__(self, client: Client, payload: dict):
+        if not isinstance(payload, dict) or not isinstance(payload.get('id'), str) or not _ID.fullmatch(payload['id']):
+            raise HostedClientError('invalid_server_response', 'the server did not return an experiment ID')
+        _validate_links(payload)
+        self._client, self._record = client, payload
+        self.id = payload['id']
+    @property
+    def progress(self) -> ProgressView:
+        from .progress import _hosted_progress
+        return _hosted_progress(self._record, 'submission')
+    @property
+    def status(self): return self._record.get('status')
+    @property
+    def head_sha(self): return self._record.get('head_sha')
+    @property
+    def run_id(self): return self._record.get('run_id')
+    @property
+    def evaluation_id(self): return self._record.get('evaluation_id')
+    def refresh(self):
+        fresh = self._client.get_experiment(self.id)
+        _response_matches(fresh.id, self.id, 'submission')
+        _unchanged_links(self._record, fresh._record)
+        self._record = fresh._record
+        return self
+    def wait(self, *, timeout: float = 900, poll_interval: float = 2, on_progress=None):
+        for value in (timeout, poll_interval):
+            if type(value) not in (int, float) or not math.isfinite(value) or value <= 0:
+                raise ValueError('timeout and poll_interval must be finite positive seconds')
+        deadline, previous = time.monotonic() + timeout, None
+        while True:
+            state = self.status
+            if state != previous:
+                if on_progress is not None: on_progress(state)
+                previous = state
+            if state == 'completed':
+                return HostedResult(self._client._request('GET', f'/v1/experiments/{self.id}/result'))
+            if state == 'failed':
+                error = self._record.get('error') or {}
+                raise HostedClientError(error.get('code', 'experiment_failed'),
+                    f"experiment {self.id} failed at {error.get('stage', 'unknown')}; inspect its status for details", experiment_id=self.id)
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise HostedClientError('wait_timeout', f'experiment {self.id} continues remotely; use get_experiment() to resume waiting', experiment_id=self.id, handle=self)
+            time.sleep(min(poll_interval, remaining))
+            self.refresh()
+    def to_dict(self): return json.loads(json.dumps(self._record, allow_nan=False))
+    def __repr__(self): return f'Experiment(id={self.id!r}, status={self.status!r})'
+
+class HostedRun:
+    """Captured remote execution. Grading this run does not execute its candidate."""
+    def __init__(self, client: Client, payload: dict):
+        try: identity = _saved_id(payload.get('id'), 'run')
+        except (AttributeError, ValueError):
+            raise HostedClientError('invalid_server_response', 'the server did not return a run ID') from None
+        _validate_links(payload)
+        self._client, self._record, self.id = client, payload, identity
+    @property
+    def progress(self) -> ProgressView:
+        from .progress import _hosted_progress
+        return _hosted_progress(self._record, 'execution')
+    @property
+    def status(self): return self._record.get('status')
+    def refresh(self):
+        fresh = self._client.get_run(self.id)
+        if fresh.id != self.id:
+            raise HostedClientError('invalid_server_response', 'the server returned a different run')
+        _unchanged_links(self._record, fresh._record)
+        self._record = fresh._record
+        return self
+    def grade(self, *, idempotency_key=None):
+        return self._client.grade(self.id, idempotency_key=idempotency_key)
+    def to_dict(self): return json.loads(json.dumps(self._record, allow_nan=False))
+    def __repr__(self): return f'HostedRun(id={self.id!r}, status={self.status!r})'
+
+class HostedEvaluation:
+    """A durable remote grading pass; also available as HostedGradingPass."""
+    def __init__(self, client: Client, payload: dict):
+        try: identity = _saved_id(payload.get('id'), 'eval')
+        except (AttributeError, ValueError):
+            raise HostedClientError('invalid_server_response', 'the server did not return an evaluation ID') from None
+        _validate_links(payload)
+        self._client, self._record, self.id = client, payload, identity
+    @property
+    def progress(self) -> ProgressView:
+        from .progress import _hosted_progress
+        return _hosted_progress(self._record, 'grading')
+    @property
+    def status(self): return self._record.get('status')
+    @property
+    def run_id(self): return self._record.get('run_id')
+    def refresh(self):
+        fresh = self._client.get_evaluation(self.id)
+        if fresh.id != self.id:
+            raise HostedClientError('invalid_server_response', 'the server returned a different evaluation')
+        _unchanged_links(self._record, fresh._record)
+        self._record = fresh._record
+        return self
+    def wait(self, *, timeout=900, poll_interval=2, on_progress=None):
+        for value in (timeout, poll_interval):
+            if type(value) not in (int, float) or not math.isfinite(value) or value <= 0:
+                raise ValueError('timeout and poll_interval must be finite positive seconds')
+        deadline, previous = time.monotonic() + timeout, None
+        while True:
+            state = self.status
+            if state != previous:
+                if on_progress is not None: on_progress(state)
+                previous = state
+            if state == 'completed':
+                return HostedResult(self._client._request('GET', f'/v1/evaluations/{self.id}/result'))
+            if state == 'failed':
+                error = self._record.get('error') or {}
+                raise HostedClientError(error.get('code', 'evaluation_failed'),
+                    f'evaluation {self.id} failed during grading; inspect its status for details')
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise HostedClientError('wait_timeout',
+                    f'evaluation {self.id} continues remotely; use get_evaluation() to resume waiting', handle=self)
+            time.sleep(min(poll_interval, remaining))
+            self.refresh()
+    def to_dict(self): return json.loads(json.dumps(self._record, allow_nan=False))
+    def __repr__(self): return f'HostedEvaluation(id={self.id!r}, status={self.status!r})'
+
+class ComparisonRef:
+    """Saved comparison of owned reports. Retrieval never runs or grades a candidate."""
+    def __init__(self, client: Client, payload: dict):
+        try: identity = _saved_id(payload.get('id'), 'cmp')
+        except (AttributeError, ValueError):
+            raise HostedClientError('invalid_server_response', 'the server did not return a comparison ID') from None
+        self._client, self._record, self.id = client, payload, identity
+    @property
+    def status(self): return self._record.get('status')
+    def result(self):
+        payload = self._client._request('GET', f'/v1/comparisons/{self.id}/result')
+        if payload.get('comparison_id') != self.id or payload.get('schema_version') != 'sphynx.hosted.saved-comparison.v1':
+            raise HostedClientError('invalid_server_response', 'the server returned a different comparison')
+        return HostedResult(payload)
+    def summary(self): return self.result().summary()
+    def to_dict(self): return json.loads(json.dumps(self._record, allow_nan=False))
+    def __repr__(self): return f'ComparisonRef(id={self.id!r}, status={self.status!r})'
+
+class Client:
+    def __init__(self, api_url: str | None = None, token: str | None = None, *, timeout: float = 120,
+                 config_path: str | Path | None = None, allow_local_http: bool = False, retries: int = 2):
+        config = {}
+        path = Path(config_path) if config_path else Path.home() / '.sphynx' / 'client.json'
+        if (api_url is None or token is None) and path.exists():
+            try:
+                if path.stat().st_size > 16_384: raise ValueError('size')
+                config = json.loads(path.read_bytes())
+                if not isinstance(config, dict) or set(config) != {'api_url', 'token'}: raise ValueError('shape')
+            except (OSError, ValueError):
+                raise HostedClientError('invalid_client_config', 'the private client configuration is invalid') from None
+        api_url = api_url or os.environ.get('SPHYNX_API_URL') or config.get('api_url')
+        token = token or os.environ.get('SPHYNX_TOKEN') or config.get('token')
+        if not isinstance(api_url, str) or not isinstance(token, str) or not token:
+            raise HostedClientError('client_not_configured', 'configure a hosted API URL and your Sphynx token')
+        try: parsed = urlsplit(api_url)
+        except ValueError: raise HostedClientError('invalid_api_url', 'use a trusted HTTPS API origin') from None
+        if (parsed.username or parsed.password or parsed.query or parsed.fragment or parsed.path not in ('', '/')
+                or not parsed.hostname or any(c.isspace() or ord(c) < 32 for c in api_url)):
+            raise HostedClientError('invalid_api_url', 'use a trusted HTTPS API origin without a path or credentials')
+        if parsed.scheme != 'https' and not (allow_local_http and parsed.scheme == 'http' and parsed.hostname in ('127.0.0.1', '::1', 'localhost')):
+            raise HostedClientError('invalid_api_url', 'HTTPS is required; local HTTP must be explicitly enabled for development')
+        if not 32 <= len(token) <= 256 or any(c.isspace() for c in token):
+            raise HostedClientError('invalid_client_token', 'use an operator-issued Sphynx token')
+        if type(timeout) not in (int, float) or not math.isfinite(timeout) or timeout <= 0:
+            raise ValueError('timeout must be finite positive seconds')
+        if type(retries) is not int or not 0 <= retries <= 4: raise ValueError('retries must be between zero and four')
+        self.api_url, self._token, self.timeout, self.retries = api_url.rstrip('/'), token, timeout, retries
+    def __repr__(self): return f'Client(api_url={self.api_url!r})'
+    def _request(self, method, path, payload=None, *, retry_key=None, deadline=None):
+        if deadline is not None and (type(deadline) not in (int, float) or not math.isfinite(deadline)):
+            raise ValueError('request deadline must be a finite monotonic time')
+        def remaining():
+            if deadline is None: return None
+            value = deadline - time.monotonic()
+            if value <= 0: raise HostedClientError('wait_timeout', 'the read budget expired; retain the original operation handle')
+            return value
+        def pause(seconds):
+            budget = remaining()
+            time.sleep(seconds if budget is None else min(seconds, budget))
+        body = None if payload is None else json.dumps(payload, separators=(',', ':'), allow_nan=False).encode()
+        headers = {'Authorization': 'Bearer ' + self._token, 'Accept': 'application/json', 'Content-Type': 'application/json'}
+        if retry_key: headers['Idempotency-Key'] = retry_key
+        request = urllib.request.Request(self.api_url + path, data=body, headers=headers, method=method)
+        for attempt in range(self.retries + 1):
+            budget = remaining()
+            socket_timeout = self.timeout if budget is None else min(self.timeout, budget)
+            try:
+                with open_no_redirect(request, timeout=socket_timeout) as response:
+                    raw = response.read(_MAX_RESPONSE + 1)
+            except urllib.error.HTTPError as exc:
+                status = exc.code
+                try: raw = exc.read(16_385)
+                finally: exc.close()
+                if status in (429, 500, 502, 503, 504) and attempt < self.retries:
+                    pause(min(2 ** attempt, 4)); continue
+                try: error = json.loads(raw, object_pairs_hook=_unique_pairs).get('error', {})
+                except (ValueError, AttributeError, RecursionError): error = {}
+                code = error.get('code') if isinstance(error, dict) else None
+                safe = code if isinstance(code, str) and re.fullmatch('[a-z_]{1,64}', code) else 'hosted_request_failed'
+                message = ('authentication failed; provision or renew your Sphynx token' if status == 401
+                           else 'submission or access was rejected; check repository and suite registration' if status == 403
+                           else f'the hosted API returned HTTP {status}; inspect the experiment status or retry')
+                raise HostedClientError(safe, message) from None
+            except (urllib.error.URLError, OSError, TimeoutError):
+                if attempt < self.retries: pause(min(2 ** attempt, 4)); continue
+                raise HostedClientError('hosted_transport_failed', 'the hosted API could not be reached; retry with the same submission key') from None
+            remaining()
+            if len(raw) > _MAX_RESPONSE: raise HostedClientError('invalid_server_response', 'the hosted response exceeds its size limit')
+            try:
+                value = json.loads(raw, object_pairs_hook=_unique_pairs, parse_constant=lambda _: (_ for _ in ()).throw(ValueError('nonfinite')))
+                if not isinstance(value, dict): raise ValueError('shape')
+            except (ValueError, RecursionError): raise HostedClientError('invalid_server_response', 'the hosted API returned invalid JSON') from None
+            return value
+    @staticmethod
+    def list_evals():
+        """Installed contract discovery, offline; not hosted availability/access."""
+        from .evals import list_evals
+        return list_evals()
+
+    @staticmethod
+    def describe_eval(evaluation_id: str):
+        """Describe an installed definition without any authenticated request."""
+        from .evals import describe_eval
+        return describe_eval(evaluation_id)
+
+    def list_benchmarks(self):
+        """Authenticated public metadata discovery; does not run a candidate."""
+        return self._request('GET', '/v1/benchmarks')
+
+    def get_benchmark(self, release: str):
+        """Inspect release membership and eligibility, without private inputs or labels."""
+        return self._request('GET', '/v1/benchmarks/' + _release_ref(release))
+
+    def get_label_release(self, release: str):
+        """Inspect declared label provenance; metadata does not prove review or approval."""
+        return self._request('GET', '/v1/label-releases/' + _release_ref(release))
+    def evaluate(self, *, candidate_pr: str, suite: str = 'rag.rerank.v1', baseline: str = 'supplied-score:v1',
+                 idempotency_key: str | None = None, parameters: dict | None = None,
+                 expected_head_sha: str | None = None, candidate_method: str | None = None,
+                 expected_baseline_sha: str | None = None) -> Experiment:
+        """Submit a PR and optional named method; a full commit SHA can guard its head."""
+        if candidate_method is not None:
+            if not isinstance(candidate_method, str) or not re.fullmatch(r'[A-Za-z0-9][A-Za-z0-9._:-]{0,127}', candidate_method):
+                raise ValueError('candidate_method must be a bounded ASCII stable identifier')
+        if expected_head_sha is not None:
+            if not isinstance(expected_head_sha, str) or not re.fullmatch(r'[0-9a-fA-F]{40}', expected_head_sha):
+                raise ValueError('expected_head_sha must be a complete 40-character hexadecimal commit SHA')
+            expected_head_sha = expected_head_sha.lower()
+        if expected_baseline_sha is not None:
+            if baseline != 'registered-main-reflex-lexical:v1':
+                raise ValueError('expected_baseline_sha requires the registered main baseline')
+            if not isinstance(expected_baseline_sha, str) or not re.fullmatch(r'[0-9a-fA-F]{40}', expected_baseline_sha):
+                raise ValueError('expected_baseline_sha must be a complete 40-character hexadecimal commit SHA')
+            expected_baseline_sha = expected_baseline_sha.lower()
+        key = _retry_key(idempotency_key)
+        payload = {'candidate_pr': candidate_pr, 'suite': suite, 'baseline': baseline}
+        if parameters is not None:
+            if not isinstance(parameters, dict): raise ValueError('parameters must be an object')
+            payload['parameters'] = parameters
+        if expected_head_sha is not None:
+            payload['expected_head_sha'] = expected_head_sha
+        if candidate_method is not None:
+            payload['candidate_method'] = candidate_method
+        if expected_baseline_sha is not None:
+            payload['expected_baseline_sha'] = expected_baseline_sha
+        return Experiment(self, self._request('POST', '/v1/experiments', payload, retry_key=key))
+    def get_experiment(self, experiment_id: str) -> Experiment:
+        if not isinstance(experiment_id, str) or not _ID.fullmatch(experiment_id): raise ValueError('invalid experiment ID')
+        result = Experiment(self, self._request('GET', '/v1/experiments/' + experiment_id))
+        _response_matches(result.id, experiment_id, 'submission')
+        return result
+    # Equivalent names retain exact signatures, validation, and native wire
+    # behavior. They do not add a shared-workflow hosted execution adapter.
+    submit = evaluate
+    get_submission = get_experiment
+    def get_run(self, run_id: str) -> HostedRun:
+        identity = _saved_id(run_id, 'run')
+        result = HostedRun(self, self._request('GET', '/v1/runs/' + identity))
+        _response_matches(result.id, identity, 'run')
+        return result
+    def grade(self, run_id: str, *, idempotency_key: str | None = None) -> HostedEvaluation:
+        """Grade an owned saved capture again with its pinned grader; no candidate run."""
+        identity = _saved_id(run_id, 'run')
+        result = HostedEvaluation(self, self._request('POST', '/v1/runs/' + identity + '/evaluations',
+            {}, retry_key=_retry_key(idempotency_key)))
+        if result.run_id is not None:
+            _response_matches(result.run_id, identity, 'grading run')
+        return result
+    def get_evaluation(self, evaluation_id: str) -> HostedEvaluation:
+        identity = _saved_id(evaluation_id, 'eval')
+        result = HostedEvaluation(self, self._request('GET', '/v1/evaluations/' + identity))
+        _response_matches(result.id, identity, 'grading pass')
+        return result
+    def compare_saved(self, evaluation_a: str, evaluation_b: str, *, lane_a='candidate', lane_b='candidate') -> ComparisonRef:
+        """Compare two existing owned evaluations; no candidate run or new grading."""
+        a, b = _saved_id(evaluation_a, 'eval'), _saved_id(evaluation_b, 'eval')
+        if lane_a not in ('candidate', 'baseline') or lane_b not in ('candidate', 'baseline'):
+            raise ValueError('comparison lanes must be candidate or baseline')
+        return ComparisonRef(self, self._request('POST', '/v1/comparisons', {
+            'evaluation_a': a, 'evaluation_b': b, 'lane_a': lane_a, 'lane_b': lane_b}))
+    def get_comparison(self, comparison_id: str) -> ComparisonRef:
+        identity = _saved_id(comparison_id, 'cmp')
+        record = self._request('GET', '/v1/comparisons/' + identity)
+        result = ComparisonRef(self, record)
+        if result.id != identity:
+            raise HostedClientError('invalid_server_response', 'the server returned a different comparison')
+        return result
+    def get_bank_release(self, bank_id: str, release_id: str) -> BankRelease:
+        """Read current permitted metadata/eligibility for a known selected bank."""
+        from ._audit_client import release
+        return release(self, bank_id, release_id)
+
+    def get_bank_review_targets(self, bank_id: str, release_id: str, *, after: str | None = None,
+                                through_version: int | None = None, limit: int = 20) -> ReviewTargetPage:
+        """Read one protected page. No global catalog or automatic pagination."""
+        from ._audit_client import targets
+        return targets(self, bank_id, release_id, after=after, through_version=through_version, limit=limit)
+
+    def get_bank_review_history(self, bank_id: str, release_id: str, *, after: int = 0,
+                                through_version: int | None = None, limit: int | None = None,
+                                protected: bool = False) -> ReviewHistoryPage:
+        """Read metadata, or explicitly request operator-only private history."""
+        from ._audit_client import history
+        return history(self, bank_id, release_id, after=after, through_version=through_version,
+                       limit=limit, protected=protected)
+
+    def get_bank_review_details(self, bank_id: str, release_id: str, target_id: str, *, after: int = 0,
+                                through_version: int | None = None, limit: int = 10) -> TargetReviewPage:
+        """Read authorized judgments/protocol and the current contribution-set digest."""
+        from ._audit_client import details
+        return details(self, bank_id, release_id, target_id, after=after, through_version=through_version, limit=limit)
+
+    def create_bank_release(self, bank_id: str, request: BankReleaseDeclaration) -> ReviewOperationReceipt:
+        """Submit an operator declaration with its original explicit key."""
+        from ._audit_client import write
+        return write(self, bank_id, None, 'create', request)
+
+    def contribute_bank_review(self, bank_id: str, release_id: str, request: ReviewContribution) -> ReviewOperationReceipt:
+        """Submit a version-guarded review; the service supplies reviewer identity."""
+        from ._audit_client import write
+        return write(self, bank_id, release_id, 'contribute', request)
+
+    def adjudicate_bank_review(self, bank_id: str, release_id: str, request: ReviewAdjudication) -> ReviewOperationReceipt:
+        """Submit an independent decision bound to the exact current review set."""
+        from ._audit_client import write
+        return write(self, bank_id, release_id, 'adjudicate', request)
+
+    def transition_bank_release(self, bank_id: str, release_id: str, request: BankReleaseTransition) -> ReviewOperationReceipt:
+        """Request operator hold/resume/withdraw with the original version/key."""
+        from ._audit_client import write
+        return write(self, bank_id, release_id, 'transition', request)
+
+    def get_evaluation_board(self, bank_id: str, board_id: str, *, limit: int = 20,
+                             cursor: str | None = None) -> EvaluationBoardPage:
+        """Read a selected private board. Retain its cursor with its snapshot."""
+        from ._analytical_client import board
+        return board(self, bank_id, board_id, limit=limit, cursor=cursor)
+    def submit_pr_evaluation(self, request: PrEvaluationRequest, *, idempotency_key: str | None = None) -> PrEvaluation:
+        """Submit one server-selected private evaluation plan for exact base/head revisions."""
+        from ._pr_client import submit
+        return submit(self, request, idempotency_key=idempotency_key)
+    def get_pr_evaluation(self, evaluation_id: str) -> PrEvaluation:
+        """Read the original owned PR operation without creating more candidate work."""
+        from ._pr_client import get
+        return get(self, evaluation_id)
+
+    def get_evaluation_projection(self, bank_id: str, board_id: str, entry_id: str) -> ProjectionPage:
+        """Read permitted source summaries for one selected board entry."""
+        from ._analytical_client import projection
+        return projection(self, bank_id, board_id, entry_id)
+
+    def leaderboard(self, suite: str = 'rag.rerank.v1', *, include_baseline: bool = False, limit: int = 200):
+        """Read owner-scoped saved rankings, grouped by quality and actual runtime."""
+        if suite not in ('rag.rerank.v1', 'rag.rerank.public.v1'):
+            raise ValueError('suite has no admitted hosted leaderboard')
+        if type(include_baseline) is not bool or type(limit) is not int or not 1 <= limit <= 200:
+            raise ValueError('include_baseline must be boolean and limit must be from 1 to 200')
+        query = urlencode({'suite': suite, 'include_baseline': str(include_baseline).lower(), 'limit': limit})
+        board = self._request('GET', '/v1/leaderboards?' + query)
+        if board.get('schema_version') != 'sphynx.hosted.leaderboard.v1' or board.get('official') is not False:
+            raise HostedClientError('invalid_server_response', 'the server returned an invalid development leaderboard')
+        return board
+
+
+# Direct aliases preserve native type identity and saved/wire compatibility.
+# Existing imports remain supported; no new remote capability is implied.
+HostedSubmission = Experiment
+HostedGradingPass = HostedEvaluation
+HostedReport = HostedResult