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

sphynx/speech_contracts.py

@@ -0,0 +1,225 @@
+"""Versioned speech candidate wire contracts and provider-neutral serving helpers."""
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import math
+import re
+import sys
+import time
+
+TTS_REQUEST = "sphynx.speech.tts.request.v1"
+STT_REQUEST = "sphynx.speech.stt.request.v1"
+EVENT_SCHEMA = "sphynx.speech.stream-event.v1"
+FORMAT = {"encoding": "pcm_s16le", "sample_rate": 16000, "channels": 1}
+ERRORS = {"adapter_error", "missing_credential", "provider_http_error", "provider_timeout",
+          "empty_audio", "audio_limit", "invalid_pcm", "invalid_request"}
+
+
+class SpeechContractError(ValueError):
+    """A speech request, configuration or stream is invalid."""
+
+
+def require(condition, message):
+    if not condition:
+        raise SpeechContractError(message)
+
+
+def encode(value):
+    return (json.dumps(value, sort_keys=True, ensure_ascii=False, separators=(",", ":"), allow_nan=False) + "\n").encode()
+
+
+def sha(raw):
+    return hashlib.sha256(raw).hexdigest()
+
+
+def parse(raw):
+    def pairs(items):
+        result = {}
+        for key, value in items:
+            require(key not in result, "duplicate speech field")
+            result[key] = value
+        return result
+    def floating(value):
+        result = float(value)
+        require(math.isfinite(result), "nonfinite speech number")
+        return result
+    try:
+        return json.loads(raw, object_pairs_hook=pairs, parse_float=floating,
+                          parse_constant=lambda _: require(False, "nonfinite speech number"))
+    except (ValueError, UnicodeError, RecursionError):
+        raise SpeechContractError("invalid speech JSON") from None
+
+
+def fields(value, keys):
+    require(isinstance(value, dict) and set(value) == set(keys), "speech fields differ from contract")
+
+
+def identifier(value):
+    require(isinstance(value, str) and re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}", value), "invalid speech identifier")
+    return value
+
+
+def checksum(value):
+    require(isinstance(value, str) and re.fullmatch(r"[0-9a-f]{64}", value), "invalid speech digest")
+    return value
+
+
+def validate_method(method):
+    fields(method, ("mode", "provider", "model", "voice_id", "api_version", "fixture_samples", "fixture_chunk_samples"))
+    require(method["mode"] in ("fixture", "provider"), "unsupported speech execution mode")
+    identifier(method["model"])
+    if method["mode"] == "fixture":
+        require(method["provider"] == "fixture" and method["voice_id"] is None and method["api_version"] is None,
+                "fixture cannot declare a live provider")
+        require(all(type(method[k]) is int and 1 <= method[k] <= 16000 for k in ("fixture_samples", "fixture_chunk_samples")),
+                "fixture sample limits are invalid")
+    else:
+        require(method["provider"] in ("elevenlabs", "cartesia"), "unsupported provider transport")
+        require(method["fixture_samples"] is None and method["fixture_chunk_samples"] is None, "provider cannot contain fixture settings")
+        require(isinstance(method["voice_id"], str) and re.fullmatch(r"[A-Za-z0-9_-]{1,128}", method["voice_id"]), "invalid voice ID")
+        require(method["api_version"] == ("2026-08-14" if method["provider"] == "cartesia" else None), "unsupported API version")
+    return method
+
+
+def validate_request(request):
+    fields(request, ("schema_version", "request_id", "case_id", "method_id", "config", "config_sha256", "input", "format", "limits"))
+    require(request["schema_version"] in (TTS_REQUEST, STT_REQUEST), "unsupported speech request")
+    for key in ("request_id", "case_id", "method_id"):
+        identifier(request[key])
+    fields(request["format"], FORMAT)
+    require(request["format"] == FORMAT and type(request["format"]["sample_rate"]) is int
+            and type(request["format"]["channels"]) is int, "unsupported speech audio format")
+    fields(request["limits"], ("max_audio_bytes", "timeout_seconds"))
+    require(type(request["limits"]["max_audio_bytes"]) is int and 2 <= request["limits"]["max_audio_bytes"] <= 8_000_000,
+            "invalid speech audio byte limit")
+    require(type(request["limits"]["timeout_seconds"]) is int and 1 <= request["limits"]["timeout_seconds"] <= 120,
+            "invalid speech timeout")
+    require(checksum(request["config_sha256"]) == sha(encode(request["config"])), "speech configuration digest differs")
+    if request["schema_version"] == TTS_REQUEST:
+        validate_method(request["config"])
+        fields(request["input"], ("text", "language"))
+        require(isinstance(request["input"]["text"], str) and 0 < len(request["input"]["text"]) <= 10000,
+                "TTS text is empty or oversized")
+    else:
+        fields(request["config"], ("text_mode",))
+        require(request["config"]["text_mode"] in ("delta", "snapshot"), "declare STT transcript semantics")
+        fields(request["input"], ("audio_base64", "audio_sha256", "language"))
+        raw = decode_audio(request["input"]["audio_base64"])
+        require(raw and len(raw) % 2 == 0 and len(raw) <= request["limits"]["max_audio_bytes"], "invalid STT PCM input")
+        require(sha(raw) == checksum(request["input"]["audio_sha256"]), "STT input audio digest differs")
+    require(isinstance(request["input"]["language"], str) and re.fullmatch(r"[a-z]{2}(?:-[A-Za-z]{2,4})?", request["input"]["language"]), "invalid speech language")
+    return request
+
+
+def decode_audio(value):
+    require(isinstance(value, str) and len(value) <= 11_000_000, "invalid speech chunk")
+    try:
+        return base64.b64decode(value, validate=True)
+    except ValueError:
+        raise SpeechContractError("invalid speech base64") from None
+
+
+class StreamValidator:
+    """Strict sequencing, request binding and terminal audio integrity."""
+    def __init__(self, request):
+        self.request = validate_request(request)
+        self.count = 0
+        self.last_ns = -1
+        self.terminal = None
+        self.total_bytes = 0
+        self.audio_hash = hashlib.sha256()
+        self.transcript = ""
+        self.final_seen = False
+
+    def accept(self, event):
+        common = {"schema_version", "request_id", "config_sha256", "seq", "t_ns", "type"}
+        kind = event.get("type") if isinstance(event, dict) else None
+        extras = {"start": set(), "audio": {"data_base64"}, "transcript": {"text", "is_final"},
+                  "terminal": {"status", "error_code", "audio_sha256", "audio_bytes", "identity_evidence"}}
+        require(isinstance(kind, str) and kind in extras and self.terminal is None, "unexpected speech event or event after terminal")
+        fields(event, common | extras[kind])
+        require(event["schema_version"] == EVENT_SCHEMA and event["request_id"] == self.request["request_id"]
+                and event["config_sha256"] == self.request["config_sha256"], "speech event request/config binding differs")
+        require(type(event["seq"]) is int and event["seq"] == self.count, "speech event sequence gap or duplicate")
+        require(type(event["t_ns"]) is int and 0 <= event["t_ns"] and self.last_ns <= event["t_ns"] <= self.request["limits"]["timeout_seconds"] * 1_000_000_000,
+                "speech event clock is invalid")
+        require((self.count == 0) == (kind == "start"), "speech stream must start exactly once")
+        self.count += 1
+        self.last_ns = event["t_ns"]
+        audio = b""
+        if kind == "audio":
+            require(self.request["schema_version"] == TTS_REQUEST, "STT output cannot contain synthesis audio")
+            audio = decode_audio(event["data_base64"])
+            require(audio and len(audio) <= 8192, "speech audio event is empty or oversized")
+            self.total_bytes += len(audio)
+            require(self.total_bytes <= self.request["limits"]["max_audio_bytes"], "speech audio byte limit exceeded")
+            self.audio_hash.update(audio)
+        elif kind == "transcript":
+            require(self.request["schema_version"] == STT_REQUEST and not self.final_seen, "unexpected transcript after final")
+            require(isinstance(event["text"], str) and len(event["text"]) <= 20000 and type(event["is_final"]) is bool, "invalid transcript event")
+            if self.request["config"]["text_mode"] == "delta":
+                self.transcript += event["text"]
+            else:
+                self.transcript = event["text"]
+            require(len(self.transcript) <= 20000, "STT output exceeds transcript limit")
+            self.final_seen = event["is_final"]
+        elif kind == "terminal":
+            require(event["status"] in ("success", "error") and type(event["audio_bytes"]) is int and
+                    event["audio_bytes"] == self.total_bytes and event["audio_sha256"] == self.audio_hash.hexdigest(),
+                    "terminal speech status or audio identity differs")
+            require(event["error_code"] is None if event["status"] == "success" else isinstance(event["error_code"], str) and event["error_code"] in ERRORS,
+                    "invalid terminal speech error code")
+            fields(event["identity_evidence"], ("endpoint", "observed_model", "observed_voice", "cache_status"))
+            require(event["identity_evidence"]["cache_status"] in ("fixture", "unknown"), "unsupported speech cache attestation")
+            require(all(value is None or (isinstance(value, str) and len(value) <= 256)
+                        for value in event["identity_evidence"].values()), "invalid provider identity evidence")
+            if event["status"] == "success":
+                require((self.total_bytes > 0 and self.total_bytes % 2 == 0) if self.request["schema_version"] == TTS_REQUEST else self.final_seen,
+                        "successful speech stream has no complete output")
+            self.terminal = event
+        return audio
+
+
+def serve_tts(adapter):
+    """Serve one validated request; adapter yields bytes, never grader data."""
+    raw = sys.stdin.buffer.read(65537)
+    try:
+        require(len(raw) <= 65536, "request exceeds limit")
+        request = validate_request(parse(raw))
+        require(request["schema_version"] == TTS_REQUEST, "TTS adapter requires a TTS request")
+    except (SpeechContractError, KeyError, TypeError):
+        raise SystemExit(2) from None
+    start = time.monotonic_ns()
+    seq, count, checksum_ = 0, 0, hashlib.sha256()
+    def emit(kind, **extra):
+        nonlocal seq
+        event = {"schema_version": EVENT_SCHEMA, "request_id": request["request_id"],
+            "config_sha256": request["config_sha256"], "seq": seq, "t_ns": time.monotonic_ns() - start,
+            "type": kind, **extra}
+        seq += 1
+        sys.stdout.buffer.write(encode(event)); sys.stdout.buffer.flush()
+    emit("start")
+    error = None
+    try:
+        for chunk in adapter(request):
+            require(isinstance(chunk, bytes) and 0 < len(chunk) <= 8192, "invalid adapter chunk")
+            if count + len(chunk) > request["limits"]["max_audio_bytes"]:
+                error = "audio_limit"; break
+            count += len(chunk); checksum_.update(chunk)
+            emit("audio", data_base64=base64.b64encode(chunk).decode("ascii"))
+        if error is None and (count == 0 or count % 2):
+            error = "empty_audio" if count == 0 else "invalid_pcm"
+    except Exception as exc:
+        # Only allow stable codes; exception text can contain credentials.
+        error = getattr(exc, "speech_error_code", "adapter_error")
+        if error not in ERRORS:
+            error = "adapter_error"
+    method = request["config"]
+    endpoint = {"elevenlabs": "https://api.elevenlabs.io/v1/text-to-speech/stream",
+                "cartesia": "https://api.cartesia.ai/tts/bytes"}.get(method["provider"])
+    emit("terminal", status="error" if error else "success", error_code=error,
+         audio_sha256=checksum_.hexdigest(), audio_bytes=count,
+         identity_evidence={"endpoint": endpoint, "observed_model": None, "observed_voice": None,
+                            "cache_status": "fixture" if method["mode"] == "fixture" else "unknown"})

