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

sphynx/invocation_candidates.py

@@ -0,0 +1,392 @@
+"""Portable, cohort-bound invocation candidates and stdin protocol adapters.
+
+Recordings are owner supplied and pinned, never discovered relative to source.
+Credentials are resolved at execution and never persisted or placed in argv.
+The protocol subprocess accepts a configuration artifact path and exact digest;
+this is an SDK candidate protocol, not a user-facing Sphynx command line.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import sys
+import time
+import urllib.request
+from collections.abc import Mapping
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any, Callable
+
+from .contracts import CandidateSpec, canonical_json
+from .integration_contracts import CandidateConfiguration, require_digest, value_digest
+from .invocation_catalog_data import POLICY_MANIFESTS, BANK_BINDINGS
+from . import routing_policies as policies
+
+INTERFACE = "sphynx.rag.invoke.v1"
+RECORDING_SCHEMA = "sphynx.rag.invoke.recording.v1"
+ADAPTER_SCHEMA = "sphynx.rag.invoke.adapter.v1"
+JEV_ENDPOINT = "https://api.typesafe.ai/v1/systemone"
+REVIEW_ENDPOINT = "https://api.openai.com/v1/responses"
+_APPROVED_LIVE_INPUTS = {
+    "excerpt-free-200": "sha256:7316862d37a7185ed7c995278a5d5f9ae34ff0ae05afe5c4d281e2c00303d2bf",
+    "decision-boundary-80": "sha256:f1aea9ab88c55586ed01a6bf5aee4ac78661ae11727dfea12ecee14da09ea2b6",
+    "narrow-gate-20260925-r5": "sha256:c230ad79a9aba6cef17266b83345d273e93eba0871408ce23f87d59e27543194",
+}
+_BINDING_KEYS = {"bank_id", "bank_release", "input_digest", "cohort_digest", "case_ids", "request_digests"}
+_PARAMETER_KEYS = _BINDING_KEYS | {"policy", "excerpt_policy"}
+
+
+def _file_digest(raw: bytes) -> str:
+    return "sha256:" + hashlib.sha256(raw).hexdigest()
+
+
+def _strict_json(raw: bytes | str) -> Any:
+    def unique(pairs):
+        obj = {}
+        for key, value in pairs:
+            if key in obj:
+                raise ValueError("duplicate JSON field")
+            obj[key] = value
+        return obj
+    def invalid(value):
+        raise ValueError("non-finite JSON value")
+    return json.loads(raw, object_pairs_hook=unique, parse_constant=invalid)
+
+
+def bind_invocation_pack(pack) -> dict[str, Any]:
+    """Derive a content-only execution scope from a loaded InvocationPack."""
+    requests = [case.request() for case in pack.cases]
+    if not requests or len({r["case_id"] for r in requests}) != len(requests):
+        raise ValueError("scope must contain unique cases")
+    return {
+        "bank_id": pack.bank_id, "bank_release": pack.bank_release,
+        "input_digest": "sha256:" + pack.input_sha256,
+        "cohort_digest": "sha256:" + pack.cohort_sha256,
+        "case_ids": [r["case_id"] for r in requests],
+        "request_digests": {r["case_id"]: value_digest(r) for r in requests},
+    }
+
+
+def recording_model_snapshot(rows: list[dict], model_id: str) -> str:
+    """Pin captured provider responses, not a claim about hosted model weights."""
+    return value_digest({"model_id": model_id, "provider_responses": [
+        {"case_id": row["case_id"], "response": row["response"],
+         "reviewer_response": row["reviewer_response"]} for row in rows]})
+
+
+def _model_id(policy: str) -> str:
+    if policy == "jev-reviewed":
+        return "jev-1.13.0+gpt-6-sol"
+    return "jev-1.13.0" if policy.startswith("jev-") else "gpt-6-sol"
+
+
+def _binding(parameters: Mapping) -> dict:
+    return {key: parameters[key] for key in _BINDING_KEYS}
+
+
+def _plain(value):
+    if isinstance(value, Mapping):
+        return {key: _plain(item) for key, item in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_plain(item) for item in value]
+    return value
+
+
+def _freeze(value):
+    """Retain validated JSON without mutable aliases to emitted evidence."""
+    if isinstance(value, Mapping):
+        return MappingProxyType({key: _freeze(item) for key, item in value.items()})
+    if isinstance(value, (list, tuple)):
+        return tuple(_freeze(item) for item in value)
+    return value
+
+
+def _validate_configuration(configuration: CandidateConfiguration) -> str:
+    if not isinstance(configuration, CandidateConfiguration) or configuration.interface_version != INTERFACE:
+        raise ValueError("invocation configuration interface differs")
+    p = configuration.parameters
+    policy = p.get("policy")
+    if policy not in POLICY_MANIFESTS:
+        raise ValueError("routing policy is blocked or unknown")
+    manifest = POLICY_MANIFESTS[policy]
+    keys = _PARAMETER_KEYS | ({"recording_digest"} if configuration.execution_mode == "recorded" else set())
+    if set(p) != keys:
+        raise ValueError("routing parameters differ from exact schema")
+    if configuration.source_digest != manifest["source_digest"]:
+        raise ValueError("frozen policy source identity differs")
+    if configuration.execution_mode not in manifest["execution_modes"]:
+        raise ValueError("policy execution mode is unsupported")
+    if p["bank_id"] not in manifest["supported_banks"] or not isinstance(p["bank_release"], str) or not p["bank_release"]:
+        raise ValueError("routing bank is unsupported")
+    bank = BANK_BINDINGS[p["bank_id"]]
+    if p["bank_release"] != bank["release"] or p["input_digest"] != bank["input_digest"]:
+        raise ValueError("routing bank release or input identity differs")
+    if p["excerpt_policy"] != manifest["excerpt_policy"]:
+        raise ValueError("routing excerpt policy differs")
+    for field in ("input_digest", "cohort_digest"):
+        require_digest(p[field], field)
+    ids = p["case_ids"]
+    if not isinstance(ids, tuple) or not ids or any(not isinstance(i, str) or not i for i in ids) or len(set(ids)) != len(ids):
+        raise ValueError("routing coverage case IDs are invalid")
+    if not isinstance(p["request_digests"], Mapping) or set(p["request_digests"]) != set(ids):
+        raise ValueError("routing request coverage differs")
+    for digest in p["request_digests"].values():
+        require_digest(digest, "request_digest")
+    if configuration.execution_mode == "recorded":
+        require_digest(p["recording_digest"], "recording_digest")
+        if configuration.credential_refs or configuration.model_id != _model_id(policy) or configuration.model_revision != "recorded-provider-responses.v1":
+            raise ValueError("recording model/revision or credentials differ")
+    elif configuration.model_id is not None:
+        raise ValueError("deterministic/live candidates cannot claim captured model snapshots")
+    if configuration.execution_mode != "live_provider" and configuration.credential_refs:
+        raise ValueError("credentials are only accepted for explicit live execution")
+    return policy
+
+
+def _request(configuration, request):
+    if not isinstance(request, dict) or set(request) != {"schema_version", "pack_id", "case_id", "company_id", "user_turn", "conversation_context"}:
+        raise ValueError("request fields differ from invocation schema")
+    if request["schema_version"] != "sphynx.rag.invoke.request.v1" or request["pack_id"] != "rag.invoke.v1":
+        raise ValueError("request interface differs")
+    if request["company_id"] not in policies.COMPANIES or not isinstance(request["user_turn"], str) or not request["user_turn"].strip():
+        raise ValueError("request company or user turn is invalid")
+    context = request["conversation_context"]
+    if not isinstance(context, list) or any(not isinstance(t, dict) or set(t) != {"role", "content"} or t["role"] not in ("user", "assistant") or not isinstance(t["content"], str) for t in context):
+        raise ValueError("request conversation is invalid")
+    if configuration.parameters["request_digests"].get(request["case_id"]) != value_digest(request):
+        raise ValueError("request is outside the bound cohort")
+    if configuration.parameters["excerpt_policy"] == "forbid" and "source excerpt" in canonical_json(request).casefold():
+        raise ValueError("source excerpts are outside approved routing scope")
+
+
+def _default_credentials(reference: str) -> str:
+    if not reference.startswith("env:") or not re.fullmatch(r"SPHYNX_[A-Z0-9_]+", reference[4:]):
+        raise ValueError("subprocess requires an env:SPHYNX_ named credential reference")
+    return os.environ.get(reference[4:], "")
+
+
+def _provider_transport(endpoint: str, body: bytes, credential: str) -> dict:
+    request = urllib.request.Request(endpoint, data=body, method="POST", headers={
+        "Authorization": "Bearer " + credential, "Content-Type": "application/json"})
+    try:
+        with urllib.request.urlopen(request, timeout=90) as response:
+            raw = response.read(16 * 1024 * 1024 + 1)
+        if len(raw) > 16 * 1024 * 1024:
+            raise ValueError("provider response too large")
+        return _strict_json(raw)
+    except Exception:
+        raise ValueError("provider transport failed; details withheld") from None
+
+
+class RoutingAdapter:
+    """Direct typed adapter. Every provider boundary requires explicit approval."""
+    def __init__(self, configuration: CandidateConfiguration, *, recordings=None,
+                 allow_live: bool = False, approved_scope: Mapping | None = None,
+                 credential_resolver: Callable[[str], str] | None = None,
+                 transport: Callable[[str, bytes, str], dict] | None = None):
+        self.configuration = configuration
+        self.policy = _validate_configuration(configuration)
+        self.last_events: tuple[dict, ...] = ()
+        self.last_intervention: dict | None = None
+        self._rows = MappingProxyType({})
+        self._credentials: tuple[str, ...] = ()
+        self._transport = transport or _provider_transport
+        if configuration.execution_mode == "live_provider":
+            if allow_live is not True or not isinstance(approved_scope, Mapping) or value_digest(approved_scope) != value_digest(_binding(configuration.parameters)):
+                raise ValueError("live execution requires explicit opt-in and exact approved scope")
+            p = configuration.parameters
+            if p["input_digest"] != _APPROVED_LIVE_INPUTS.get(p["bank_id"]) or p["excerpt_policy"] != "forbid":
+                raise ValueError("live bank/input scope is unapproved")
+            refs = configuration.credential_refs
+            if len(refs) != (2 if self.policy == "jev-reviewed" else 1):
+                raise ValueError("live credential references differ from selected stages")
+            resolver = credential_resolver or _default_credentials
+            try:
+                credentials = tuple(resolver(ref) for ref in refs)
+            except Exception:
+                raise ValueError("credential resolution failed; details withheld") from None
+            if any(not isinstance(key, str) or not key or any(c.isspace() for c in key) for key in credentials):
+                raise ValueError("live credentials are missing or malformed")
+            self._credentials = credentials
+        elif allow_live or approved_scope is not None or credential_resolver is not None or transport is not None:
+            raise ValueError("provider settings are only valid for live execution")
+        if configuration.execution_mode == "recorded":
+            if recordings is None:
+                raise ValueError("complete pinned recording is required")
+            self._load_recording(Path(recordings))
+        elif recordings is not None:
+            raise ValueError("recordings are only valid for recorded execution")
+
+    def _load_recording(self, path: Path):
+        raw = path.read_bytes()
+        if len(raw) > 64 * 1024 * 1024 or _file_digest(raw) != self.configuration.parameters["recording_digest"]:
+            raise ValueError("recording bytes differ from pinned capture")
+        recording = _strict_json(raw)
+        expected_keys = {"schema_version", "policy", "source_digest", "binding", "model_id", "model_revision", "model_snapshot_digest", "rows"}
+        if not isinstance(recording, dict) or set(recording) != expected_keys or recording["schema_version"] != RECORDING_SCHEMA:
+            raise ValueError("recording schema differs")
+        for field in ("model_id", "model_revision", "model_snapshot_digest", "source_digest"):
+            if recording[field] != getattr(self.configuration, field):
+                raise ValueError("recording " + field + " identity differs")
+        if recording["policy"] != self.policy or value_digest(recording["binding"]) != value_digest(_binding(self.configuration.parameters)):
+            raise ValueError("recording cohort or policy identity differs")
+        rows = recording["rows"]
+        if not isinstance(rows, list) or any(not isinstance(row, dict) or set(row) != {"case_id", "request_digest", "response", "reviewer_response", "source_prediction_digest"} for row in rows):
+            raise ValueError("recording rows differ from exact schema")
+        if [row["case_id"] for row in rows] != list(self.configuration.parameters["case_ids"]):
+            raise ValueError("recording ordered coverage differs")
+        if recording_model_snapshot(rows, recording["model_id"]) != recording["model_snapshot_digest"]:
+            raise ValueError("recording provider response snapshot differs")
+        for row in rows:
+            if row["request_digest"] != self.configuration.parameters["request_digests"][row["case_id"]]:
+                raise ValueError("recording request binding differs")
+            if self.policy.startswith("jev-"):
+                p = policies.jev_probabilities(row["response"])
+                first = max(policies.ORDER, key=lambda a: p[a])
+                if self.policy == "jev-reviewed":
+                    prediction_digest = value_digest({"request_digest": row["request_digest"], "response": row["response"]})
+                    if row["source_prediction_digest"] != prediction_digest:
+                        raise ValueError("reviewer source prediction differs")
+                    if first == "call_rag":
+                        if row["reviewer_response"] is not None:
+                            raise ValueError("Jev calls must bypass reviewer")
+                    else:
+                        policies.route_result(row["reviewer_response"], reviewer=True)
+                elif row["reviewer_response"] is not None or row["source_prediction_digest"] is not None:
+                    raise ValueError("unexpected reviewer evidence")
+            else:
+                policies.route_result(row["response"])
+                if row["reviewer_response"] is not None or row["source_prediction_digest"] is not None:
+                    raise ValueError("unexpected reviewer evidence")
+        self._rows = _freeze({row["case_id"]: row for row in rows})
+
+    def _call(self, endpoint, body, index):
+        try:
+            response = self._transport(endpoint, body, self._credentials[index])
+            def contains_secret(value):
+                if isinstance(value, str):
+                    return any(secret in value for secret in self._credentials)
+                if isinstance(value, Mapping):
+                    return any(contains_secret(k) or contains_secret(v) for k, v in value.items())
+                if isinstance(value, (list, tuple)):
+                    return any(contains_secret(v) for v in value)
+                return False
+            if contains_secret(response):
+                raise ValueError("provider response contains a credential")
+            return _strict_json(canonical_json(response))
+        except Exception:
+            raise ValueError("provider execution failed; details withheld") from None
+
+    def __call__(self, request: dict) -> dict:
+        self.last_events = ()
+        self.last_intervention = None
+        _request(self.configuration, request)
+        if self.configuration.execution_mode == "live_provider" and (len(request["conversation_context"]) != 1 or len(canonical_json(request["conversation_context"])) > 3000):
+            raise ValueError("live context is outside approved authored scope")
+        events = []
+        replay = self.configuration.execution_mode == "recorded"
+        row = _plain(self._rows.get(request["case_id"]))
+        def stage(name, model, body, response, decision, elapsed, probabilities=None):
+            usage = response.get("usage") or {}
+            events.append({"schema_version": "sphynx.rag.invoke.candidate_stage.v1", "case_id": request["case_id"],
+                "stage": name, "model": model, "request_sha256": hashlib.sha256(body).hexdigest(),
+                "response_sha256": hashlib.sha256(json.dumps(response, sort_keys=True, separators=(",", ":"), allow_nan=False).encode()).hexdigest(),
+                "request": _strict_json(body), "response": _plain(response),
+                "candidate_reported_latency_ms": round(elapsed, 3),
+                "timing_provenance": "replay_adapter_elapsed_not_provider_latency" if replay else "provider_stage_wall_clock",
+                "candidate_reported_usage": {"input_tokens": _plain(usage.get("input_tokens")), "output_tokens": _plain(usage.get("output_tokens"))},
+                "decision": decision, "probabilities": _plain(probabilities)})
+        if self.policy in ("always-call", "always-clarify", "always-context", "simple-rule"):
+            action = {"always-call": "call_rag", "always-clarify": "clarify_first", "always-context": "do_not_call_rag"}.get(self.policy)
+            action = action or policies.simple_rule_action(request["user_turn"])
+        elif self.policy.startswith("jev-"):
+            body = policies.jev_body(request)
+            start = time.monotonic_ns()
+            response = row["response"] if replay else self._call(JEV_ENDPOINT, body, 0)
+            p = policies.jev_probabilities(response)
+            action = max(policies.ORDER, key=lambda a: p[a])
+            if self.policy == "jev-080":
+                action = policies.jev_080_action(p["do_not_call_rag"], p["clarify_first"])
+            elif self.policy == "jev-asymmetric":
+                action = policies.t023_asymmetric_action(p["do_not_call_rag"], p["clarify_first"])
+            stage("jev", policies.JEV_MODEL, body, response, action, (time.monotonic_ns()-start)/1e6, p)
+            first = action
+            if self.policy == "jev-reviewed" and first != "call_rag":
+                body = policies.route_body(request, "reviewer")
+                start = time.monotonic_ns()
+                review = row["reviewer_response"] if replay else self._call(REVIEW_ENDPOINT, body, 1)
+                result = policies.route_result(review, reviewer=True)
+                stage("noncall_reviewer", policies.MODEL, body, review, result["route"], (time.monotonic_ns()-start)/1e6)
+                if result["route"] == "REQUIRE_RAG":
+                    action = "call_rag"
+            if self.policy == "jev-reviewed":
+                self.last_intervention = {"case_id": request["case_id"], "source_prediction_digest": value_digest({"request_digest": value_digest(request), "response": response}),
+                    "initial_action": policies.ACTION[first], "final_action": policies.ACTION[action],
+                    "changed": first != action, "scope": "same_recorded_jev_first_stage_before_and_after_noncall_review" if replay else "same_live_jev_first_stage_before_and_after_noncall_review"}
+        else:
+            body = policies.route_body(request, self.policy)
+            start = time.monotonic_ns()
+            response = row["response"]
+            result = policies.route_result(response)
+            stage(self.policy, policies.MODEL, body, response, result["route"], (time.monotonic_ns()-start)/1e6)
+            action = next(source for source, translated in policies.ACTION.items() if translated == result["route"])
+        self.last_events = tuple(events)
+        return {"schema_version": "sphynx.rag.invoke.response.v1", "case_id": request["case_id"], "action": policies.ACTION[action]}
+
+
+def make_invocation_candidate(name: str, *, configuration: CandidateConfiguration,
+                              configuration_path: str | os.PathLike[str], recordings=None,
+                              allow_live: bool = False, approved_scope: Mapping | None = None) -> CandidateSpec:
+    """Persist caller-owned nonsecret configuration and return installed protocol argv.
+
+    configuration_path must be a new retained file. The subprocess checks its
+    exact bytes; credential values and raw requests are never stored here.
+    Live subprocess environment refs currently fail closed under the legacy
+    runner's minimal environment; explicit runner integration is required.
+    """
+    policy = _validate_configuration(configuration)
+    if name not in (policy, "routing." + policy + ".v1"):
+        raise ValueError("candidate name differs from configuration policy")
+    RoutingAdapter(configuration, recordings=recordings, allow_live=allow_live, approved_scope=approved_scope)
+    envelope = {"schema_version": ADAPTER_SCHEMA, "configuration": configuration.to_dict(),
+        "recordings": str(Path(recordings).resolve()) if recordings is not None else None,
+        "allow_live": allow_live, "approved_scope": _plain(approved_scope)}
+    raw = (canonical_json(envelope) + "\n").encode("utf-8")
+    path = Path(configuration_path).resolve()
+    with path.open("xb") as stream:
+        stream.write(raw)
+    return CandidateSpec("routing." + policy + ".v1", configuration.configuration_id,
+        (sys.executable, "-m", "sphynx.invocation_candidates", str(path), _file_digest(raw)), INTERFACE)
+
+
+def protocol_main(argv=None) -> int:
+    try:
+        args = list(sys.argv[1:] if argv is None else argv)
+        if len(args) != 2:
+            raise ValueError("expected pinned adapter configuration path and digest")
+        require_digest(args[1], "adapter_digest")
+        raw = Path(args[0]).read_bytes()
+        if len(raw) > 1024 * 1024 or _file_digest(raw) != args[1]:
+            raise ValueError("adapter configuration digest differs")
+        envelope = _strict_json(raw)
+        if set(envelope) != {"schema_version", "configuration", "recordings", "allow_live", "approved_scope"} or envelope["schema_version"] != ADAPTER_SCHEMA:
+            raise ValueError("adapter envelope schema differs")
+        adapter = RoutingAdapter(CandidateConfiguration.from_dict(envelope["configuration"]), recordings=envelope["recordings"],
+            allow_live=envelope["allow_live"], approved_scope=envelope["approved_scope"])
+        request_raw = sys.stdin.buffer.read(1024 * 1024 + 1)
+        if len(request_raw) > 1024 * 1024:
+            raise ValueError("request too large")
+        response = adapter(_strict_json(request_raw))
+        for event in adapter.last_events:
+            print(json.dumps(event, sort_keys=True, allow_nan=False), file=sys.stderr, flush=True)
+        print(canonical_json(response), flush=True)
+        return 0
+    except Exception as exc:
+        print("routing_candidate_failure:" + type(exc).__name__, file=sys.stderr, flush=True)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(protocol_main())

sphynx/invocation_catalog_data.py

@@ -0,0 +1,40 @@
+"""Immutable, content-free routing discovery; importing this never executes a router."""
+from types import MappingProxyType
+from .catalog import CandidateDescriptor
+
+POLICY_MANIFESTS = MappingProxyType({
+    'always-call': MappingProxyType({'source_digest': 'sha256:92bf9f6db5ccee39e0702bfe23dbfef23935cb23792fa0ebc29450908c7e152b', 'supported_banks': ('excerpt-free-200', 'development-300', 'narrow-policy-90', 'decision-boundary-80', 'narrow-gate-20260925-r2', 'narrow-gate-20260925-r4', 'narrow-gate-20260925-r5'), 'execution_modes': ('trusted_local',), 'excerpt_policy': 'allow_supplied'}),
+    'always-clarify': MappingProxyType({'source_digest': 'sha256:27a8f2384bc920bef28b9d925dbf6e03163fac85d27edbf14842cf45a7b67885', 'supported_banks': ('excerpt-free-200', 'development-300', 'narrow-policy-90', 'decision-boundary-80', 'narrow-gate-20260925-r2', 'narrow-gate-20260925-r4', 'narrow-gate-20260925-r5'), 'execution_modes': ('trusted_local',), 'excerpt_policy': 'allow_supplied'}),
+    'always-context': MappingProxyType({'source_digest': 'sha256:38b160fec657e70f1af7011ea95e43705a8376a79eaee28db9a41093597a0391', 'supported_banks': ('excerpt-free-200', 'development-300', 'narrow-policy-90', 'decision-boundary-80', 'narrow-gate-20260925-r2', 'narrow-gate-20260925-r4', 'narrow-gate-20260925-r5'), 'execution_modes': ('trusted_local',), 'excerpt_policy': 'allow_supplied'}),
+    'simple-rule': MappingProxyType({'source_digest': 'sha256:aadfbdf4291a994eef41021ead871a70dba79b2a8ecbf79f1fe290cca7b4b719', 'supported_banks': ('excerpt-free-200', 'development-300', 'narrow-policy-90', 'decision-boundary-80', 'narrow-gate-20260925-r2', 'narrow-gate-20260925-r4', 'narrow-gate-20260925-r5'), 'execution_modes': ('trusted_local',), 'excerpt_policy': 'allow_supplied'}),
+    'jev-argmax': MappingProxyType({'source_digest': 'sha256:bedde8856f34b637210a2034005825fd359e5e2043414145d5f51af8b7252d91', 'supported_banks': ('excerpt-free-200', 'decision-boundary-80', 'narrow-gate-20260925-r5'), 'execution_modes': ('recorded', 'live_provider'), 'excerpt_policy': 'forbid'}),
+    'jev-reviewed': MappingProxyType({'source_digest': 'sha256:87bdf91d3e4d61d0a2fdd4a4c75560b3e38e75c87c1df9732f1e7d8f752b145f', 'supported_banks': ('excerpt-free-200', 'decision-boundary-80', 'narrow-gate-20260925-r5'), 'execution_modes': ('recorded', 'live_provider'), 'excerpt_policy': 'forbid'}),
+    'jev-080': MappingProxyType({'source_digest': 'sha256:ca20188db799e00618e0c22afd15838a634f0dc60b42dc3fbb3b2f201748d7fd', 'supported_banks': ('excerpt-free-200', 'development-300', 'narrow-policy-90', 'decision-boundary-80', 'narrow-gate-20260925-r2', 'narrow-gate-20260925-r4', 'narrow-gate-20260925-r5'), 'execution_modes': ('recorded',), 'excerpt_policy': 'allow_supplied'}),
+    'jev-asymmetric': MappingProxyType({'source_digest': 'sha256:eb06ef68479a94c2759f71979ae2df6aca68a6857d1808d3e8a7547046024a9a', 'supported_banks': ('excerpt-free-200', 'development-300', 'narrow-policy-90', 'decision-boundary-80', 'narrow-gate-20260925-r2', 'narrow-gate-20260925-r4', 'narrow-gate-20260925-r5'), 'execution_modes': ('recorded',), 'excerpt_policy': 'allow_supplied'}),
+    'typed': MappingProxyType({'source_digest': 'sha256:38bda9f73ac90ecac22e099e30b16edcd4705a26e06aa3e6b0d6f39064d2dd73', 'supported_banks': ('excerpt-free-200', 'development-300', 'narrow-policy-90', 'decision-boundary-80', 'narrow-gate-20260925-r2', 'narrow-gate-20260925-r4', 'narrow-gate-20260925-r5'), 'execution_modes': ('recorded',), 'excerpt_policy': 'allow_supplied'}),
+    'narrow': MappingProxyType({'source_digest': 'sha256:1292541d95aa8a92a84933526bad43bce0a93f4bd05120882de5df7bfc02e972', 'supported_banks': ('excerpt-free-200', 'development-300', 'narrow-policy-90', 'decision-boundary-80', 'narrow-gate-20260925-r2', 'narrow-gate-20260925-r4', 'narrow-gate-20260925-r5'), 'execution_modes': ('recorded',), 'excerpt_policy': 'allow_supplied'}),
+    'hybrid': MappingProxyType({'source_digest': 'sha256:618f61b1fa15081f4e599f227d61b86153044e9ff3728785506774c8e59eab46', 'supported_banks': ('excerpt-free-200', 'development-300', 'narrow-policy-90', 'decision-boundary-80', 'narrow-gate-20260925-r2', 'narrow-gate-20260925-r4', 'narrow-gate-20260925-r5'), 'execution_modes': ('recorded',), 'excerpt_policy': 'allow_supplied'}),
+})
+
+CANDIDATES = tuple(CandidateDescriptor(
+    candidate_id="routing." + name + ".v1", track="rag_invoke",
+    interface_version="sphynx.rag.invoke.v1", source_digest=manifest["source_digest"],
+    supported_dataset_ids=tuple("invocation." + bank for bank in manifest["supported_banks"]),
+    execution_modes=manifest["execution_modes"], implementation_status="available",
+    local_prerequisites=("exact bank/release/input/cohort/request binding", "excerpt_policy=" + manifest["excerpt_policy"]) + (("pinned complete recording and provider response snapshot",) if "recorded" in manifest["execution_modes"] else ()) + (("explicit live opt-in and approved excerpt-free scope", "named credential resolver; subprocess environment integration required") if "live_provider" in manifest["execution_modes"] else ()),
+    model_identity_required="recorded" in manifest["execution_modes"], supported_python=(">=3.11",),
+) for name, manifest in POLICY_MANIFESTS.items()) + (
+    CandidateDescriptor('routing.aidan-production.v1', "rag_invoke", "sphynx.rag.invoke.v1", None, (), ("recorded",), "blocked", reason='Deployed Aidan subject source/version is unverified; no reconstructed production adapter is authorized.'),
+    CandidateDescriptor('routing.aidan-gpt6sol-production.v1', "rag_invoke", "sphynx.rag.invoke.v1", None, (), ("recorded",), "blocked", reason='Cheap Aidan planner source/model identity is unverified as a deployed subject.'),
+    CandidateDescriptor('routing.binary-cascades.v1', "rag_invoke", "sphynx.rag.invoke.v1", 'sha256:a1cd3170e59f448abf5db157b9c012317c8398a3fbd22a02b2121d22be2bfce2', (), ("recorded",), "blocked", reason='Source-verified counterfactual cascades produce binary call/noncall, with explicit source fallbacks; the three-way interface cannot distinguish ASK_BUYER from ANSWER_FROM_CONTEXT. Use routing_policies.binary_cascade for binary source-parity only.'),
+)
+
+BANK_BINDINGS = MappingProxyType({
+    'excerpt-free-200': MappingProxyType({'release': 'v1-development-200', 'input_digest': 'sha256:7316862d37a7185ed7c995278a5d5f9ae34ff0ae05afe5c4d281e2c00303d2bf'}),
+    'development-300': MappingProxyType({'release': 'v1-20260918-r3-five-customer', 'input_digest': 'sha256:80336bade48c6bc1acadbae8c66e321d68008e0ee6d2d18fd473e56d566319a6'}),
+    'narrow-policy-90': MappingProxyType({'release': 'v1-20260925', 'input_digest': 'sha256:ecde7c3141fa8b508386e5b59468296acba55e14aa4f64e1e2f8143de977878e'}),
+    'decision-boundary-80': MappingProxyType({'release': 'v1-20260925', 'input_digest': 'sha256:f1aea9ab88c55586ed01a6bf5aee4ac78661ae11727dfea12ecee14da09ea2b6'}),
+    'narrow-gate-20260925-r2': MappingProxyType({'release': 'narrow-gate-20260925-r2', 'input_digest': 'sha256:fea544f918248f710be172bcadfdf1e6506ca2f4e08ab97c6099bd3afed1d316'}),
+    'narrow-gate-20260925-r4': MappingProxyType({'release': 'narrow-gate-20260925-r4', 'input_digest': 'sha256:2af3d98cb92146511e85de1a6c038d01f4bf7c117b622c61c6425a03f6e4a391'}),
+    'narrow-gate-20260925-r5': MappingProxyType({'release': 'narrow-gate-20260925-r5', 'input_digest': 'sha256:c230ad79a9aba6cef17266b83345d273e93eba0871408ce23f87d59e27543194'}),
+})

sphynx/learned_catalog_data.py

@@ -0,0 +1,30 @@
+"""Content-free frozen learned inference discovery; no fitted values/ML imports."""
+from types import MappingProxyType
+from .catalog import CandidateDescriptor
+from .integration_contracts import ScoreField
+
+_SOURCE='sha256:3323ca7ead3cf8cb69d9e7fc3a908dd877784f79ff94bb48ebdcb24cdb02c924'
+METHOD_NAMES=('T2','T7','T14','T17','T18','T19','T20','T21','T22')
+METHOD_METADATA=MappingProxyType({name:MappingProxyType({
+    'method':name,'ranking_alias_of':'T2' if name in ('T7','T14','T17','T18') else 'T19' if name=='T20' else None,
+    'historical_fitted_state_located':name in ('T19','T20','T21','T22'),
+    'historical_complete_cohort_located':False,'fitted_values_bundled':False,'refitting_available':False,
+    'probability_semantics':'state_label_mode_required; positive_unlabeled_diagnostic stays diagnostic' if name!='T2' and name!='T19' else 'no probability field',
+    'historical_full_benchmark_parity_verified':False,
+}) for name in METHOD_NAMES})
+_FIELDS=(ScoreField('ranking_utility','utility','higher','ranking_utility'),
+    ScoreField('raw_minilm_logit','utility','higher','model_logit'))
+CANDIDATES=tuple(CandidateDescriptor(
+    candidate_id='learned-'+name+'-frozen-v1',track='rerank',interface_version='sphynx.rerank-family.v1',
+    source_digest=_SOURCE,supported_dataset_ids=(),execution_modes=('recorded','trusted_local'),
+    implementation_status='available',reason=(
+        'Frozen prediction code is source-verified; this does not recreate a historical experiment. '+
+        ('Historical coefficients/calibration exist externally; complete original N11 inputs/metadata remain missing.' if name in ('T19','T20','T21','T22') else
+         'Original fitted ranker/calibrator not located; synthetic-source prediction parity does not supply the historical state.')),
+    local_prerequisites=('exact external fitted-state wrapper and SHA-256; payload/cohort/source binding',
+        'complete exact label-free ten-feature metadata, with missing values explicitly null',
+        'pinned MiniLM logits or an explicit offline model scorer configuration',
+        'explicit excluded evaluation/cohort identity and domain; lineage declarations remain unverified',
+        'separate probability grading policy; raw utilities or PU outputs are not calibrated probabilities'),
+    dependencies=(),score_fields=_FIELDS,supported_python=('3.11','3.12','3.13','3.14'),
+) for name in METHOD_NAMES)