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

sphynx/evidence.py

@@ -0,0 +1,352 @@
+"""Versioned, content-addressed local run bundles.
+
+Only label-free case inputs and candidate process observations belong here.
+References and grading results live outside captures. Files are written once
+under a new run ID; readers never repair or rewrite historical evidence.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+from .contracts import canonical_json
+from .records import EVIDENCE_SCHEMA_VERSION, EvidenceCapability
+
+RUN_SCHEMA_VERSION = "sphynx.run.v1"
+ARTIFACT_SCHEMA_VERSION = "sphynx.artifact.v1"
+EVENT_SCHEMA_VERSION = "sphynx.event.v1"
+COVERAGE_SCHEMA_VERSION = "sphynx.coverage.v1"
+RUNNER_CLOCK_DOMAIN = "python.monotonic_ns.process_local"
+RUN_ID_PATTERN = re.compile(r"run-[0-9a-f]{32}\Z")
+CAPTURE_ID_PATTERN = re.compile(r"cap-[0-9a-f]{32}\Z")
+_CAPABILITIES = frozenset({
+    "candidate_input", "case_snapshot", "candidate_stdout_raw",
+    "candidate_stderr_raw", "candidate_response_validated", "runner_timing",
+})
+
+
+class EvidenceError(ValueError):
+    """A saved run is missing, altered, or uses an unsupported schema."""
+
+
+@dataclass(frozen=True)
+class RunRef:
+    """Durable, absolute reference to one completed local run bundle."""
+
+    run_id: str
+    path: Path
+    pack_id: str
+
+
+def sha256_bytes(data: bytes) -> str:
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def _new_bytes(path: Path, data: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("xb") as stream:
+        stream.write(data)
+
+
+def write_json(path: Path, value: Any) -> str:
+    """Write canonical JSON once and return its exact byte digest."""
+
+    data = (canonical_json(value) + "\n").encode("utf-8")
+    _new_bytes(path, data)
+    return sha256_bytes(data)
+
+
+def write_jsonl(path: Path, rows: list[Mapping[str, Any]]) -> str:
+    data = "".join(canonical_json(row) + "\n" for row in rows).encode("utf-8")
+    _new_bytes(path, data)
+    return sha256_bytes(data)
+
+
+def write_blob(
+    capture_dir: Path,
+    *,
+    role: str,
+    data: bytes,
+    media_type: str,
+    observed_bytes: int,
+    complete: bool,
+    observed: bool = True,
+) -> dict[str, Any]:
+    """Save retained bytes and describe whether they are the complete original.
+
+    Identical blobs may share a content address within one capture. A truncated
+    stream's digest authenticates its retained prefix, never the unseen suffix.
+    """
+
+    digest = sha256_bytes(data)
+    relative_path = "blobs/" + digest.removeprefix("sha256:")
+    path = capture_dir / relative_path
+    if path.exists():
+        if path.read_bytes() != data:
+            raise EvidenceError(f"content-address collision at {path}")
+    else:
+        _new_bytes(path, data)
+    return {
+        "schema_version": ARTIFACT_SCHEMA_VERSION,
+        "role": role,
+        "path": relative_path,
+        "sha256": digest,
+        "retained_bytes": len(data),
+        "observed_bytes": observed_bytes,
+        "complete": complete,
+        "observed": observed,
+        "media_type": media_type,
+        "source": "runner_observed",
+    }
+
+
+def _read_json(path: Path) -> dict[str, Any]:
+    try:
+        value = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise EvidenceError(f"cannot read JSON evidence {path}: {exc}") from exc
+    if not isinstance(value, dict):
+        raise EvidenceError(f"evidence {path} must be a JSON object")
+    return value
+
+
+def _safe_capture_dir(run_path: Path, capture_id: str) -> Path:
+    if not isinstance(capture_id, str) or not CAPTURE_ID_PATTERN.fullmatch(capture_id):
+        raise EvidenceError(f"invalid capture ID {capture_id!r}")
+    return run_path / "captures" / capture_id
+
+
+def open_run(path: str | Path | RunRef) -> RunRef:
+    """Reopen a completed run by absolute or caller-relative bundle path.
+
+    Integrity checking is separate in :func:`verify_run`. Readers can inspect
+    the manifest even when a particular capture has become corrupt.
+    """
+
+    run_path = path.path if isinstance(path, RunRef) else Path(path)
+    run_path = run_path.expanduser().resolve()
+    manifest = _read_json(run_path / "manifest.json")
+    if manifest.get("schema_version") != RUN_SCHEMA_VERSION:
+        raise EvidenceError("unsupported run schema_version")
+    run_id = manifest.get("run_id")
+    if not isinstance(run_id, str) or not RUN_ID_PATTERN.fullmatch(run_id) or run_path.name != run_id:
+        raise EvidenceError("run ID does not match bundle directory")
+    pack_id = manifest.get("pack_id")
+    if not isinstance(pack_id, str) or not pack_id:
+        raise EvidenceError("run pack_id is missing")
+    if manifest.get("status") not in ("completed", "completed_with_failures"):
+        raise EvidenceError("run is not terminal")
+    return RunRef(run_id, run_path, pack_id)
+
+
+def read_run_manifest(run_ref: RunRef | str | Path) -> dict[str, Any]:
+    ref = open_run(run_ref)
+    return _read_json(ref.path / "manifest.json")
+
+
+def read_capture_manifest(run_ref: RunRef | str | Path, capture_id: str) -> dict[str, Any]:
+    ref = open_run(run_ref)
+    return _checked_capture_manifest(ref, capture_id)
+
+
+def _checked_capture_manifest(ref: RunRef, capture_id: str) -> dict[str, Any]:
+    root = _read_json(ref.path / "manifest.json")
+    expected = root.get("capture_manifest_hashes")
+    if not isinstance(expected, dict) or capture_id not in expected:
+        raise EvidenceError(f"capture {capture_id} is not indexed by the run")
+    path = _safe_capture_dir(ref.path, capture_id) / "manifest.json"
+    try:
+        raw = path.read_bytes()
+    except OSError as exc:
+        raise EvidenceError(f"cannot read capture manifest {capture_id}: {exc}") from exc
+    if sha256_bytes(raw) != expected[capture_id]:
+        raise EvidenceError(f"capture manifest hash mismatch: {capture_id}")
+    return _read_json(path)
+
+
+def read_capture_artifact(run_ref: RunRef | str | Path, capture_id: str, role: str) -> bytes:
+    """Return exact retained bytes only after checking its index and digest."""
+
+    ref = open_run(run_ref)
+    capture_dir = _safe_capture_dir(ref.path, capture_id)
+    capture = _checked_capture_manifest(ref, capture_id)
+    index_path = capture_dir / "artifacts.jsonl"
+    try:
+        index_bytes = index_path.read_bytes()
+    except OSError as exc:
+        raise EvidenceError(f"cannot read artifact index {capture_id}: {exc}") from exc
+    if sha256_bytes(index_bytes) != capture.get("artifacts_sha256"):
+        raise EvidenceError(f"artifact index hash mismatch: {capture_id}")
+    artifacts = _read_jsonl(index_path)
+    matches = [row for row in artifacts if row.get("role") == role]
+    if len(matches) != 1:
+        raise EvidenceError(f"expected one {role!r} artifact for {capture_id}")
+    return _verified_artifact_bytes(capture_dir, matches[0])
+
+
+def _read_jsonl(path: Path) -> list[dict[str, Any]]:
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+        rows = [json.loads(line) for line in lines]
+    except (OSError, UnicodeError, json.JSONDecodeError) as exc:
+        raise EvidenceError(f"cannot read JSONL evidence {path}: {exc}") from exc
+    if any(not isinstance(row, dict) for row in rows):
+        raise EvidenceError(f"evidence {path} must contain JSON objects")
+    return rows
+
+
+def _verified_artifact_bytes(capture_dir: Path, artifact: Mapping[str, Any]) -> bytes:
+    digest = artifact.get("sha256")
+    if not isinstance(digest, str) or not digest.startswith("sha256:") or len(digest) != 71:
+        raise EvidenceError("artifact has invalid SHA-256 digest")
+    expected_path = "blobs/" + digest.removeprefix("sha256:")
+    if artifact.get("path") != expected_path:
+        raise EvidenceError("artifact path is not its content address")
+    try:
+        data = (capture_dir / expected_path).read_bytes()
+    except OSError as exc:
+        raise EvidenceError(f"cannot read artifact {expected_path}: {exc}") from exc
+    if sha256_bytes(data) != digest or len(data) != artifact.get("retained_bytes"):
+        raise EvidenceError(f"artifact hash/size mismatch: {artifact.get('role')}")
+    return data
+
+
+def verify_run(run_ref: RunRef | str | Path) -> RunRef:
+    """Check manifests, all indexed artifacts, and all metadata file hashes."""
+
+    ref = open_run(run_ref)
+    manifest = _read_json(ref.path / "manifest.json")
+    if manifest.get("trust_tier") != "local_unverified" or manifest.get("provenance") != "runner_observed":
+        raise EvidenceError("unsupported run trust tier or provenance")
+    cases = manifest.get("cases")
+    if not isinstance(cases, list) or manifest.get("case_count") != len(cases):
+        raise EvidenceError("run case_count mismatch")
+    case_by_id: dict[str, dict[str, Any]] = {}
+    for item in cases:
+        if not isinstance(item, dict) or not isinstance(item.get("case_id"), str):
+            raise EvidenceError("run case identity is invalid")
+        if item["case_id"] in case_by_id:
+            raise EvidenceError("run has duplicate case IDs")
+        case_by_id[item["case_id"]] = item
+    policy = manifest.get("execution_policy")
+    if not isinstance(policy, dict) or type(policy.get("trials")) is not int or policy["trials"] < 1:
+        raise EvidenceError("run execution policy is invalid")
+    capture_ids = manifest.get("capture_ids")
+    if not isinstance(capture_ids, list) or any(not isinstance(value, str) for value in capture_ids) or len(set(capture_ids)) != len(capture_ids):
+        raise EvidenceError("run capture_ids are missing or duplicated")
+    if manifest.get("capture_count") != len(capture_ids):
+        raise EvidenceError("run capture_count mismatch")
+    if len(capture_ids) != len(cases) * policy["trials"]:
+        raise EvidenceError("run capture count does not match fixed case/trial workload")
+    hashes = manifest.get("capture_manifest_hashes")
+    if not isinstance(hashes, dict) or set(hashes) != set(capture_ids):
+        raise EvidenceError("run capture-manifest hashes do not match IDs")
+    statuses: list[str] = []
+    for capture_id in capture_ids:
+        capture_dir = _safe_capture_dir(ref.path, capture_id)
+        manifest_path = capture_dir / "manifest.json"
+        try:
+            manifest_bytes = manifest_path.read_bytes()
+        except OSError as exc:
+            raise EvidenceError(f"cannot read capture manifest {capture_id}: {exc}") from exc
+        if sha256_bytes(manifest_bytes) != hashes[capture_id]:
+            raise EvidenceError(f"capture manifest hash mismatch: {capture_id}")
+        capture = _read_json(manifest_path)
+        if capture.get("schema_version") != EVIDENCE_SCHEMA_VERSION:
+            raise EvidenceError(f"unsupported capture schema_version: {capture_id}")
+        identity = capture.get("identity")
+        if not isinstance(identity, dict) or identity.get("run_id") != ref.run_id or identity.get("capture_id") != capture_id:
+            raise EvidenceError(f"capture identity mismatch: {capture_id}")
+        if identity.get("schema_version") != EVIDENCE_SCHEMA_VERSION or identity.get("trust_tier") != "local_unverified":
+            raise EvidenceError(f"unsupported capture schema: {capture_id}")
+        case = case_by_id.get(identity.get("case_id"))
+        if case is None or identity.get("pool_digest") != case.get("pool_digest") or capture.get("query_id") != case.get("query_id"):
+            raise EvidenceError(f"capture does not match run case/pool: {capture_id}")
+        status = capture.get("status")
+        if status not in {"success", "timeout", "crash", "spawn_error", "process_error", "input_write_error", "output_truncated", "invalid_response"}:
+            raise EvidenceError(f"invalid terminal status: {capture_id}")
+        if (status == "success") != (capture.get("failure_code") is None):
+            raise EvidenceError(f"terminal failure code mismatch: {capture_id}")
+        statuses.append(status)
+        for filename, field in (
+            ("events.jsonl", "events_sha256"),
+            ("artifacts.jsonl", "artifacts_sha256"),
+            ("coverage.json", "coverage_sha256"),
+        ):
+            try:
+                data = (capture_dir / filename).read_bytes()
+            except OSError as exc:
+                raise EvidenceError(f"cannot read {filename} for {capture_id}: {exc}") from exc
+            if sha256_bytes(data) != capture.get(field):
+                raise EvidenceError(f"{filename} hash mismatch: {capture_id}")
+        artifacts = _read_jsonl(capture_dir / "artifacts.jsonl")
+        roles = [row.get("role") for row in artifacts]
+        if len(roles) != len(set(roles)):
+            raise EvidenceError(f"duplicate artifact role: {capture_id}")
+        if not {"candidate_request", "case_snapshot", "candidate_stdout", "candidate_stderr"}.issubset(roles):
+            raise EvidenceError(f"required artifacts missing: {capture_id}")
+        for artifact in artifacts:
+            if artifact.get("schema_version") != ARTIFACT_SCHEMA_VERSION:
+                raise EvidenceError(f"unsupported artifact schema: {capture_id}")
+            _verified_artifact_bytes(capture_dir, artifact)
+        events = _read_jsonl(capture_dir / "events.jsonl")
+        if any(row.get("schema_version") != EVENT_SCHEMA_VERSION
+               or row.get("clock_domain") != RUNNER_CLOCK_DOMAIN
+               or row.get("actor") != "runner"
+               or row.get("source") != "runner_observed" for row in events):
+            raise EvidenceError(f"unsupported event schema, clock, or provenance: {capture_id}")
+        if [row.get("sequence") for row in events] != list(range(1, len(events) + 1)):
+            raise EvidenceError(f"event order mismatch: {capture_id}")
+        event_ids = [row.get("event_id") for row in events]
+        if len(set(event_ids)) != len(event_ids):
+            raise EvidenceError(f"duplicate event ID: {capture_id}")
+        monotonic = [row.get("monotonic_ns") for row in events]
+        if any(type(value) is not int for value in monotonic) or monotonic != sorted(monotonic):
+            raise EvidenceError(f"non-monotonic event timeline: {capture_id}")
+        if not events or events[-1].get("event_type") != "case_terminal" or events[-1].get("status") != status:
+            raise EvidenceError(f"terminal event mismatch: {capture_id}")
+        if any(row.get("capture_id") != capture_id for row in events):
+            raise EvidenceError(f"event capture ID mismatch: {capture_id}")
+        timing = capture.get("timing")
+        if not isinstance(timing, dict) or type(timing.get("elapsed_ns")) is not int or timing["elapsed_ns"] < 0:
+            raise EvidenceError(f"invalid capture timing: {capture_id}")
+        if timing.get("clock_domain") != RUNNER_CLOCK_DOMAIN:
+            raise EvidenceError(f"unsupported capture timing clock: {capture_id}")
+        if type(timing.get("started_monotonic_ns")) is not int or type(timing.get("ended_monotonic_ns")) is not int:
+            raise EvidenceError(f"invalid capture timing endpoints: {capture_id}")
+        if timing.get("ended_monotonic_ns", 0) - timing.get("started_monotonic_ns", 0) != timing["elapsed_ns"]:
+            raise EvidenceError(f"capture timing span mismatch: {capture_id}")
+        latency_ns = timing.get("candidate_latency_ns")
+        if latency_ns is not None and (type(latency_ns) is not int or latency_ns < 0 or latency_ns > timing["elapsed_ns"]):
+            raise EvidenceError(f"invalid candidate latency: {capture_id}")
+        coverage = _read_json(capture_dir / "coverage.json")
+        if coverage.get("schema_version") != COVERAGE_SCHEMA_VERSION or coverage.get("capture_id") != capture_id:
+            raise EvidenceError(f"unsupported coverage schema: {capture_id}")
+        capabilities = coverage.get("capabilities")
+        if not isinstance(capabilities, list) or len(capabilities) != len(_CAPABILITIES):
+            raise EvidenceError(f"invalid coverage capability inventory: {capture_id}")
+        ids: set[str] = set()
+        for item in capabilities:
+            if not isinstance(item, dict) or set(item) != {"capability_id", "capability_schema_version", "state", "observed_count", "reason"}:
+                raise EvidenceError(f"invalid coverage capability record: {capture_id}")
+            if item.get("capability_schema_version") != "v1":
+                raise EvidenceError(f"unsupported capability schema_version: {capture_id}")
+            try:
+                capability = EvidenceCapability(**item)
+            except (TypeError, ValueError) as exc:
+                raise EvidenceError(f"invalid coverage capability: {capture_id}: {exc}") from exc
+            ids.add(capability.capability_id)
+        if ids != _CAPABILITIES:
+            raise EvidenceError(f"coverage capability IDs differ from runner profile: {capture_id}")
+    successes = sum(status == "success" for status in statuses)
+    if manifest.get("success_count") != successes or manifest.get("failure_count") != len(statuses) - successes:
+        raise EvidenceError("run terminal counts mismatch")
+    expected_status = "completed" if successes == len(statuses) else "completed_with_failures"
+    if manifest.get("status") != expected_status:
+        raise EvidenceError("run terminal status mismatch")
+    return ref

sphynx/execution_capabilities.py

@@ -0,0 +1,109 @@
+"""Exact opt-in execution paths; legacy drivers keep their own control checks."""
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from typing import Any
+
+from .evaluation_protocols import _envelope
+from .workflow_contracts import BackendDescriptor, WorkflowContractError, _text, _texts
+
+PATH_SCHEMA = "sphynx.execution-path.v1"
+
+
+@dataclass(frozen=True)
+class ExecutionPath:
+    """One scope/location pair. Declarations do not implement enforcement."""
+
+    scope: str
+    mode: str
+    operations: tuple[str, ...] = ("execute",)
+    capabilities: tuple[str, ...] = ()
+    enforcement: tuple[str, ...] = ()
+
+    def __post_init__(self) -> None:
+        _text(self.scope, "scope")
+        _text(self.mode, "mode")
+        for name in ("operations", "capabilities", "enforcement"):
+            object.__setattr__(self, name, _texts(getattr(self, name), name,
+                                                namespaced=name == "capabilities"))
+        if not self.operations:
+            raise WorkflowContractError("execution path must declare operations")
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"schema_version": PATH_SCHEMA, "scope": self.scope, "mode": self.mode,
+                "operations": list(self.operations), "capabilities": list(self.capabilities),
+                "enforcement": list(self.enforcement)}
+
+    @classmethod
+    def from_dict(cls, value: Mapping[str, Any]) -> ExecutionPath:
+        try:
+            return cls(**_envelope(value, PATH_SCHEMA, cls))
+        except TypeError as exc:
+            raise WorkflowContractError("invalid execution path fields") from exc
+
+
+def execution_paths(descriptor: BackendDescriptor) -> tuple[ExecutionPath, ...] | None:
+    """Validate exact opt-in paths. None means historical/native validation."""
+    if not isinstance(descriptor, BackendDescriptor):
+        raise WorkflowContractError("execution support requires BackendDescriptor")
+    if "execution_paths" not in descriptor.metadata:
+        return None
+    raw = descriptor.metadata["execution_paths"]
+    if not isinstance(raw, (list, tuple)) or not raw:
+        raise WorkflowContractError("execution_paths must be a nonempty sequence")
+    paths = tuple(ExecutionPath.from_dict(item) for item in raw)
+    pairs = {(item.scope, item.mode) for item in paths}
+    if len(pairs) != len(paths):
+        raise WorkflowContractError("execution path pairs must be unique")
+    for item in paths:
+        if item.scope not in descriptor.supported_scopes or item.mode not in descriptor.supported_modes:
+            raise WorkflowContractError("execution path exceeds declared scopes/modes")
+        if not set(item.capabilities).issubset(descriptor.capabilities):
+            raise WorkflowContractError("execution path exceeds declared capabilities")
+    return paths
+
+
+def validate_execution_requirement(
+    descriptor: BackendDescriptor, *, scope: str | None = None,
+    mode: str | None = None, operation: str | None = None,
+    capabilities: tuple[str, ...] = (), enforcement: str | None = None,
+) -> None:
+    """Reject unsupported requests without reading cases or starting work.
+
+    A legacy descriptor has no general operation/enforcement claim. Its native
+    methods must still validate controls; this helper never enables them.
+    Explicit enforcement requests require an exact path declaration.
+    """
+    paths = execution_paths(descriptor)
+    if scope is not None:
+        _text(scope, "scope")
+        if scope not in descriptor.supported_scopes:
+            raise WorkflowContractError("backend does not support scope " + repr(scope))
+    if mode is not None:
+        _text(mode, "mode")
+        if mode not in descriptor.supported_modes:
+            raise WorkflowContractError("backend does not support mode " + repr(mode))
+    if operation is not None:
+        _text(operation, "operation")
+    requested = set(_texts(capabilities, "required capabilities", namespaced=True))
+    if enforcement is not None:
+        _text(enforcement, "enforcement")
+    if not requested.issubset(descriptor.capabilities):
+        raise WorkflowContractError("backend lacks required execution capabilities")
+    if paths is None:
+        if enforcement is not None:
+            raise WorkflowContractError("legacy backend does not declare requested enforcement")
+        return
+    matches = [item for item in paths
+               if (scope is None or item.scope == scope) and (mode is None or item.mode == mode)]
+    if not matches:
+        raise WorkflowContractError("backend does not support this scope/mode pair")
+    if operation is not None:
+        matches = [item for item in matches if operation in item.operations]
+        if not matches:
+            raise WorkflowContractError("execution path does not support operation " + repr(operation))
+    matches = [item for item in matches if requested.issubset(item.capabilities)
+               and (enforcement is None or enforcement in item.enforcement)]
+    if not matches:
+        raise WorkflowContractError("execution path lacks requested capabilities/enforcement")