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

sphynx/hosted/registry.py

@@ -0,0 +1,97 @@
+"""Operator-owned repository authorization; never supplied by a candidate PR."""
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .contracts import HostedError, fields, stable_id
+
+REGISTRY_SCHEMA = "sphynx.hosted.registry.v1"
+SUITE_ID = "rag.rerank.v1"
+BASELINE_ID = "supplied-score:v1"
+PUBLIC_SUITE_ID = "rag.rerank.public.v1"
+REGISTERED_MAIN_BASELINE_ID = "registered-main-reflex-lexical:v1"
+_REPOSITORY = re.compile(r"^[A-Za-z0-9][A-Za-z0-9-]*/[A-Za-z0-9][A-Za-z0-9_.-]*$")
+
+
+def repository_name(value: object) -> str:
+    if not isinstance(value, str) or not _REPOSITORY.fullmatch(value):
+        raise HostedError("invalid_repository", "repository must be an owner/name pair")
+    return value
+
+
+@dataclass(frozen=True)
+class RepositoryRegistration:
+    repository_id: int
+    full_name: str
+    team_id: str
+    allowed_suites: tuple[str, ...]
+    allowed_baselines: tuple[str, ...]
+
+    def __post_init__(self):
+        if type(self.repository_id) is not int or self.repository_id <= 0:
+            raise HostedError("invalid_registry", "repository_id must be a positive GitHub repository ID")
+        repository_name(self.full_name)
+        stable_id(self.team_id, "team_id")
+        for values, supported in ((self.allowed_suites, {SUITE_ID, PUBLIC_SUITE_ID}),
+                                  (self.allowed_baselines, {BASELINE_ID, REGISTERED_MAIN_BASELINE_ID})):
+            if (not isinstance(values, tuple) or not values or
+                    any(type(value) is not str or value not in supported for value in values)
+                    or len(set(values)) != len(values)):
+                raise HostedError("invalid_registry", "suite and baseline grants must name explicit admitted IDs without duplicates")
+
+
+@dataclass(frozen=True)
+class HostedRegistry:
+    repositories: tuple[RepositoryRegistration, ...]
+
+    def __post_init__(self):
+        if not isinstance(self.repositories, tuple) or not self.repositories:
+            raise HostedError("invalid_registry", "at least one explicit repository registration is required")
+        if any(not isinstance(repo, RepositoryRegistration) for repo in self.repositories):
+            raise HostedError("invalid_registry", "invalid repository registration")
+        ids = [repo.repository_id for repo in self.repositories]
+        names = [repo.full_name.casefold() for repo in self.repositories]
+        if len(set(ids)) != len(ids) or len(set(names)) != len(names):
+            raise HostedError("invalid_registry", "repository IDs and names must be unique")
+
+    def authorize(self, team_id: str, full_name: str, suite: str, baseline: str,
+                  *, repository_id: int | None = None) -> RepositoryRegistration:
+        # Give one generic denial for unauthorized teams, repositories, and data.
+        match = next((repo for repo in self.repositories
+                      if repo.full_name.casefold() == full_name.casefold() and repo.team_id == team_id), None)
+        if match is None or suite not in match.allowed_suites or baseline not in match.allowed_baselines:
+            raise HostedError("submission_not_authorized", "team, repository, suite, or baseline is not registered")
+        if repository_id is not None and match.repository_id != repository_id:
+            raise HostedError("repository_identity_mismatch", "GitHub repository ID differs from its registration")
+        return match
+
+
+def load_registry(path: str | Path) -> HostedRegistry:
+    try:
+        payload = Path(path).read_bytes()
+        if len(payload) > 262_144:
+            raise ValueError("size")
+        def unique(pairs):
+            result = {}
+            for key, value in pairs:
+                if key in result:
+                    raise ValueError("duplicate")
+                result[key] = value
+            return result
+        raw = json.loads(payload, object_pairs_hook=unique)
+    except (OSError, ValueError, RecursionError):
+        raise HostedError("invalid_registry", "registry must be bounded JSON without duplicate fields") from None
+    fields(raw, {"schema_version", "repositories"}, "registry")
+    if raw["schema_version"] != REGISTRY_SCHEMA or not isinstance(raw["repositories"], list):
+        raise HostedError("invalid_registry", "unsupported registry schema")
+    registrations = []
+    for item in raw["repositories"]:
+        item = fields(item, {"repository_id", "full_name", "team_id", "allowed_suites", "allowed_baselines"}, "repository")
+        if not isinstance(item["allowed_suites"], list) or not isinstance(item["allowed_baselines"], list):
+            raise HostedError("invalid_registry", "suite and baseline permissions must be arrays")
+        registrations.append(RepositoryRegistration(item["repository_id"], item["full_name"], item["team_id"],
+                                                     tuple(item["allowed_suites"]), tuple(item["allowed_baselines"])))
+    return HostedRegistry(tuple(registrations))

