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

sphynx/speech_tts.py

@@ -0,0 +1,479 @@
+"""Independent, trusted-local TTS candidate execution and saved grading.
+
+No hosted admission or automatic provider launch. Freeze source and inputs,
+inspect the plan, then execute fixtures or explicitly authorize provider calls.
+"""
+from __future__ import annotations
+
+import argparse
+import base64
+from collections import Counter
+import hashlib
+import io
+import json
+import math
+import os
+from pathlib import Path, PurePosixPath
+import platform
+import queue
+import re
+import subprocess
+import sys
+import threading
+import time
+import uuid
+import wave
+
+from .speech_contracts import (EVENT_SCHEMA, FORMAT, TTS_REQUEST, SpeechContractError,
+    StreamValidator, checksum, encode, fields, identifier, parse, require, sha, validate_method, validate_request)
+from .speech_evidence import _new_directory as _saved_new_directory, _read as _saved_read, _write_files
+
+SUITE_ID = "speech.tts.execution.v1"
+PLAN_SCHEMA = "sphynx.speech.tts.plan.v1"
+INVOCATION_SCHEMA = "sphynx.speech.tts.execution-invocation.v1"
+FAMILY_SCHEMA = "sphynx.speech.tts.family.v1"
+RUN_SCHEMA = "sphynx.speech.tts.run.v1"
+GRADER = "speech.tts.integrity-grader.v1"
+FAMILY_PATH = "sphynx_candidates/tts/family.json"
+_BOOTSTRAP = {"PATH", "PATHEXT", "SYSTEMROOT", "WINDIR", "COMSPEC", "TEMP", "TMP", "TMPDIR", "HOME", "USERPROFILE", "LANG"}
+_CREDENTIAL = {"elevenlabs": "ELEVEN_API_KEY", "cartesia": "CARTESIA_API_KEY"}
+
+
+def _new_directory(path):
+    try:
+        return _saved_new_directory(path)
+    except ValueError as exc:
+        raise SpeechContractError(str(exc)) from None
+
+
+def _read(root, path):
+    try:
+        return _saved_read(root, path)
+    except ValueError as exc:
+        raise SpeechContractError(str(exc)) from None
+
+
+def describe_tts_suite():
+    return {"suite_id": SUITE_ID, "plan_schema": PLAN_SCHEMA, "invocation_schema": INVOCATION_SCHEMA,
+        "request_schema": TTS_REQUEST, "event_schema": EVENT_SCHEMA, "grader": GRADER,
+        "execution": "trusted_local_subprocess", "hosted_admitted": False,
+        "provider_authorization": "explicit_launch_flag_required", "os_isolation": False,
+        "perceived_latency_measured": False, "stt_execution": "contract_only"}
+
+
+def _relative(path):
+    require(isinstance(path, str) and re.fullmatch(r"[A-Za-z0-9_./-]{1,240}", path)
+            and all(p not in ("", ".", "..") and not p.startswith(".") for p in path.split("/")),
+            "invalid speech source path")
+    return path
+
+
+def _family(raw):
+    value = parse(raw)
+    fields(value, ("schema_version", "entry_point", "source_files", "methods"))
+    require(value["schema_version"] == FAMILY_SCHEMA, "unsupported speech candidate family")
+    _relative(value["entry_point"])
+    require(isinstance(value["source_files"], list) and 1 <= len(value["source_files"]) <= 16,
+            "invalid speech source closure")
+    for path in value["source_files"]:
+        _relative(path)
+    require(len(set(value["source_files"])) == len(value["source_files"]) and FAMILY_PATH in value["source_files"]
+            and value["entry_point"] in value["source_files"], "incomplete candidate source closure")
+    require(isinstance(value["methods"], dict) and 1 <= len(value["methods"]) <= 8, "invalid speech method census")
+    for key, method in value["methods"].items():
+        identifier(key); validate_method(method)
+    return value
+
+
+def _git(root, *args):
+    result = subprocess.run(["git", "-C", str(root), *args], capture_output=True, timeout=15, check=False)
+    require(result.returncode == 0 and len(result.stdout) <= 1_000_000, "could not verify local candidate Git source")
+    return result.stdout
+
+
+def freeze_tts_plan(repository, *, source_commit, source_pr, cases, cohort_identity,
+                    baseline, candidate, output_dir, repetitions=1, timeout_seconds=30,
+                    max_audio_bytes=2_000_000, max_requests=20):
+    """Freeze two named methods from one exact local Git commit, without execution."""
+    require(isinstance(source_commit, str) and re.fullmatch(r"[0-9a-f]{40}", source_commit), "pin the complete candidate commit")
+    match = re.fullmatch(r"https://github.com/([A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+)/pull/([1-9][0-9]*)", source_pr)
+    require(match is not None, "pin the candidate source PR")
+    root = Path(repository).absolute()
+    origin = _git(root, "config", "--get", "remote.origin.url").decode().strip()
+    repo_name = match.group(1)
+    require(origin in (f"https://github.com/{repo_name}.git", f"https://github.com/{repo_name}", f"git@github.com:{repo_name}.git"),
+            "candidate PR and local repository origin differ")
+    require(_git(root, "rev-parse", "HEAD").decode().strip() == source_commit, "candidate checkout is not the requested commit")
+    family_raw = _git(root, "cat-file", "blob", source_commit + ":" + FAMILY_PATH)
+    family = _family(family_raw)
+    require(baseline != candidate and baseline in family["methods"] and candidate in family["methods"], "select two distinct named methods")
+    require(family["methods"][baseline]["mode"] == family["methods"][candidate]["mode"], "fixture and provider arms cannot be mixed")
+    require(type(repetitions) is int and 1 <= repetitions <= 3 and type(timeout_seconds) is int and 1 <= timeout_seconds <= 120,
+            "invalid TTS trial limits")
+    require(type(max_audio_bytes) is int and 2 <= max_audio_bytes <= 8_000_000 and max_audio_bytes % 2 == 0,
+            "invalid TTS audio limit")
+    require(type(max_requests) is int and 2 <= max_requests <= 20, "pilot request budget must be between 2 and 20")
+    require(isinstance(cases, list) and 0 < len(cases) <= 10, "select one to ten pilot cases")
+    for case in cases:
+        fields(case, ("id", "text", "language")); identifier(case["id"])
+        require(isinstance(case["text"], str) and 0 < len(case["text"]) <= 10000, "invalid TTS pilot text")
+        require(isinstance(case["language"], str) and re.fullmatch(r"[a-z]{2}(?:-[A-Za-z]{2,4})?", case["language"]), "invalid TTS pilot language")
+    require(len({c["id"] for c in cases}) == len(cases), "duplicate pilot cases")
+    fields(cohort_identity, ("kind", "sha256")); identifier(cohort_identity["kind"]); checksum(cohort_identity["sha256"])
+    planned_calls = len(cases) * 2 * repetitions
+    require(planned_calls <= max_requests, "pilot exceeds request budget")
+    require(sum(len(c["text"]) for c in cases) * 2 * repetitions <= 20000, "pilot exceeds input-character budget")
+    sources = {}
+    for path in family["source_files"]:
+        blob = _git(root, "cat-file", "blob", source_commit + ":" + path)
+        require(_read(root, path) == blob, "candidate working bytes differ from pinned Git source")
+        sources["source/" + path] = blob
+    output = _new_directory(output_dir)
+    files = _write_files(output, sources)
+    plan = {"schema_version": PLAN_SCHEMA, "suite_id": SUITE_ID, "id": "tts-plan-" + uuid.uuid4().hex,
+        "source_pr": source_pr, "source_commit": source_commit, "family_path": FAMILY_PATH,
+        "family_sha256": sha(family_raw), "entry_point": family["entry_point"], "files": files,
+        "baseline": baseline, "candidate": candidate, "methods": {k: family["methods"][k] for k in (baseline, candidate)},
+        "cases": cases, "cases_sha256": sha(encode(cases)), "cohort_identity": cohort_identity,
+        "repetitions": repetitions, "limits": {"timeout_seconds": timeout_seconds, "max_audio_bytes": max_audio_bytes},
+        "budget": {"max_requests": max_requests, "planned_requests": planned_calls,
+                   "planned_input_characters": sum(len(c["text"]) for c in cases) * 2 * repetitions,
+                   "retries": 0, "cost_usd": None, "monetary_cap_enforced": False},
+        "mode": family["methods"][baseline]["mode"], "review_status": "prepared_for_review",
+        "model_voice_availability_verified": False, "hosted_admitted": False}
+    raw = encode(plan); (output / "plan.json").write_bytes(raw)
+    return {"path": str(output), "plan_sha256": sha(raw), "suite_id": SUITE_ID, "budget": plan["budget"],
+            "mode": plan["mode"], "provider_calls_made": False}
+
+
+def _load_plan(path, expected_sha256):
+    root = Path(path).absolute()
+    raw = _read(root, "plan.json")
+    require(sha(raw) == checksum(expected_sha256), "TTS plan digest differs")
+    plan = parse(raw)
+    require(plan.get("schema_version") == PLAN_SCHEMA and plan.get("suite_id") == SUITE_ID,
+            "not an executable TTS plan")
+    require(isinstance(plan.get("files"), dict) and len(plan["files"]) <= 16, "invalid TTS source census")
+    for path_, receipt in plan["files"].items():
+        require(path_.startswith("source/"), "invalid TTS source archive path")
+        _relative(path_[7:])
+        data = _read(root, path_)
+        require(len(data) == receipt["size_bytes"] and sha(data) == receipt["sha256"], "frozen TTS source changed")
+    family = _family(_read(root, "source/" + FAMILY_PATH))
+    require(plan["family_sha256"] == sha(_read(root, "source/" + FAMILY_PATH)) and
+            set(plan["files"]) == {"source/" + p for p in family["source_files"]} and
+            plan["entry_point"] == family["entry_point"], "TTS source closure differs")
+    require(plan["baseline"] != plan["candidate"] and set(plan["methods"]) == {plan["baseline"], plan["candidate"]}, "TTS arm census differs")
+    require(all(plan["methods"][k] == family["methods"].get(k) for k in plan["methods"]), "TTS selected method changed")
+    require(all(m["mode"] == plan["mode"] for m in plan["methods"].values()), "TTS execution mode differs")
+    require(sha(encode(plan["cases"])) == plan["cases_sha256"] and len({c["id"] for c in plan["cases"]}) == len(plan["cases"]),
+            "TTS cases changed")
+    require(type(plan["repetitions"]) is int and 1 <= plan["repetitions"] <= 3 and 1 <= len(plan["cases"]) <= 10,
+            "TTS trial population is invalid")
+    require(plan["budget"]["planned_requests"] == len(plan["cases"]) * 2 * plan["repetitions"] <= plan["budget"]["max_requests"] <= 20
+            and plan["budget"]["retries"] == 0, "TTS request budget differs")
+    require(plan["budget"]["planned_input_characters"] == sum(len(c["text"]) for c in plan["cases"]) * 2 * plan["repetitions"] <= 20000,
+            "TTS character budget differs")
+    for case in plan["cases"]:
+        fields(case, ("id", "text", "language"))
+        for method in plan["methods"]:
+            validate_request(_request(plan, case, method, "preflight"))
+    return root, plan
+
+
+def _request(plan, case, method, request_id):
+    config = plan["methods"][method]
+    return {"schema_version": TTS_REQUEST, "request_id": request_id, "case_id": case["id"], "method_id": method,
+            "config": config, "config_sha256": sha(encode(config)), "input": {"text": case["text"], "language": case["language"]},
+            "format": FORMAT, "limits": plan["limits"]}
+
+
+def _execute(root, plan, request, authorize):
+    validator = StreamValidator(request)
+    env = {k: v for k, v in os.environ.items() if k.upper() in _BOOTSTRAP}
+    env.update(PYTHONPATH=str(Path(__file__).resolve().parents[1]), PYTHONUTF8="1", PYTHONDONTWRITEBYTECODE="1")
+    if request["config"]["mode"] == "provider":
+        require(authorize, "provider calls require explicit launch authorization")
+        key = _CREDENTIAL[request["config"]["provider"]]
+        require(bool(os.environ.get(key)), "selected provider credential is unavailable")
+        env[key] = os.environ[key]
+        env["SPHYNX_TTS_ALLOW_PROVIDER"] = "1"
+    started = time.monotonic_ns()
+    process = subprocess.Popen([sys.executable, str(root / "source" / plan["entry_point"])],
+        cwd=root / "source", env=env, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+    events_queue, stop = queue.Queue(maxsize=64), threading.Event()
+    stderr_count = [0]
+    def enqueue(item):
+        while not stop.is_set():
+            try:
+                events_queue.put(item, timeout=.05); return
+            except queue.Full:
+                pass
+    def read_stdout():
+        try:
+            while not stop.is_set():
+                line = process.stdout.readline(16385)
+                if not line:
+                    enqueue(("eof", None, time.monotonic_ns())); return
+                if len(line) > 16384:
+                    enqueue(("overflow", None, time.monotonic_ns())); return
+                enqueue(("line", line, time.monotonic_ns()))
+        except OSError:
+            enqueue(("reader_error", None, time.monotonic_ns()))
+    def discard_stderr():
+        try:
+            while True:
+                chunk = process.stderr.read(8192)
+                if not chunk:
+                    return
+                stderr_count[0] += len(chunk)
+        except OSError:
+            pass
+    def write_input():
+        try:
+            process.stdin.write(encode(request)); process.stdin.flush()
+        except (OSError, ValueError):
+            pass
+        finally:
+            try:
+                process.stdin.close()
+            except (OSError, ValueError):
+                pass
+    readers = [threading.Thread(target=read_stdout, daemon=True), threading.Thread(target=discard_stderr, daemon=True),
+               threading.Thread(target=write_input, daemon=True)]
+    for reader in readers:
+        reader.start()
+    audio, events, first, failure, stream_bytes = bytearray(), [], None, None, 0
+    deadline = time.monotonic() + request["limits"]["timeout_seconds"]
+    try:
+        while True:
+            left = deadline - time.monotonic()
+            if left <= 0:
+                failure = "timeout"; break
+            try:
+                kind, line, arrived = events_queue.get(timeout=left)
+            except queue.Empty:
+                failure = "timeout"; break
+            if kind == "eof":
+                break
+            if kind != "line":
+                failure = "stream_limit_or_read_error"; break
+            if len(events) >= 4096:
+                failure = "event_limit"; break
+            stream_bytes += len(line)
+            if stream_bytes > request["limits"]["max_audio_bytes"] * 2 + 65536:
+                failure = "stream_limit"; break
+            event = parse(line)
+            chunk = validator.accept(event)
+            if chunk:
+                if first is None:
+                    first = arrived
+                audio.extend(chunk)
+            events.append({"event": event, "parent_received_ns": arrived - started})
+        if failure is None:
+            process.wait(timeout=max(.01, deadline - time.monotonic()))
+            if process.returncode != 0 or validator.terminal is None:
+                failure = "process_error_or_missing_terminal"
+            elif validator.terminal["status"] != "success":
+                failure = validator.terminal["error_code"]
+    except (SpeechContractError, KeyError, TypeError, ValueError):
+        failure = "invalid_stream"
+    except subprocess.TimeoutExpired:
+        failure = "timeout"
+    finally:
+        stop.set()
+        if process.poll() is None:
+            process.kill(); process.wait(timeout=5)
+        for reader in readers:
+            reader.join(timeout=1)
+        process.stdout.close(); process.stderr.close()
+        if not process.stdin.closed:
+            try:
+                process.stdin.close()
+            except OSError:
+                pass
+    return {"request_id": request["request_id"], "case_id": request["case_id"], "method_id": request["method_id"],
+        "config_sha256": request["config_sha256"], "success": failure is None, "failure": failure,
+        "audio_bytes": len(audio), "audio_sha256": sha(bytes(audio)),
+        "pcm_complete": failure is None and len(audio) > 0 and len(audio) % 2 == 0,
+        "parent_first_audio_ms": (first - started) / 1_000_000 if first is not None else None,
+        "parent_completion_ms": (time.monotonic_ns() - started) / 1_000_000,
+        "timing_scope": "parent-process-launch-to-validated-audio-event-includes-startup-and-IPC",
+        "candidate_reported_first_audio_ns": next((e["event"]["t_ns"] for e in events if e["event"]["type"] == "audio"), None),
+        "identity_evidence": validator.terminal["identity_evidence"] if validator.terminal else None,
+        "stderr_bytes_discarded": stderr_count[0], "exit_code": process.returncode,
+        "events": events}, bytes(audio)
+
+
+def run_tts_plan(path, *, expected_plan_sha256, output_dir, allow_provider_calls=False):
+    root, plan = _load_plan(path, expected_plan_sha256)
+    require(type(allow_provider_calls) is bool, "provider launch authorization must be explicit")
+    require(plan["mode"] == "fixture" or allow_provider_calls, "provider calls require explicit launch authorization")
+    # Validate both selected credentials before creating a run or starting either arm.
+    if plan["mode"] == "provider":
+        require(all(os.environ.get(_CREDENTIAL[m["provider"]]) for m in plan["methods"].values()), "selected provider credential is unavailable")
+    output = _new_directory(output_dir)
+    frozen = {"frozen-plan/plan.json": _read(root, "plan.json")}
+    frozen.update({"frozen-plan/" + name: _read(root, name) for name in plan["files"]})
+    artifacts = _write_files(output, frozen)
+    root, plan = _load_plan(output / "frozen-plan", expected_plan_sha256)
+    invocation_id = "tts-invocation-" + uuid.uuid4().hex
+    invocation = {"schema_version": INVOCATION_SCHEMA, "suite_id": SUITE_ID, "id": invocation_id,
+        "plan_sha256": expected_plan_sha256, "source_pr": plan["source_pr"], "source_commit": plan["source_commit"],
+        "mode": plan["mode"], "provider_calls_authorized": allow_provider_calls and plan["mode"] == "provider",
+        "provider_calls_observed": None if plan["mode"] == "provider" else 0,
+        "runtime": {"python": sys.version, "platform": platform.platform(), "machine": platform.machine()},
+        "implementation_sha256": {name: sha(Path(__file__).with_name(name).read_bytes()) for name in ("speech_tts.py", "speech_contracts.py")}}
+    (output / "invocation.json").write_bytes(encode(invocation))
+    captures = []
+    artifacts["invocation.json"] = {"sha256": sha(encode(invocation)), "size_bytes": len(encode(invocation))}
+    for rep in range(plan["repetitions"]):
+        for case_index, case in enumerate(plan["cases"]):
+            arms = (plan["baseline"], plan["candidate"])
+            if (rep + case_index) % 2:
+                arms = tuple(reversed(arms))
+            for method in arms:
+                request_id = "tts-request-" + uuid.uuid4().hex
+                request = _request(plan, case, method, request_id)
+                try:
+                    capture, audio = _execute(root, plan, request, allow_provider_calls)
+                except OSError:
+                    capture, audio = {"request_id": request_id, "case_id": case["id"], "method_id": method,
+                        "success": False, "failure": "process_start_error", "audio_bytes": 0, "audio_sha256": sha(b""),
+                        "pcm_complete": False, "parent_first_audio_ms": None, "parent_completion_ms": None,
+                        "events": []}, b""
+                capture["repetition"] = rep + 1
+                capture["order_index"] = len(captures)
+                capture["request_sha256"] = sha(encode(request))
+                relative = "captures/" + request_id + "/"
+                payloads = {relative + "request.json": encode(request), relative + "capture.json": encode(capture)}
+                if audio:
+                    wav = io.BytesIO()
+                    with wave.open(wav, "wb") as stream:
+                        stream.setnchannels(1); stream.setsampwidth(2); stream.setframerate(16000); stream.writeframes(audio)
+                    payloads[relative + "audio.wav"] = wav.getvalue()
+                artifacts.update(_write_files(output, payloads))
+                captures.append(capture)
+    report = grade_tts_captures(plan, captures)
+    report.update(invocation_id=invocation_id, invocation_sha256=sha(encode(invocation)), plan_sha256=expected_plan_sha256)
+    artifacts.update(_write_files(output, {"report.json": encode(report)}))
+    manifest = {"schema_version": RUN_SCHEMA, "suite_id": SUITE_ID, "invocation_id": invocation_id,
+                "plan_sha256": expected_plan_sha256, "files": artifacts,
+                "completed_requests": len(captures), "planned_requests": plan["budget"]["planned_requests"],
+                "status": "completed" if all(c["success"] for c in captures) else "completed_with_failures"}
+    raw = encode(manifest); (output / "manifest.json").write_bytes(raw)
+    return {"path": str(output), "suite_id": SUITE_ID, "invocation_id": invocation_id,
+            "manifest_sha256": sha(raw), "status": manifest["status"], "mode": plan["mode"]}
+
+
+def grade_tts_captures(plan, captures):
+    for capture in captures:
+        require(type(capture.get("success")) is bool, "TTS outcome must be a boolean")
+        value = capture.get("parent_first_audio_ms")
+        require(value is None or (type(value) in (int, float) and math.isfinite(value) and value >= 0),
+                "TTS timing must be finite and nonnegative")
+    expected = {(case["id"], method, rep + 1) for case in plan["cases"] for method in plan["methods"] for rep in range(plan["repetitions"])}
+    actual = [(c["case_id"], c["method_id"], c["repetition"]) for c in captures]
+    require(len(actual) == len(set(actual)) and set(actual) == expected, "TTS capture census is incomplete or duplicated")
+    arms = {}
+    for method in plan["methods"]:
+        rows = [c for c in captures if c["method_id"] == method]
+        times = [c["parent_first_audio_ms"] for c in rows if c["success"] and c["parent_first_audio_ms"] is not None]
+        arms[method] = {"attempts": len(rows), "successful": sum(c["success"] for c in rows),
+            "failure_counts": dict(Counter(c["failure"] for c in rows if c["failure"])),
+            "observed_success_first_audio_ms_mean": sum(times) / len(times) if times else None,
+            "timing_count": len(times), "provider_latency_ms": None, "perceived_latency_ms": None}
+    pairs = []
+    for case in plan["cases"]:
+        for rep in range(1, plan["repetitions"] + 1):
+            pair = {c["method_id"]: c for c in captures if c["case_id"] == case["id"] and c["repetition"] == rep}
+            left, right = pair[plan["baseline"]], pair[plan["candidate"]]
+            eligible = left["success"] and right["success"] and left["parent_first_audio_ms"] is not None and right["parent_first_audio_ms"] is not None
+            pairs.append({"case_id": case["id"], "repetition": rep, "paired_success": eligible,
+                          "parent_first_audio_delta_ms": right["parent_first_audio_ms"] - left["parent_first_audio_ms"] if eligible else None,
+                          "identical_pcm": left["audio_sha256"] == right["audio_sha256"] if eligible else None})
+    observed = [p["parent_first_audio_delta_ms"] for p in pairs if p["parent_first_audio_delta_ms"] is not None]
+    return {"schema_version": "sphynx.speech.tts.integrity-report.v1", "suite_id": SUITE_ID, "grader": GRADER,
+        "mode": plan["mode"], "arms": arms, "pairs": pairs, "paired_count": len(observed), "missing_pairs": len(pairs) - len(observed),
+        "primary_parent_first_audio_delta_ms": sum(observed) / len(observed) if observed and len(observed) == len(pairs) else None,
+        "confidence_interval": None, "quality": None, "cost_usd": None,
+        "timing_scope": "local process startup plus adapter plus IPC; not pure provider or audible latency",
+        "claim_scope": "fixture plumbing only" if plan["mode"] == "fixture" else "trusted local pilot; requested model/voice not independently attested"}
+
+
+def load_tts_run(path, *, expected_manifest_sha256):
+    root = Path(path).absolute(); raw = _read(root, "manifest.json")
+    require(sha(raw) == checksum(expected_manifest_sha256), "TTS run manifest differs")
+    manifest = parse(raw)
+    require(manifest.get("schema_version") == RUN_SCHEMA and manifest.get("suite_id") == SUITE_ID, "not a TTS execution run")
+    require(isinstance(manifest.get("files"), dict) and {"report.json", "invocation.json", "frozen-plan/plan.json"}.issubset(manifest["files"]),
+            "incomplete TTS run file census")
+    for name, receipt in manifest["files"].items():
+        data = _read(root, name)
+        require(sha(data) == receipt["sha256"] and len(data) == receipt["size_bytes"], "saved TTS artifact changed")
+    invocation, report = parse(_read(root, "invocation.json")), parse(_read(root, "report.json"))
+    require(report["invocation_sha256"] == sha(encode(invocation)) and
+            report["invocation_id"] == invocation["id"] == manifest["invocation_id"] and
+            report["plan_sha256"] == invocation["plan_sha256"] == manifest["plan_sha256"], "TTS run identity binding differs")
+    require(invocation.get("schema_version") == INVOCATION_SCHEMA and invocation.get("suite_id") == report.get("suite_id") == SUITE_ID,
+            "TTS invocation namespace differs")
+    _, plan = _load_plan(root / "frozen-plan", manifest["plan_sha256"])
+    captures = [parse(_read(root, name)) for name in manifest["files"] if name.startswith("captures/") and name.endswith("/capture.json")]
+    require(manifest["completed_requests"] == len(captures) == manifest["planned_requests"] == plan["budget"]["planned_requests"],
+            "saved TTS request census differs")
+    recomputed = grade_tts_captures(plan, captures)
+    cases = {c["id"]: c for c in plan["cases"]}
+    for capture in captures:
+        relative = "captures/" + identifier(capture["request_id"]) + "/"
+        expected_request = _request(plan, cases[capture["case_id"]], capture["method_id"], capture["request_id"])
+        require(_read(root, relative + "request.json") == encode(expected_request) and
+                capture["request_sha256"] == sha(encode(expected_request)), "saved TTS request differs from frozen inputs")
+        validator = StreamValidator(expected_request)
+        chunks = []
+        for item in capture["events"]:
+            chunks.append(validator.accept(item["event"]))
+        pcm = b"".join(chunks)
+        require(sha(pcm) == capture["audio_sha256"] and len(pcm) == capture["audio_bytes"], "saved TTS audio differs from events")
+        require(capture["success"] == (capture["failure"] is None), "TTS success and failure status differ")
+        if capture["success"]:
+            require(validator.terminal is not None and validator.terminal["status"] == "success", "successful saved TTS stream lacks terminal")
+        if pcm:
+            require(relative + "audio.wav" in manifest["files"], "saved TTS audio artifact is missing")
+            with wave.open(io.BytesIO(_read(root, relative + "audio.wav")), "rb") as stream:
+                require((stream.getnchannels(), stream.getsampwidth(), stream.getframerate()) == (1, 2, 16000)
+                        and stream.readframes(stream.getnframes()) == pcm, "saved WAV differs from speech stream")
+    require(all(report.get(k) == v for k, v in recomputed.items()), "saved TTS report differs from capture grading")
+    return report
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description="Independent trusted-local speech.tts.execution.v1 suite")
+    sub = parser.add_subparsers(dest="command", required=True)
+    sub.add_parser("describe")
+    freeze = sub.add_parser("freeze")
+    for arg in ("repository", "source-commit", "source-pr", "cases-json", "baseline", "candidate", "output"):
+        freeze.add_argument("--" + arg, required=True)
+    freeze.add_argument("--repetitions", type=int, default=1)
+    launch = sub.add_parser("run")
+    for arg in ("plan", "expected-plan-sha256", "output"):
+        launch.add_argument("--" + arg, required=True)
+    launch.add_argument("--allow-provider-calls", action="store_true")
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "describe":
+            result = describe_tts_suite()
+        elif args.command == "freeze":
+            cases = parse(Path(args.cases_json).read_bytes())
+            result = freeze_tts_plan(args.repository, source_commit=args.source_commit, source_pr=args.source_pr,
+                cases=cases, cohort_identity={"kind": "owner-supplied-cases", "sha256": sha(encode(cases))},
+                baseline=args.baseline, candidate=args.candidate, repetitions=args.repetitions, output_dir=args.output)
+        else:
+            result = run_tts_plan(args.plan, expected_plan_sha256=args.expected_plan_sha256,
+                                  output_dir=args.output, allow_provider_calls=args.allow_provider_calls)
+    except (SpeechContractError, ValueError, OSError, KeyError, TypeError, subprocess.SubprocessError):
+        parser.exit(2, "TTS operation failed; check frozen identities, limits and launch authorization\n")
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

sphynx/sql/001_sync_v1.sql

@@ -0,0 +1,30 @@
+-- Sphynx-owned projection schema. Provision {database} and grant the sync
+-- principal INSERT/SELECT on only these tables before invoking sync().
+-- No Litmus database, tables, buckets, or credentials are used.
+CREATE TABLE IF NOT EXISTS {database}.sphynx_facts_v1
+(
+    projection_id String,
+    row_id String,
+    row_hash String,
+    fact_type LowCardinality(String),
+    run_id String,
+    case_id String,
+    capture_id String,
+    evaluation_id String,
+    metric_id String,
+    capability_id String,
+    status LowCardinality(String),
+    numeric_value Nullable(Float64),
+    payload_json String
+)
+ENGINE = MergeTree
+ORDER BY (projection_id, row_id);
+
+CREATE TABLE IF NOT EXISTS {database}.sphynx_projection_commits_v1
+(
+    projection_id String,
+    commit_hash String,
+    payload_json String
+)
+ENGINE = MergeTree
+ORDER BY projection_id;