sphynx/speech_evidence.py

@@ -0,0 +1,429 @@
+"""Independent offline speech suite, import invocation, and saved regrading.
+
+Run ``python -m sphynx.speech_evidence --help``. This module never starts a
+candidate, contacts a provider, executes imported code, or uses RAG invocation.
+Owner-held source/bundles/reports contain private text and must stay private.
+"""
+from __future__ import annotations
+
+import argparse
+import csv
+from collections import Counter, defaultdict
+from dataclasses import dataclass
+import json
+from pathlib import Path, PurePosixPath
+import re
+import stat
+import uuid
+
+from ._speech_kido import (SpeechEvidenceError, csv_rows, digest, encoded,
+                           json_value, normalize_kido, require)
+from ._speech_scoring import (NORMALIZATION, TOKEN_SCORER, score_transcript,
+                              timing_summary)
+
+SUITE_ID = "speech.saved-evidence.v1"
+INTERFACE_VERSION = "sphynx.speech.saved-evidence.v1"
+BUNDLE_SCHEMA = "sphynx.speech.saved-evidence.bundle.v1"
+INVOCATION_SCHEMA = "sphynx.speech.saved-evidence.invocation.v1"
+REPORT_SCHEMA = "sphynx.speech.saved-evidence.report.v1"
+GRADER_VERSION = "speech.saved-evidence.grader.v1"
+SOURCE_LOCK_SHA256 = "b2cd81f87658c9b8b9f8a618657bf6e64fd513fb510dcc8da81e101055e3c70e"
+_MAX_FILE = 16 * 1024 * 1024
+_MAX_TOTAL = 64 * 1024 * 1024
+
+
+def _source_lock(root):
+    """Reconstruct the reviewed inventory; a fixed digest admits only exact bytes.
+
+    Keep internal session/file inventories out of distributable package resources.
+    The inventory is metadata derived from the owner-supplied source export, and
+    its digest must equal the independently reviewed constant before admission.
+    """
+    names = {"results/isolated/official-v1/combined/trials.csv",
+        "provenance/manifests/combined-manifest.json", "results/human-eval/mapping.json",
+        "results/human-eval/scores.csv", "scripts/manifests/official-v1-live-sessions.json",
+        "scripts/wer_cer.py", "scripts/live_telemetry.py", "provenance/audio-evidence-manifest.csv",
+        "results/isolated/official-v1/analysis/per-provider-ttfa.csv",
+        "results/live-agent/official-v1/analysis/live-tts-ttfa-fresh-only-post-1756.csv",
+        "results/live-agent/official-v1/analysis/success-coverage-post-1756.csv"}
+    for relative in ("configs", "provenance/run-jsons"):
+        directory = root / relative
+        _plain(directory)
+        names.update(p.relative_to(root).as_posix() for p in directory.glob("*.json"))
+    for folder in ("hands-on-v1", "hands-on-ink2-v1"):
+        for name in ("corpus.json", "raw_results.json", "final_analysis.json"):
+            names.add("results/exploratory/cartesia-ink-2-stt/" + folder + "/" + name)
+    sessions = json_value(_read(root, "scripts/manifests/official-v1-live-sessions.json"))
+    directory = root / "results/live-agent/official-v1/raw-events"
+    _plain(directory)
+    require(isinstance(sessions, list) and len(sessions) <= 100, "invalid speech session inventory")
+    for session in sessions:
+        room = session.get("room_sid")
+        require(isinstance(room, str) and re.fullmatch(r"[A-Za-z0-9_-]{1,128}", room), "invalid session identity")
+        names.update(p.relative_to(root).as_posix() for p in directory.glob(room + "-*")
+                     if p.suffix in (".json", ".jsonl"))
+    require(len(names) <= 1000, "speech source has too many files")
+    pins, total = {}, 0
+    for name in sorted(names):
+        raw = _read(root, name)
+        total += len(raw)
+        require(total <= _MAX_TOTAL, "speech source exceeds total byte limit")
+        pins[name] = {"sha256": digest(raw), "size_bytes": len(raw)}
+    lock = {"schema_version": "sphynx.speech.source-lock.v1",
+        "repository": "https://github.com/sable-inc/sable-tts-eval",
+        "source_commit": "71ec7e89805360479ea19c5bb43fae7707229ce9", "files": pins}
+    raw = (json.dumps(lock, indent=2) + "\n").encode("utf-8")
+    require(digest(raw) == SOURCE_LOCK_SHA256, "speech source inventory differs from reviewed identity")
+    return lock
+
+
+def _sha(value):
+    require(isinstance(value, str) and re.fullmatch(r"[0-9a-f]{64}", value), "expected a complete speech SHA256")
+    return value
+
+
+def _plain(path):
+    """Refuse symlinks and Windows junction/reparse paths, including parents."""
+    for part in (path, *path.parents):
+        if part.exists() or part.is_symlink():
+            info = part.lstat()
+            require(not stat.S_ISLNK(info.st_mode) and
+                    not getattr(info, "st_file_attributes", 0) & getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400),
+                    "speech evidence paths cannot contain links or reparse points")
+
+
+def _read(root, relative):
+    require(isinstance(relative, str) and "\\" not in relative and ":" not in relative,
+            "unsafe speech artifact path")
+    rel = PurePosixPath(relative)
+    require(not rel.is_absolute() and all(p not in ("..", ".", "") for p in rel.parts)
+            and str(rel) == relative, "unsafe speech artifact path")
+    path = root.joinpath(*rel.parts)
+    _plain(path)
+    require(path.is_file() and path.stat().st_size <= _MAX_FILE, "speech artifact missing or oversized")
+    raw = path.read_bytes()
+    require(len(raw) <= _MAX_FILE, "speech artifact exceeds read limit")
+    return raw
+
+
+def _source_bytes(root, lock):
+    data, total = {}, 0
+    for path, receipt in lock["files"].items():
+        raw = _read(root, path)
+        require(len(raw) == receipt["size_bytes"] and digest(raw) == receipt["sha256"],
+                "speech source bytes differ from pinned identity: " + path)
+        total += len(raw)
+        require(total <= _MAX_TOTAL, "speech source exceeds total byte limit")
+        data[path] = raw
+    return data
+
+
+def _new_directory(path):
+    path = Path(path).absolute()
+    _plain(path)
+    path = path.resolve()
+    require(not path.exists(), "speech output already exists")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.mkdir()
+    return path
+
+
+def _lines(rows):
+    return b"".join(encoded(row) for row in rows)
+
+
+def _write_files(root, payloads):
+    receipts = {}
+    for name, raw in payloads.items():
+        target = root.joinpath(*PurePosixPath(name).parts)
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with target.open("xb") as stream:
+            stream.write(raw)
+        receipts[name] = {"sha256": digest(raw), "size_bytes": len(raw)}
+    return receipts
+
+
+def import_kido_speech_evidence(source, output_dir) -> dict:
+    """Import only the installed, byte-pinned source revision, entirely offline.
+
+    Raw selected files are retained as inert evidence. No audio is copied and
+    external paths from source metadata are never opened. Failure leaves no
+    finalized manifest. An existing destination is never overwritten.
+    """
+    root = Path(source).absolute()
+    lock = _source_lock(root)
+    raw = _source_bytes(root, lock)
+    observations, references, audit = normalize_kido(raw)
+    destination = _new_directory(output_dir)
+    payloads = {"source/" + name: data for name, data in raw.items()}
+    payloads.update({"observations.jsonl": _lines(observations),
+                     "references.jsonl": _lines(references)})
+    receipts = _write_files(destination, payloads)
+    manifest = {"schema_version": BUNDLE_SCHEMA, "suite_id": SUITE_ID,
+        "source_repository": lock["repository"], "source_commit": lock["source_commit"],
+        "source_lock_sha256": SOURCE_LOCK_SHA256,
+        "counts": dict(Counter(r["track"] for r in observations)),
+        "reference_count": len(references), "audit": audit, "files": receipts,
+        "execution_mode": "saved_evidence_import", "fresh_model_execution": False,
+        "candidate_execution_available": False, "hosted_admitted": False}
+    raw_manifest = encoded(manifest)
+    (destination / "manifest.json").write_bytes(raw_manifest)  # commit marker LAST
+    return {"path": str(destination), "suite_id": SUITE_ID,
+            "manifest_sha256": digest(raw_manifest), "counts": manifest["counts"], "audit": audit}
+
+
+@dataclass(frozen=True)
+class SpeechEvidence:
+    path: Path
+    manifest_sha256: str
+
+    @property
+    def manifest(self):
+        return _verified(self)[0]
+
+
+def _verified(bundle):
+    raw_manifest = _read(bundle.path, "manifest.json")
+    require(digest(raw_manifest) == _sha(bundle.manifest_sha256), "speech bundle manifest changed")
+    manifest = json_value(raw_manifest)
+    require(manifest.get("schema_version") == BUNDLE_SCHEMA and manifest.get("suite_id") == SUITE_ID,
+            "not a saved speech evidence bundle")
+    lock = _source_lock(bundle.path / "source")
+    require(manifest.get("source_lock_sha256") == SOURCE_LOCK_SHA256 and
+            manifest.get("source_commit") == lock["source_commit"] and
+            manifest.get("source_repository") == lock["repository"], "speech source identity mismatch")
+    expected_paths = {"source/" + p for p in lock["files"]} | {"observations.jsonl", "references.jsonl"}
+    require(isinstance(manifest.get("files"), dict) and set(manifest["files"]) == expected_paths,
+            "speech bundle file census changed")
+    payloads, total = {}, 0
+    for path, receipt in manifest["files"].items():
+        raw = _read(bundle.path, path)
+        require(isinstance(receipt, dict) and receipt.get("size_bytes") == len(raw)
+                and receipt.get("sha256") == digest(raw), "speech bundle artifact changed")
+        total += len(raw)
+        require(total <= _MAX_TOTAL, "speech bundle exceeds total byte limit")
+        payloads[path] = raw
+    source = {p: payloads["source/" + p] for p in lock["files"]}
+    require(all(digest(source[p]) == r["sha256"] and len(source[p]) == r["size_bytes"]
+                for p, r in lock["files"].items()), "speech source archive differs from lock")
+    observations, references, audit = normalize_kido(source)
+    require(payloads["observations.jsonl"] == _lines(observations) and
+            payloads["references.jsonl"] == _lines(references), "normalized speech records differ from source")
+    require(manifest.get("counts") == dict(Counter(r["track"] for r in observations)) and
+            manifest.get("reference_count") == len(references) and manifest.get("audit") == audit,
+            "speech census or audit changed")
+    require(manifest.get("execution_mode") == "saved_evidence_import" and
+            manifest.get("fresh_model_execution") is False and
+            manifest.get("candidate_execution_available") is False and manifest.get("hosted_admitted") is False,
+            "saved speech execution boundary changed")
+    return manifest, observations, references
+
+
+def load_speech_evidence(path, *, expected_manifest_sha256) -> SpeechEvidence:
+    bundle = SpeechEvidence(Path(path).absolute(), _sha(expected_manifest_sha256))
+    _verified(bundle)
+    return bundle
+
+
+def describe_speech_suite():
+    """Dedicated local definition; deliberately separate from RAG discovery."""
+    return {"suite_id": SUITE_ID, "interface_version": INTERFACE_VERSION,
+        "invocation_schema": INVOCATION_SCHEMA, "grader_version": GRADER_VERSION,
+        "execution_mode": "saved_evidence_regrade", "runnable_locally": True,
+        "hosted_admitted": False, "fresh_model_execution": False,
+        "tracks": ["tts_isolated", "tts_live", "tts_live_session", "stt_recognition", "tts_listening"],
+        "normalization": NORMALIZATION, "structured_token_scorer": TOKEN_SCORER,
+        "implementation_sha256": {name: digest(Path(__file__).with_name(name).read_bytes()) for name in
+                                  ("speech_evidence.py", "_speech_kido.py", "_speech_scoring.py")}}
+
+
+def speech_candidate_view(bundle: SpeechEvidence, *, task: str) -> dict:
+    """Return an explicit future-input view; never transcripts, gold or ratings.
+
+    TTS has source text. STT has no bundled audio, so it remains non-executable.
+    This view is not permission, an execution adapter, or hosted admission.
+    """
+    require(task in ("stt", "tts"), "select exactly one speech input task")
+    manifest, observations, _ = _verified(bundle)
+    cases = {}
+    for row in observations:
+        if task == "tts" and row["track"] == "tts_isolated":
+            key = "tts/" + row["case_id"]
+            case = {"id": key, "task": "tts", "text": row["input_text"], "language": row["language"]}
+            require(key not in cases or cases[key] == case, "TTS input identity collision")
+            cases[key] = case
+        elif task == "stt" and row["track"] == "stt_recognition":
+            key = "stt/" + row["case_id"]
+            cases[key] = {"id": key, "task": "stt", "audio_available": False, "audio_sha256": None}
+    return {"suite_id": SUITE_ID, "task": task, "bundle_sha256": bundle.manifest_sha256,
+            "source_commit": manifest["source_commit"], "candidate_execution_available": False,
+            "cases": sorted(cases.values(), key=lambda r: r["id"])}
+
+
+def _grade_rows(observations, references):
+    references = {r["id"]: r for r in references}
+    groups = defaultdict(list)
+    for row in observations:
+        groups[(row["track"], row["cohort"], row["model"])].append(row)
+    summaries, per_case = [], []
+    for (track, cohort, model), rows in sorted(groups.items()):
+        summary = {"track": track, "cohort": cohort, "model": model, "observations": len(rows),
+            "clusters": len({r["cluster_id"] for r in rows}), "confidence_interval": None,
+            "uncertainty_status": "descriptive-dependent-historical-samples"}
+        if track == "stt_recognition":
+            scored = []
+            for row in rows:
+                ref = references.get(row["id"])
+                eligible = row["success"] and row["hypothesis"] is not None and ref is not None
+                score = score_transcript(ref["reference"], row["hypothesis"]) if eligible else None
+                if score is not None:
+                    scored.append(score)
+                per_case.append({"id": row["id"], "track": track, "cluster_id": row["cluster_id"],
+                                 "status": "scored" if eligible else "unavailable", "score": score})
+            words = sum(r["reference_words"] for r in scored)
+            chars = sum(r["reference_characters"] for r in scored)
+            word_errors = sum(r["word_errors"] for r in scored if r["reference_words"])
+            char_errors = sum(r["character_errors"] for r in scored if r["reference_characters"])
+            complete = len(scored) == len(rows)
+            summary.update({"scored": len(scored), "unavailable": len(rows) - len(scored),
+                "reference_words": words, "word_errors": word_errors, "reference_characters": chars,
+                "character_errors": char_errors,
+                "wer": word_errors / words if words and complete else None,
+                "cer": char_errors / chars if chars and complete else None,
+                "observed_subset_wer": word_errors / words if words else None,
+                "observed_subset_cer": char_errors / chars if chars else None,
+                "silence_inserted_words": sum(r["silence_inserted_words"] for r in scored),
+                "normalization": NORMALIZATION, "structured_token_scorer": TOKEN_SCORER})
+            summary["structured_tokens"] = {}
+            for token in (scored[0]["structured_tokens"] if scored else {}):
+                count = sum(r["structured_tokens"][token]["reference_tokens"] for r in scored)
+                matched = sum(r["structured_tokens"][token]["matched"] for r in scored)
+                summary["structured_tokens"][token] = {"matched": matched, "reference_tokens": count,
+                    "accuracy": matched / count if count and complete else None}
+        elif track in ("tts_isolated", "tts_live"):
+            success = [r for r in rows if r["success"]]
+            summary.update({"successful": len(success), "failed_or_cancelled": len(rows) - len(success)})
+            if track == "tts_live":
+                fresh = [r for r in success if not r["cache_hit"] and r["observed_provider"] == r["provider"]]
+                summary["successful_cache_replays"] = sum(r["cache_hit"] for r in success)
+                summary["provider_mismatch_attempts"] = sum(r["observed_provider"] != r["provider"] for r in rows)
+                summary["cancelled_with_audio"] = sum(r["cancelled"] and r["audio_bytes"] > 0 for r in rows)
+                summary["model_identity_observed"] = sum(r["observed_model"] is not None for r in rows)
+                summary["model_identity_mismatch"] = sum(r["observed_model"] is not None and r["observed_model"] != r["model"] for r in rows)
+                summary["missing_session_metadata_attempts"] = sum(not r["session_metadata_present"] for r in rows)
+                convention = "kido.live-median-rounded-index.v1"
+                summary["timing_scope"] = "server-synthesis-start-to-first-audio-bytes-not-audible-response"
+            else:
+                fresh, convention = success, "kido.isolated-rounded-index.v1"
+                summary["timing_scope"] = "source-Stream-call-to-first-nonempty-Read-not-audible-response"
+            values = [r["ttfa_ms"] for r in fresh if r["ttfa_ms"] is not None]
+            summary["fresh_valid_ttfa_ms"] = timing_summary(values, convention=convention)
+            summary["fresh_timing_missing"] = len(fresh) - len(values)
+            summary["perceived_latency_ms"] = None
+        elif track == "tts_listening":
+            scores = [references[r["id"]]["overall_quality"] for r in rows]
+            available = [s for s in scores if s is not None]
+            summary.update({"rated": len(available), "pending": len(rows) - len(available),
+                "overall_quality_mean": sum(available) / len(available) if available and len(available) == len(rows) else None,
+                "observed_subset_mean": sum(available) / len(available) if available else None,
+                "naturalness": None, "perceived_waiting": None, "historical_study_rater_count": 1,
+                "review_scope": "historical-single-rater-overall-only"})
+        elif track == "tts_live_session":
+            summary.update({"legacy_provider_gate_passed": sum(r["legacy_provider_gate"] for r in rows),
+                "fallback_sessions": sum(r["fallback_observed"] for r in rows),
+                "sessions_without_synthesis": sum(r["attempts"] == 0 for r in rows),
+                "full_model_voice_verification": False})
+        summaries.append(summary)
+    return summaries, per_case
+
+
+def grade_speech_evidence(bundle: SpeechEvidence, output_dir) -> dict:
+    """Regrade saved evidence into a new speech-specific invocation and report."""
+    manifest, observations, references = _verified(bundle)
+    invocation_id = "speech-invocation-" + uuid.uuid4().hex
+    definition = describe_speech_suite()
+    invocation = {"schema_version": INVOCATION_SCHEMA, "id": invocation_id,
+        "suite_id": SUITE_ID, "definition_sha256": digest(encoded(definition)),
+        "implementation_sha256": definition["implementation_sha256"],
+        "bundle_manifest_sha256": bundle.manifest_sha256, "source_commit": manifest["source_commit"],
+        "grader_version": GRADER_VERSION, "mode": "saved_evidence_regrade", "candidate_executed": False,
+        "provider_called": False, "hosted_admitted": False}
+    summaries, per_case = _grade_rows(observations, references)
+    report = {"schema_version": REPORT_SCHEMA, "suite_id": SUITE_ID,
+        "invocation_id": invocation_id, "invocation_sha256": digest(encoded(invocation)),
+        "bundle_manifest_sha256": bundle.manifest_sha256, "grader_version": GRADER_VERSION,
+        "summaries": summaries, "per_case": per_case, "audit": manifest["audit"],
+        "limits": {"historical_observations_only": True, "fresh_performance_measured": False,
+                   "perceived_latency_measured": False, "population_inference_validated": False}}
+    output = _new_directory(output_dir)
+    receipts = _write_files(output, {"invocation.json": encoded(invocation), "report.json": encoded(report)})
+    receipt = {"schema_version": "sphynx.speech.saved-evidence.receipt.v1", "suite_id": SUITE_ID,
+               "invocation_id": invocation_id, "files": receipts}
+    raw = encoded(receipt)
+    (output / "receipt.json").write_bytes(raw)
+    return {"path": str(output), "suite_id": SUITE_ID, "invocation_id": invocation_id,
+            "receipt_sha256": digest(raw), "report_sha256": receipts["report.json"]["sha256"]}
+
+
+def load_speech_evaluation(path, *, expected_receipt_sha256) -> dict:
+    root = Path(path).absolute()
+    raw = _read(root, "receipt.json")
+    require(digest(raw) == _sha(expected_receipt_sha256), "speech evaluation receipt changed")
+    receipt = json_value(raw)
+    require(receipt.get("schema_version") == "sphynx.speech.saved-evidence.receipt.v1" and
+            receipt.get("suite_id") == SUITE_ID and set(receipt.get("files", {})) == {"invocation.json", "report.json"},
+            "not a saved speech evaluation")
+    results = {}
+    for name, entry in receipt["files"].items():
+        data = _read(root, name)
+        require(entry.get("sha256") == digest(data) and entry.get("size_bytes") == len(data), "speech evaluation artifact changed")
+        results[name] = json_value(data)
+    invocation, report = results["invocation.json"], results["report.json"]
+    require(invocation.get("schema_version") == INVOCATION_SCHEMA and report.get("schema_version") == REPORT_SCHEMA
+            and invocation.get("suite_id") == report.get("suite_id") == SUITE_ID
+            and invocation.get("id") == receipt.get("invocation_id") == report.get("invocation_id")
+            and report.get("invocation_sha256") == digest(encoded(invocation))
+            and report.get("bundle_manifest_sha256") == invocation.get("bundle_manifest_sha256"),
+            "speech report and invocation identities differ")
+    require(invocation.get("mode") == "saved_evidence_regrade" and
+            invocation.get("candidate_executed") is False and invocation.get("provider_called") is False and
+            invocation.get("hosted_admitted") is False and
+            invocation.get("grader_version") == report.get("grader_version") == GRADER_VERSION,
+            "speech evaluation execution scope differs")
+    _sha(invocation.get("definition_sha256"))
+    implementations = invocation.get("implementation_sha256", {})
+    require(isinstance(implementations, dict) and set(implementations) ==
+            {"speech_evidence.py", "_speech_kido.py", "_speech_scoring.py"}, "missing speech grader source identities")
+    for value in implementations.values():
+        _sha(value)
+    return report
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Independent offline speech.saved-evidence.v1 suite; no provider calls")
+    commands = parser.add_subparsers(dest="command", required=True)
+    commands.add_parser("describe")
+    prepare = commands.add_parser("import-kido")
+    prepare.add_argument("--source", required=True)
+    prepare.add_argument("--output", required=True)
+    grade = commands.add_parser("grade")
+    grade.add_argument("--bundle", required=True)
+    grade.add_argument("--expected-manifest-sha256", required=True)
+    grade.add_argument("--output", required=True)
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "describe":
+            result = describe_speech_suite()
+        elif args.command == "import-kido":
+            result = import_kido_speech_evidence(args.source, args.output)
+        else:
+            result = grade_speech_evidence(load_speech_evidence(args.bundle,
+                expected_manifest_sha256=args.expected_manifest_sha256), args.output)
+    except (SpeechEvidenceError, OSError, KeyError, TypeError, csv.Error) as exc:
+        # No source text, provider error payload, reference label or secret in CLI diagnostics.
+        parser.exit(2, "speech evidence operation failed (" + type(exc).__name__ + "); check source pins and output path\n")
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()