sphynx/hosted/revisions.py

@@ -0,0 +1,126 @@
+"""Immutable source revision checks shared by PR and registered-main resolution.
+
+Resolving a baseline source is deliberately separate from admitting a runnable
+baseline. It does not fetch models, archive source, register an execution adapter,
+or enable main-branch model execution in the current synthetic pilot.
+"""
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Mapping, Protocol
+
+from .contracts import HostedError
+from .registry import RepositoryRegistration
+
+_COMMIT_SHA = re.compile(r"[0-9a-fA-F]{40}", re.ASCII)
+
+
+def require_commit_sha(value: object, *, field: str = "commit_sha") -> str:
+    """Accept a complete Git SHA-1 object identity; never accept a moving ref."""
+    if not isinstance(value, str) or _COMMIT_SHA.fullmatch(value) is None:
+        raise HostedError("invalid_commit_sha", f"{field} must be a complete 40-character hexadecimal commit SHA")
+    return value.lower()
+
+
+def enforce_expected_sha(actual_sha: object, expected_sha: object | None, *,
+                         field: str = "expected_head_sha",
+                         mismatch_code: str = "expected_head_mismatch") -> str:
+    """Actual identity is mandatory; a caller's matching constraint is optional."""
+    actual = require_commit_sha(actual_sha, field="resolved_commit_sha")
+    if expected_sha is not None and require_commit_sha(expected_sha, field=field) != actual:
+        raise HostedError(mismatch_code,
+                          f"resolved revision differs from {field}; confirm the intended revision and submit a new experiment")
+    return actual
+
+
+class RegisteredMainReader(Protocol):
+    def verify_repository_scope(self, full_name: str) -> Mapping[str, Any]: ...
+    def get_json(self, path: str) -> Mapping[str, Any]: ...
+
+
+@dataclass(frozen=True)
+class ResolvedMainRevision:
+    """A source-only record; a future baseline manifest must also bind artifacts."""
+    repository: str
+    repository_id: int
+    team_id: str
+    head_sha: str
+    tree_sha: str
+    resolved_at_utc: str
+    expected_sha: str | None = None
+
+    def __post_init__(self):
+        if type(self.repository_id) is not int or self.repository_id <= 0:
+            raise HostedError("invalid_github_identity", "resolved repository ID is invalid")
+        # Use the same checks for restored records as for new resolutions.
+        from .registry import repository_name
+        repository_name(self.repository)
+        if not isinstance(self.team_id, str) or not self.team_id:
+            raise HostedError("invalid_recorded_head", "resolved team identity is missing")
+        object.__setattr__(self, "head_sha", enforce_expected_sha(
+            self.head_sha, self.expected_sha, field="baseline_expected_sha",
+            mismatch_code="expected_baseline_mismatch"))
+        object.__setattr__(self, "tree_sha", require_commit_sha(self.tree_sha, field="tree_sha"))
+        if self.expected_sha is not None:
+            object.__setattr__(self, "expected_sha", require_commit_sha(self.expected_sha, field="baseline_expected_sha"))
+        try:
+            stamp = datetime.fromisoformat(self.resolved_at_utc.replace("Z", "+00:00"))
+            if stamp.utcoffset() is None:
+                raise ValueError("timezone")
+        except (AttributeError, TypeError, ValueError):
+            raise HostedError("invalid_recorded_head", "resolved timestamp must include a timezone") from None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema_version": "sphynx.registered-main-revision.v1",
+                "repository": self.repository, "repository_id": self.repository_id,
+                "team_id": self.team_id, "ref": "refs/heads/main",
+                "head_sha": self.head_sha, "tree_sha": self.tree_sha,
+                "resolved_at_utc": self.resolved_at_utc, "expected_sha": self.expected_sha,
+                "scope": "source_revision_only", "execution_enabled": False}
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> "ResolvedMainRevision":
+        fields = {"schema_version", "repository", "repository_id", "team_id", "ref",
+                  "head_sha", "tree_sha", "resolved_at_utc", "expected_sha", "scope", "execution_enabled"}
+        if (not isinstance(value, Mapping) or set(value) != fields or
+                value["schema_version"] != "sphynx.registered-main-revision.v1" or
+                value["ref"] != "refs/heads/main" or value["scope"] != "source_revision_only" or
+                value["execution_enabled"] is not False):
+            raise HostedError("invalid_recorded_head", "registered main revision has an unsupported shape")
+        return cls(**{key: value[key] for key in ("repository", "repository_id", "team_id", "head_sha",
+                                                  "tree_sha", "resolved_at_utc", "expected_sha")})
+
+
+def resolve_registered_main(reader: RegisteredMainReader, registration: RepositoryRegistration, *,
+                            team_id: str, expected_sha: object | None = None) -> ResolvedMainRevision:
+    """Resolve an operator-registered repository's main exactly once.
+
+    The caller must persist the returned record before archive/build/queue work.
+    Retries reuse that record instead of resolving main again. Baseline execution
+    additionally needs its own authorized definition, immutable model package,
+    and supported adapter; repository source permission alone grants none of them.
+    """
+    if not isinstance(registration, RepositoryRegistration) or registration.team_id != team_id:
+        raise HostedError("submission_not_authorized", "repository is not registered for this team")
+    expected = None if expected_sha is None else require_commit_sha(expected_sha, field="baseline_expected_sha")
+    scope = reader.verify_repository_scope(registration.full_name)
+    if (not isinstance(scope, Mapping) or type(scope.get("repository_id")) is not int or
+            scope["repository_id"] != registration.repository_id or
+            not isinstance(scope.get("full_name"), str) or
+            scope["full_name"].casefold() != registration.full_name.casefold() or
+            scope.get("scoped_repository_count") != 1):
+        raise HostedError("repository_identity_mismatch", "GitHub scope differs from its repository registration")
+    branch = reader.get_json(f"repos/{registration.full_name}/branches/main")
+    if not isinstance(branch, Mapping) or branch.get("name") != "main" or not isinstance(branch.get("commit"), Mapping):
+        raise HostedError("invalid_github_identity", "GitHub did not return the registered main branch")
+    head = enforce_expected_sha(branch["commit"].get("sha"), expected, field="baseline_expected_sha",
+                                mismatch_code="expected_baseline_mismatch")
+    commit = reader.get_json(f"repos/{registration.full_name}/git/commits/{head}")
+    if (not isinstance(commit, Mapping) or commit.get("sha") != head or
+            not isinstance(commit.get("tree"), Mapping)):
+        raise HostedError("invalid_github_identity", "GitHub commit differs from the frozen main revision")
+    tree = require_commit_sha(commit["tree"].get("sha"), field="tree_sha")
+    return ResolvedMainRevision(registration.full_name, registration.repository_id, team_id, head, tree,
+                                datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"), expected)

sphynx/hosted/sandbox.py

@@ -0,0 +1,105 @@
+"""Fail-closed Linux gVisor execution. No local/subprocess fallback for PR code.
+
+The trusted host stages declared files, invokes Docker with a verified runsc
+runtime, and captures bounded streams. The guest sees only source, two protocol
+helper modules, and one label-free request. No SDK fixture/grader or credentials.
+"""
+from __future__ import annotations
+import hashlib
+import json
+import os
+import re
+import subprocess
+import threading
+import time
+import uuid
+from pathlib import Path
+from .contracts import HostedError
+
+MAX_STREAM = 1_048_576
+POLICY = {'id': 'sphynx.gvisor.cpu.v1', 'cpus': 1, 'memory_bytes': 1_073_741_824,
+          'pids': 64, 'tmpfs_bytes': 67_108_864, 'case_timeout_seconds': 30,
+          'build_step_timeout_seconds': 30, 'network': 'none', 'user': '65532:65532',
+          'root_filesystem': 'read_only', 'fresh_process_per_case': True}
+
+class GVisorSandbox:
+    def __init__(self, image: str, *, runsc_path='/usr/local/bin/runsc', expected_runsc_sha256: str):
+        if os.name != 'posix': raise HostedError('sandbox_unavailable', 'hosted PR execution requires a Linux gVisor worker')
+        if not isinstance(image, str) or not re.fullmatch(r'[a-zA-Z0-9./:_-]+@sha256:[0-9a-f]{64}', image):
+            raise HostedError('invalid_runtime_identity', 'the candidate image must use an immutable digest')
+        if not re.fullmatch('[0-9a-f]{64}', expected_runsc_sha256):
+            raise HostedError('invalid_runtime_identity', 'a trusted runsc binary digest is required')
+        self.image, self.runsc_path, self.runsc_hash = image, Path(runsc_path), expected_runsc_sha256
+        self._verified = False
+    def verify(self):
+        if self._verified: return self.identity()
+        if hashlib.sha256(self.runsc_path.read_bytes()).hexdigest() != self.runsc_hash:
+            raise HostedError('sandbox_identity_mismatch', 'runsc binary differs from the approved runtime')
+        result = subprocess.run(['docker', 'info', '--format', '{{json .Runtimes}}'], capture_output=True, timeout=20, check=True)
+        runtimes = json.loads(result.stdout)
+        configured = runtimes.get('runsc', {}).get('path')
+        if not isinstance(configured, str) or Path(configured).resolve() != self.runsc_path.resolve():
+            raise HostedError('sandbox_unavailable', 'Docker is not configured with the approved runsc runtime')
+        subprocess.run(['docker', 'image', 'inspect', self.image], capture_output=True, timeout=20, check=True)
+        self._verified = True
+        return self.identity()
+    def identity(self):
+        return {'image_digest': self.image, 'runsc_sha256': self.runsc_hash, 'resource_policy': dict(POLICY)}
+    def command(self, argv, source: Path, helper: Path, name: str):
+        return ['docker', 'run', '--rm', '--name', name, '--runtime=runsc', '--network=none',
+            '--read-only', '--cap-drop=ALL', '--security-opt=no-new-privileges:true',
+            '--cpus=1', '--memory=1g', '--memory-swap=1g', '--pids-limit=64', '--ulimit=nofile=128:128',
+            '--user=65532:65532', '--log-driver=none',
+            '--tmpfs=/tmp:rw,noexec,nosuid,nodev,size=64m,uid=65532,gid=65532,mode=700',
+            '--mount', 'type=bind,source=' + str(source.resolve()) + ',target=/candidate,readonly',
+            '--mount', 'type=bind,source=' + str(helper.resolve()) + ',target=/helper,readonly',
+            '--workdir=/candidate', '--env=PYTHONPATH=/helper:/candidate', '--env=PYTHONPYCACHEPREFIX=/tmp/cache',
+            '--env=HOME=/tmp', '--env=PYTHONUTF8=1', '--env=PYTHONDONTWRITEBYTECODE=1',
+            '-i', self.image, *argv]
+    def execute(self, argv, source, helper, payload: bytes, *, timeout: float = 30):
+        self.verify()
+        name = 'sphynx-' + uuid.uuid4().hex
+        command = self.command(argv, source, helper, name)
+        start = time.monotonic()
+        process = subprocess.Popen(command, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+            env={key: value for key, value in os.environ.items() if key in ('PATH', 'LANG')})
+        streams = {'stdout': bytearray(), 'stderr': bytearray()}
+        exceeded = threading.Event()
+        def read(stream, label):
+            try:
+                while block := stream.read(8192):
+                    remaining = MAX_STREAM - len(streams[label])
+                    streams[label].extend(block[:remaining])
+                    if len(block) > remaining: exceeded.set(); process.kill(); break
+            finally: stream.close()
+        threads = [threading.Thread(target=read, args=(process.stdout, 'stdout'), daemon=True),
+                   threading.Thread(target=read, args=(process.stderr, 'stderr'), daemon=True)]
+        for thread in threads: thread.start()
+        def write_input():
+            try:
+                process.stdin.write(payload)
+            except (BrokenPipeError, OSError):
+                pass
+            finally:
+                try: process.stdin.close()
+                except OSError: pass
+        writer = threading.Thread(target=write_input, daemon=True)
+        writer.start()
+        status = 'ok'
+        try:
+            process.wait(timeout=timeout)
+        except subprocess.TimeoutExpired:
+            status = 'timeout'; process.kill(); process.wait(timeout=5)
+        finally:
+            ended = time.monotonic()
+            # CLI termination alone would leave the guest running. Remove it on the host.
+            subprocess.run(['docker', 'rm', '-f', name], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=20)
+            writer.join(5)
+            for thread in threads: thread.join(5)
+        if exceeded.is_set(): status = 'output_limit_exceeded'
+        elif status == 'ok' and process.returncode != 0:
+            if process.returncode == 125: raise HostedError('sandbox_launch_failed', 'the trusted sandbox could not start')
+            status = 'process_failed'
+        return {'status': status, 'stdout_base64': __import__('base64').b64encode(streams['stdout']).decode(),
+                'stderr_base64': __import__('base64').b64encode(streams['stderr']).decode(),
+                'exit_code': process.returncode, 'runner_latency_ms': (ended - start) * 1000}

sphynx/hosted/submission.py

@@ -0,0 +1,287 @@
+"""Resolve one registered PR and freeze declared source files at its head SHA.
+
+This is trusted submission preparation, not a build service or evaluation runner.
+It never checks out a branch, follows a PR merge ref, or executes repository code.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import re
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any, Callable, Mapping, Protocol
+from urllib.parse import urlsplit
+
+from ..contracts import INTERFACE_VERSION, canonical_json
+from ..metrics import GRADER_RELEASE, METRIC_RELEASE
+from ..rag import FIXTURE_SHA256
+from .contracts import (CandidateConfig, HostedError, MAX_CONFIG_BYTES, MAX_FILE_BYTES,
+                        MAX_SOURCE_BYTES, FAMILY_SUBMISSION_SCHEMA, SelectedCandidateRepository,
+                        candidate_method_id, parse_candidate_repository)
+from .registry import BASELINE_ID, SUITE_ID, HostedRegistry, repository_name
+from .revisions import enforce_expected_sha, require_commit_sha
+
+SUBMISSION_SCHEMA = "sphynx.hosted.prepared-submission.v1"
+_SHA = re.compile(r"^[0-9a-f]{40}$")
+_PR = re.compile(r"^/([A-Za-z0-9][A-Za-z0-9-]*)/([A-Za-z0-9][A-Za-z0-9_.-]*)/pull/([1-9][0-9]*)/?$")
+
+
+class GitHubReader(Protocol):
+    """Implemented by a trusted GitHub App transport in the hosted API later."""
+    def get_json(self, path: str) -> Mapping[str, Any]: ...
+
+
+def pr_identity(url: object) -> tuple[str, str, int]:
+    if not isinstance(url, str) or len(url) > 512:
+        raise HostedError("invalid_pr_url", "use an HTTPS github.com repository/pull/number URL")
+    if any(character.isspace() or ord(character) < 32 for character in url):
+        raise HostedError("invalid_pr_url", "PR URL cannot contain whitespace or control characters")
+    try:
+        parsed = urlsplit(url)
+    except ValueError:
+        raise HostedError("invalid_pr_url", "use an HTTPS github.com repository/pull/number URL") from None
+    match = _PR.fullmatch(parsed.path)
+    if parsed.scheme != "https" or parsed.netloc != "github.com" or parsed.query or parsed.fragment or match is None:
+        raise HostedError("invalid_pr_url", "use an HTTPS github.com repository/pull/number URL")
+    full_name = repository_name(match.group(1) + "/" + match.group(2))
+    number = int(match.group(3))
+    return f"https://github.com/{full_name}/pull/{number}", full_name, number
+
+
+def _sha(value: object) -> str:
+    if not isinstance(value, str) or not _SHA.fullmatch(value):
+        raise HostedError("invalid_github_identity", "GitHub must return a complete commit or object SHA")
+    return value
+
+
+def _mapping(value: object) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping):
+        raise HostedError("invalid_github_response", "GitHub returned an unexpected object")
+    return value
+
+
+def _repo(value: object) -> tuple[str, int]:
+    value = _mapping(value)
+    name = repository_name(value.get("full_name"))
+    repo_id = value.get("id")
+    if type(repo_id) is not int or repo_id <= 0:
+        raise HostedError("invalid_github_identity", "GitHub repository ID is missing")
+    return name, repo_id
+
+
+@dataclass(frozen=True)
+class ResolvedPR:
+    pr_url: str
+    pr_number: int
+    base_repository: str
+    base_repository_id: int
+    head_repository: str
+    head_repository_id: int
+    head_sha: str
+    team_id: str
+    resolved_at_utc: str
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(vars(self))
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> "ResolvedPR":
+        expected = {"pr_url", "pr_number", "base_repository", "base_repository_id",
+                    "head_repository", "head_repository_id", "head_sha", "team_id", "resolved_at_utc"}
+        if not isinstance(value, Mapping) or set(value) != expected:
+            raise HostedError("invalid_recorded_head", "recorded PR head has an unsupported shape")
+        return cls(**value)
+
+
+def resolve_pull_request(reader: GitHubReader, registry: HostedRegistry, *, team_id: str,
+                         candidate_pr: str, suite: str = SUITE_ID, baseline: str = BASELINE_ID,
+                         expected_head_sha: str | None = None) -> ResolvedPR:
+    if expected_head_sha is not None:
+        expected_head_sha = require_commit_sha(expected_head_sha, field='expected_head_sha')
+    pr_url, requested_repo, number = pr_identity(candidate_pr)
+    registry.authorize(team_id, requested_repo, suite, baseline)
+    pr = _mapping(reader.get_json(f"repos/{requested_repo}/pulls/{number}"))
+    if type(pr.get("number")) is not int or pr["number"] != number:
+        raise HostedError("invalid_github_identity", "GitHub PR number does not match the submission")
+    base_name, base_id = _repo(_mapping(pr.get("base")).get("repo"))
+    if base_name.casefold() != requested_repo.casefold():
+        raise HostedError("repository_identity_mismatch", "GitHub PR base differs from the requested repository")
+    registry.authorize(team_id, base_name, suite, baseline, repository_id=base_id)
+    head = _mapping(pr.get("head"))
+    if head.get("repo") is None:
+        raise HostedError("head_repository_unavailable", "PR head repository has been deleted or is inaccessible")
+    head_name, head_id = _repo(head["repo"])
+    registry.authorize(team_id, head_name, suite, baseline, repository_id=head_id)
+    head_sha = _sha(head.get("sha"))
+    enforce_expected_sha(head_sha, expected_head_sha)
+    return ResolvedPR(pr_url, number, base_name, base_id, head_name, head_id, head_sha,
+                      team_id, datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"))
+
+
+@dataclass(frozen=True)
+class SourceFile:
+    path: str
+    content: bytes
+    git_blob_sha: str
+
+    @property
+    def digest(self) -> str:
+        return "sha256:" + hashlib.sha256(self.content).hexdigest()
+
+
+@dataclass(frozen=True)
+class FrozenSubmission:
+    pr_url: str
+    pr_number: int
+    base_repository: str
+    base_repository_id: int
+    head_repository: str
+    head_repository_id: int
+    head_sha: str
+    tree_sha: str
+    team_id: str
+    config: CandidateConfig
+    files: tuple[SourceFile, ...]
+    resolved_at_utc: str
+    repository_selection: SelectedCandidateRepository | None = None
+    model_runtime_json: str | None = None
+
+    @property
+    def source_bundle_digest(self) -> str:
+        identity = {
+            "head_repository_id": self.head_repository_id, "head_sha": self.head_sha,
+            "files": [{"path": source.path, "sha256": source.digest} for source in self.files],
+        }
+        return "sha256:" + hashlib.sha256(canonical_json(identity).encode("utf-8")).hexdigest()
+
+    def to_manifest(self) -> dict[str, Any]:
+        manifest = {
+            "schema_version": SUBMISSION_SCHEMA, "status": "prepared",
+            "hosted_execution_verified": False, "team_id": self.team_id,
+            "candidate_pr": self.pr_url, "pr_number": self.pr_number,
+            "base_repository": {"id": self.base_repository_id, "full_name": self.base_repository},
+            "head_repository": {"id": self.head_repository_id, "full_name": self.head_repository},
+            "head_sha": self.head_sha, "tree_sha": self.tree_sha,
+            "resolved_at_utc": self.resolved_at_utc,
+            "candidate_configuration": self.config.to_dict(),
+            "configuration_digest": self.config.digest,
+            "source_bundle_digest": self.source_bundle_digest,
+            "files": [{"path": source.path, "size_bytes": len(source.content),
+                       "git_blob_sha": source.git_blob_sha, "sha256": source.digest} for source in self.files],
+            "suite": {"id": SUITE_ID, "dataset_digest": "sha256:" + FIXTURE_SHA256,
+                      "case_count": 6, "interface_version": INTERFACE_VERSION,
+                      "grader_release": GRADER_RELEASE, "metric_release": METRIC_RELEASE},
+            "baseline": {"id": BASELINE_ID, "score_source": "supplied_dense_scores",
+                         "fresh_model_inference": False},
+            "requested_runtime_profile": self.config.runtime_profile,
+            "runtime_identity": None, "metrics": None, "report_location": None,
+        }
+        if self.repository_selection is not None and self.repository_selection.family is not None:
+            manifest.update(schema_version=FAMILY_SUBMISSION_SCHEMA,
+                candidate_method=self.repository_selection.candidate_method,
+                candidate_family=self.repository_selection.family_selection())
+        if self.model_runtime_json is not None:
+            from .model_contracts import MODEL_SUBMISSION_SCHEMA
+            import json
+            manifest.update(schema_version=MODEL_SUBMISSION_SCHEMA,
+                            model_runtime=json.loads(self.model_runtime_json))
+        return manifest
+
+
+def prepare_submission(reader: GitHubReader, registry: HostedRegistry, *, team_id: str,
+                       candidate_pr: str, suite: str = SUITE_ID, baseline: str = BASELINE_ID,
+                       pinned: ResolvedPR | None = None,
+                       on_resolved: Callable[[ResolvedPR], None] | None = None,
+                       expected_head_sha: str | None = None,
+                       candidate_method: str | None = None,
+                       model_runtime=None) -> FrozenSubmission:
+    if candidate_method is not None:
+        candidate_method = candidate_method_id(candidate_method)
+    if expected_head_sha is not None:
+        expected_head_sha = require_commit_sha(expected_head_sha, field='expected_head_sha')
+    pr_url, requested_repo, number = pr_identity(candidate_pr)
+    registry.authorize(team_id, requested_repo, suite, baseline)
+    resolved = pinned or resolve_pull_request(reader, registry, team_id=team_id,
+                                              candidate_pr=candidate_pr, suite=suite, baseline=baseline,
+                                              expected_head_sha=expected_head_sha)
+    if (resolved.pr_url != pr_url or type(resolved.pr_number) is not int or resolved.pr_number != number
+            or resolved.base_repository.casefold() != requested_repo.casefold() or resolved.team_id != team_id):
+        raise HostedError("recorded_head_mismatch", "recorded head belongs to another submission")
+    for name, repo_id in ((resolved.base_repository, resolved.base_repository_id),
+                         (resolved.head_repository, resolved.head_repository_id)):
+        if type(repo_id) is not int or repo_id <= 0:
+            raise HostedError("invalid_recorded_head", "recorded repository ID is invalid")
+        registry.authorize(team_id, repository_name(name), suite, baseline, repository_id=repo_id)
+    commit_sha = _sha(resolved.head_sha)
+    enforce_expected_sha(commit_sha, expected_head_sha)
+    if on_resolved is not None:
+        on_resolved(resolved)  # Persist before source fetch; retries resume this exact head.
+    base_name, base_id = resolved.base_repository, resolved.base_repository_id
+    head_name, head_id = resolved.head_repository, resolved.head_repository_id
+    prefix = f"repos/{head_name}/git"
+    commit = _mapping(reader.get_json(f"{prefix}/commits/{commit_sha}"))
+    if commit.get("sha") != commit_sha:
+        raise HostedError("commit_identity_mismatch", "GitHub returned a different commit")
+    tree_sha = _sha(_mapping(commit.get("tree")).get("sha"))
+    trees: dict[str, Mapping[str, Any]] = {}
+
+    def read_file(path: str, maximum: int) -> SourceFile:
+        current_sha = tree_sha
+        components = path.split("/")
+        for index, component in enumerate(components):
+            if current_sha not in trees:
+                tree = _mapping(reader.get_json(f"{prefix}/trees/{current_sha}"))
+                entries = tree.get("tree")
+                if tree.get("sha") != current_sha or tree.get("truncated") or not isinstance(entries, list) or len(entries) > 10_000:
+                    raise HostedError("invalid_source_tree", "source tree is truncated, oversized, or has a different identity")
+                trees[current_sha] = tree
+            matches = [item for item in trees[current_sha]["tree"]
+                       if isinstance(item, Mapping) and item.get("path") == component]
+            if len(matches) != 1:
+                code = "candidate_config_missing" if path == "sphynx.toml" else "source_file_missing"
+                raise HostedError(code, "the pinned commit does not contain a declared regular file")
+            entry = matches[0]
+            current_sha = _sha(entry.get("sha"))
+            final = index == len(components) - 1
+            if not final:
+                if entry.get("type") != "tree" or entry.get("mode") != "040000":
+                    raise HostedError("unsafe_source_entry", "source directory cannot be a symlink or submodule")
+            elif entry.get("type") != "blob" or entry.get("mode") not in ("100644", "100755"):
+                raise HostedError("unsafe_source_entry", "source files cannot be symlinks or submodules")
+        blob = _mapping(reader.get_json(f"{prefix}/blobs/{current_sha}"))
+        content, size = blob.get("content"), blob.get("size")
+        if blob.get("sha") != current_sha or blob.get("encoding") != "base64" or not isinstance(content, str):
+            raise HostedError("invalid_source_blob", "GitHub did not return the requested encoded blob")
+        if type(size) is not int or size < 0 or size > maximum or len(content) > maximum * 2 + 1024:
+            raise HostedError("source_size_limit", "source file exceeds the pilot size limit")
+        try:
+            data = base64.b64decode("".join(content.splitlines()), validate=True)
+        except (ValueError, UnicodeEncodeError):
+            raise HostedError("invalid_source_blob", "source blob is not valid base64") from None
+        actual_sha = hashlib.sha1(b"blob " + str(len(data)).encode("ascii") + b"\0" + data).hexdigest()
+        if len(data) != size or actual_sha != current_sha:
+            raise HostedError("source_digest_mismatch", "source bytes do not match the pinned Git object")
+        return SourceFile(path, data, current_sha)
+
+    configuration_file = read_file("sphynx.toml", MAX_CONFIG_BYTES)
+    selection = parse_candidate_repository(configuration_file.content, candidate_method=candidate_method)
+    config = selection.config
+    model_runtime_json = None
+    if config.model_kind == "registered":
+        from .model_admission import ModelRuntimeAdmission, require_model_authorization
+        if model_runtime is None:
+            raise HostedError("models_not_admitted", "this candidate requires an operator-verified model runtime admission")
+        record = model_runtime.to_dict() if isinstance(model_runtime, ModelRuntimeAdmission) else model_runtime
+        admitted = require_model_authorization(record, team_id=team_id, base_repository_id=base_id,
+            head_repository_id=head_id, suite=suite, baseline=baseline)
+        model_runtime_json = canonical_json(admitted)
+    sources = [configuration_file]
+    for path in sorted(config.source_files):
+        sources.append(read_file(path, MAX_FILE_BYTES))
+        if sum(len(source.content) for source in sources) > MAX_SOURCE_BYTES:
+            raise HostedError("source_size_limit", "candidate bundle exceeds the pilot size limit")
+    return FrozenSubmission(pr_url, number, base_name, base_id, head_name, head_id, commit_sha,
+                            tree_sha, team_id, config, tuple(sources),
+                            resolved.resolved_at_utc, selection if selection.family is not None else None,
+                            model_runtime_json)