mostlyright-data 0.9.0__py3-none-any.whl

mostlyright/data_harness/studio_boundary.py

@@ -0,0 +1,2019 @@
+"""Lazy, strict boundary between Harness-private contracts and Studio wire models.
+
+Studio's generated Python package is deliberately optional.  This module imports no Studio
+module at import time, so local/replay execution remains installable without the hosted client.
+Every hosted mapping is explicit, carries tenant/fence context, and returns the generated model
+plus deterministic mapping evidence.
+
+Terms used throughout.  The worker protocol that issues them is docs/HOSTED-WORKERS.md.
+
+- Generation and fence: Studio-owned positive integers that order reissues and retries of one
+  attempt.  The Harness never derives or increments them.  It carries the exact values Studio
+  issued and rejects any server value that differs, so a stale worker cannot write over newer
+  state.  producer_generation, producer_fence, verification_generation, verifier_generation
+  and verifier_fence are all of this kind.  object_generation is not: it is the storage
+  object's own generation, a decimal string on signed-session wire values.
+- Epoch: a Studio-owned positive integer naming which candidate selection (selection_epoch) or
+  which recipe activation (activation_epoch) a scope belongs to.  Also carried, never derived.
+- HostedFence: the tenant and attempt coordinates a caller must supply before this module will
+  parse a Studio-owned value.  Parsing fails closed when a required coordinate is absent.
+- Model-free V3: the contract set pinned by PINNED_CONTRACT_SET, in which verification is
+  deterministic and no model sits in the loop.  The surfaces that once carried model-mediated
+  semantic review still exist here and always raise, so a caller on that path fails loudly
+  instead of sending evidence Studio no longer accepts.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import importlib
+import json
+import re
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from functools import lru_cache
+from types import ModuleType
+from typing import Any
+from uuid import UUID
+
+from mostlyright.data_harness.agent_runtime import AgentCallEvidence
+from mostlyright.data_harness.local_contracts import (
+    LocalQuestion,
+    LocalRequirements,
+    SourceProposal,
+)
+from mostlyright.data_harness.local_contracts import (
+    TablePlan as LocalTablePlan,
+)
+from mostlyright.data_harness.recipe import BACKFILL_POLICY_SCHEMA_VERSION, BackfillPolicy
+
+PINNED_CONTRACT_SET = "mostlyright-studio-v3"
+PINNED_CONTRACT_VERSION = "3.0.0"
+PINNED_GENERATOR = "openapi-python-client"
+PINNED_GENERATOR_VERSION = "0.27.1"
+PINNED_OPENAPI_SOURCE_SHA256 = "d63d5e36527c7a13b5c27c73589b583604b832b11231efc73267d63ed490e694"
+
+_DIGEST = re.compile(r"^sha256:[0-9a-f]{64}$")
+_IMAGE_DIGEST = re.compile(r"^[a-z0-9][a-z0-9._/-]{0,254}@sha256:[0-9a-f]{64}$")
+_SEMVER = re.compile(r"^[1-9][0-9]*\.[0-9]+\.[0-9]+$")
+_UTC = re.compile(
+    r"^(?:[0-9]{4})-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])"
+    r"T(?:[01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9](?:\.[0-9]{1,9})?Z$"
+)
+_UUID_FIELDS = frozenset(
+    {
+        "admission_id",
+        "artifact_id",
+        "actor_principal_id",
+        "budget_id",
+        "call_id",
+        "closure_review_id",
+        "connector_id",
+        "event_id",
+        "finding_id",
+        "gate_lineage_id",
+        "table_plan_id",
+        "predecessor_table_plan_id",
+        "producer_attempt_id",
+        "dataset_id",
+        "question_id",
+        "requirements_id",
+        "review_id",
+        "rights_decision_id",
+        "run_id",
+        "source_id",
+        "submission_id",
+        "superseded_by_admission_id",
+        "verifier_principal_id",
+        "workspace_id",
+        "attempt_id",
+    }
+)
+_TIMESTAMP_FIELDS = frozenset(
+    {
+        "occurred_at",
+        "created_at",
+        "sealed_at",
+        "retention_expires_at",
+        "admitted_at",
+        "selected_at",
+        "revoked_at",
+        "opened_at",
+        "closed_at",
+        "started_at",
+        "completed_at",
+        "start_inclusive",
+        "end_exclusive",
+        "result_observed_at",
+    }
+)
+_BARE_DIGEST_FIELDS = frozenset(
+    {
+        "artifact_manifest_digest",
+        "bootstrap_table_digest",
+        "bootstrap_verification_digest",
+        "execution_scope_digest",
+        "lineage_digest",
+        "predecessor_recipe_digest",
+        "recipe_approval_digest",
+        "recipe_digest",
+        "resulting_source_states_digest",
+        "source_authority_bindings_digest",
+        "source_authority_digest",
+        "state_digest",
+    }
+)
+
+
+class StudioBoundaryError(RuntimeError):
+    """Base error for hosted-boundary loading, compatibility, and mapping failures."""
+
+
+class StudioClientUnavailableError(StudioBoundaryError, ImportError):
+    """The optional generated Studio client is not installed."""
+
+
+class StudioClientIncompatibleError(StudioBoundaryError):
+    """The installed generated client does not match the pinned contract identity."""
+
+
+class StudioBoundaryValidationError(StudioBoundaryError, ValueError):
+    """A local value or generated wire value cannot cross the boundary losslessly."""
+
+
+@dataclass(frozen=True)
+class StudioContractIdentity:
+    contract_set: str
+    contract_version: str
+    generator: str
+    generator_version: str
+    openapi_source_sha256: str
+
+    def to_dict(self) -> dict[str, str]:
+        return {
+            "contract_set": self.contract_set,
+            "contract_version": self.contract_version,
+            "generator": self.generator,
+            "generator_version": self.generator_version,
+            "openapi_source_sha256": self.openapi_source_sha256,
+        }
+
+
+@dataclass(frozen=True)
+class BoundaryMappingEvidence:
+    contract: StudioContractIdentity
+    model_name: str
+    local_schema_version: str
+    local_digest: str
+    workspace_id: UUID
+    run_id: UUID | None = None
+    attempt_id: UUID | None = None
+    producer_generation: int | None = None
+    producer_fence: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        result: dict[str, Any] = {
+            "contract": self.contract.to_dict(),
+            "model_name": self.model_name,
+            "local_schema_version": self.local_schema_version,
+            "local_digest": _wire_digest(
+                self.local_digest,
+                "local_digest",
+                allow_raw=True,
+            ),
+            "workspace_id": str(self.workspace_id),
+        }
+        for name in ("run_id", "attempt_id"):
+            value = getattr(self, name)
+            if value is not None:
+                result[name] = str(value)
+        for name in ("producer_generation", "producer_fence"):
+            value = getattr(self, name)
+            if value is not None:
+                result[name] = value
+        return result
+
+
+@dataclass(frozen=True)
+class MappedStudioValue:
+    """A generated Studio model paired with the exact contract/mapping identity."""
+
+    model: Any
+    evidence: BoundaryMappingEvidence
+
+    def to_wire_dict(self) -> dict[str, Any]:
+        return studio_wire_dict(self.model)
+
+
+@dataclass(frozen=True)
+class QuestionIdentity:
+    workspace_id: UUID
+    dataset_id: UUID
+    question_id: UUID
+    created_by_principal_id: UUID
+    status: str = "draft"
+
+    def __post_init__(self) -> None:
+        _uuids(self)
+        _nonempty(self.status, "status", maximum=64)
+
+
+@dataclass(frozen=True)
+class RequirementsIdentity:
+    workspace_id: UUID
+    requirements_id: UUID
+    question_id: UUID
+    prediction_cutoff: str | None = None
+
+    def __post_init__(self) -> None:
+        _uuids(self)
+        if self.prediction_cutoff is not None:
+            _parse_utc(self.prediction_cutoff, "prediction_cutoff")
+
+
+@dataclass(frozen=True)
+class OpaqueSecretBinding:
+    name: str
+    handle_id: str
+    workspace_id: UUID
+    connector_id: UUID
+    attempt_id: UUID
+    purpose: str
+
+    def __post_init__(self) -> None:
+        _uuids(self)
+        if not re.fullmatch(r"[a-z][a-z0-9]*(?:[-_.][a-z0-9]+)*", self.name):
+            raise StudioBoundaryValidationError("secret.name must be a canonical identifier")
+        if not re.fullmatch(r"shr_[A-Za-z0-9_-]{24,120}", self.handle_id):
+            raise StudioBoundaryValidationError(
+                "secret.handle_id must be a server-issued opaque handle"
+            )
+        if self.purpose not in {"provider_auth", "source_acquisition", "web_extraction"}:
+            raise StudioBoundaryValidationError("secret.purpose is unsupported")
+
+
+@dataclass(frozen=True)
+class SourceIdentity:
+    workspace_id: UUID
+    dataset_id: UUID
+    source_id: UUID
+    data_classification: str
+    raw_retention_days: int
+    derived_retention_days: int
+    tombstone_required: bool
+    status: str
+    rights_evidence_digest: str | None
+    rights_claim_digest: str
+    rights_policy_digest: str
+    rights_adjudication: str
+    credential_reference_ids: tuple[UUID, ...] = ()
+    connector_contract_version: str | None = None
+    rights_decision_id: UUID | None = None
+
+    def __post_init__(self) -> None:
+        _uuids(self)
+        _nonempty(self.data_classification, "data_classification", maximum=64)
+        _bounded_int(self.raw_retention_days, "raw_retention_days", 0, 3650)
+        _bounded_int(self.derived_retention_days, "derived_retention_days", 0, 3650)
+        if type(self.tombstone_required) is not bool:
+            raise StudioBoundaryValidationError("tombstone_required must be a boolean")
+        _nonempty(self.status, "status", maximum=64)
+        if self.rights_evidence_digest is not None:
+            _wire_digest(self.rights_evidence_digest, "rights_evidence_digest")
+        _wire_digest(self.rights_claim_digest, "rights_claim_digest")
+        _wire_digest(self.rights_policy_digest, "rights_policy_digest")
+        if self.rights_adjudication not in {"server_derived", "human_reviewed"}:
+            raise StudioBoundaryValidationError("rights_adjudication is unsupported")
+        if self.rights_adjudication == "human_reviewed":
+            if self.rights_decision_id is None or self.rights_evidence_digest is None:
+                raise StudioBoundaryValidationError(
+                    "human_reviewed rights require decision ID and evidence digest"
+                )
+        elif self.rights_decision_id is not None:
+            raise StudioBoundaryValidationError(
+                "server_derived rights cannot carry a human decision ID"
+            )
+        if len(self.credential_reference_ids) > 16:
+            raise StudioBoundaryValidationError("credential_reference_ids exceeds 16 entries")
+        if not all(isinstance(item, UUID) for item in self.credential_reference_ids):
+            raise StudioBoundaryValidationError("credential_reference_ids must contain UUIDs")
+        if len(self.credential_reference_ids) != len(set(self.credential_reference_ids)):
+            raise StudioBoundaryValidationError("credential_reference_ids contains duplicates")
+        if self.connector_contract_version is not None:
+            _semver(self.connector_contract_version, "connector_contract_version")
+
+
+@dataclass(frozen=True)
+class PlanIdentity:
+    workspace_id: UUID
+    dataset_id: UUID
+    table_plan_id: UUID
+    question_id: UUID
+    requirements_id: UUID
+    source_ids: tuple[tuple[str, UUID], ...]
+    revision: int
+    transformation_contract_version: str
+    validation_policy_digest: str
+    backfill_policy: BackfillPolicy
+    status: str
+    created_at: str
+    predecessor_table_plan_id: UUID | None = None
+    # map_plan, the only consumer, rejects any non-None value on the model-free V3 plan boundary.
+    semantic_approval_key_digest: str | None = None
+
+    def __post_init__(self) -> None:
+        _uuids(self)
+        _bounded_int(self.revision, "revision", 1, (1 << 63) - 1)
+        _semver(self.transformation_contract_version, "transformation_contract_version")
+        _wire_digest(self.validation_policy_digest, "validation_policy_digest")
+        if not isinstance(self.backfill_policy, BackfillPolicy):
+            raise StudioBoundaryValidationError("backfill_policy must be a concrete Harness policy")
+        _nonempty(self.status, "status", maximum=64)
+        _parse_utc(self.created_at, "created_at")
+        if self.semantic_approval_key_digest is not None:
+            _wire_digest(self.semantic_approval_key_digest, "semantic_approval_key_digest")
+        local_names = [item[0] for item in self.source_ids]
+        if len(local_names) != len(set(local_names)):
+            raise StudioBoundaryValidationError("source_ids contains duplicate local identifiers")
+        hosted_ids = [item[1] for item in self.source_ids]
+        if len(hosted_ids) != len(set(hosted_ids)):
+            raise StudioBoundaryValidationError("source_ids contains duplicate hosted identifiers")
+        if not all(isinstance(item, UUID) for item in hosted_ids):
+            raise StudioBoundaryValidationError("source_ids must map to UUID values")
+
+    @property
+    def backfill_policy_digest(self) -> str:
+        """Studio wire digest of the exact immutable Harness policy bytes."""
+
+        return f"sha256:{self.backfill_policy.digest}"
+
+
+@dataclass(frozen=True)
+class AgentCallIdentity:
+    workspace_id: UUID
+    run_id: UUID
+    attempt_id: UUID
+    call_id: UUID
+    budget_id: UUID
+    evidence_digest: str
+    started_at: str
+    completed_at: str
+    currency: str
+
+    def __post_init__(self) -> None:
+        _uuids(self)
+        if not re.fullmatch(r"[0-9a-f]{64}", self.evidence_digest):
+            raise StudioBoundaryValidationError("evidence_digest must be a raw SHA-256")
+        started = _parse_utc(self.started_at, "started_at")
+        completed = _parse_utc(self.completed_at, "completed_at")
+        if completed < started:
+            raise StudioBoundaryValidationError("completed_at precedes started_at")
+        if self.currency != "USD":
+            raise StudioBoundaryValidationError("agent-call micro-cost currency must be USD")
+
+
+@dataclass(frozen=True)
+class HostedFence:
+    """Expected tenant, run, and attempt coordinates for parsing Studio-owned values.
+
+    Optional fields are supplied only when the caller holds them.  Each parser states which of
+    them it requires and fails closed when a required one is None.
+    """
+
+    workspace_id: UUID
+    run_id: UUID
+    attempt_id: UUID | None = None
+    gate_lineage_id: UUID | None = None
+    producer_generation: int | None = None
+    producer_fence: int | None = None
+
+    def __post_init__(self) -> None:
+        _uuids(self)
+        for name in ("producer_generation", "producer_fence"):
+            value = getattr(self, name)
+            if value is not None:
+                _bounded_int(value, name, 1, (1 << 63) - 1)
+
+
+@dataclass(frozen=True)
+class ProducerEvidenceScope:
+    """Server-issued producer attempt coordinates required on evidence ingress."""
+
+    workspace_id: UUID
+    run_id: UUID
+    attempt_id: UUID
+    producer_generation: int
+    producer_fence: int
+
+    def __post_init__(self) -> None:
+        _uuids(self)
+        _bounded_int(
+            self.producer_generation,
+            "producer_generation",
+            1,
+            (1 << 63) - 1,
+        )
+        _bounded_int(self.producer_fence, "producer_fence", 1, (1 << 63) - 1)
+
+
+@dataclass(frozen=True)
+class VerifierReviewScope:
+    """Complete server-issued coordinates for verifier reads and report submission."""
+
+    workspace_id: UUID
+    run_id: UUID
+    gate_lineage_id: UUID
+    attempt_id: UUID
+    verification_generation: int
+    verifier_generation: int
+    verifier_fence: int
+    admission_id: UUID
+    selection_epoch: int
+    candidate_digest: str
+    candidate_contract_version: str
+    dataset_id: UUID
+    table_id: UUID
+    table_recipe_id: str
+    recipe_version: int
+    recipe_digest: str
+    activation_epoch: int
+    execution_scope_digest: str
+    validation_policy_digest: str
+    release_policy_digest: str
+    artifact_scope_digest: str
+    verifier_principal_id: UUID
+    verifier_image_digest: str
+    required_check_ids: tuple[str, ...]
+    attestation_scheme: str
+    attestation_key_id: str
+    attestation_key_version: int
+    resulting_source_states: tuple[Mapping[str, Any], ...] | None = None
+    resulting_source_states_digest: str | None = None
+
+    def __post_init__(self) -> None:
+        _uuids(self)
+        for name in (
+            "verification_generation",
+            "verifier_generation",
+            "verifier_fence",
+            "selection_epoch",
+            "recipe_version",
+            "activation_epoch",
+        ):
+            _bounded_int(getattr(self, name), name, 1, (1 << 63) - 1)
+        for name in (
+            "candidate_digest",
+            "validation_policy_digest",
+            "release_policy_digest",
+            "artifact_scope_digest",
+        ):
+            _wire_digest(getattr(self, name), name)
+        _bare_digest(self.recipe_digest, "recipe_digest")
+        _bare_digest(self.execution_scope_digest, "execution_scope_digest")
+        if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9_.-]{0,127}", self.table_recipe_id):
+            raise StudioBoundaryValidationError("table_recipe_id is not canonical")
+        _semver(self.candidate_contract_version, "candidate_contract_version")
+        if not _IMAGE_DIGEST.fullmatch(self.verifier_image_digest):
+            raise StudioBoundaryValidationError("verifier_image_digest is not canonical")
+        if (
+            type(self.required_check_ids) is not tuple
+            or not self.required_check_ids
+            or len(self.required_check_ids) != len(set(self.required_check_ids))
+        ):
+            raise StudioBoundaryValidationError(
+                "required_check_ids must be a nonempty unique tuple"
+            )
+        for check_id in self.required_check_ids:
+            if not re.fullmatch(r"[A-Z][A-Z0-9_]{2,127}", check_id):
+                raise StudioBoundaryValidationError("required_check_ids contains an invalid ID")
+        if (self.resulting_source_states is None) != (self.resulting_source_states_digest is None):
+            raise StudioBoundaryValidationError(
+                "resulting source states and digest must both be present or absent"
+            )
+        if self.resulting_source_states is not None:
+            if type(self.resulting_source_states) is not tuple or not self.resulting_source_states:
+                raise StudioBoundaryValidationError(
+                    "resulting_source_states must be a nonempty tuple"
+                )
+            canonical_states = [dict(item) for item in self.resulting_source_states]
+            if canonical_states != sorted(
+                canonical_states,
+                key=lambda item: item.get("source_id", ""),
+            ):
+                raise StudioBoundaryValidationError(
+                    "resulting_source_states must be ordered by source_id"
+                )
+            expected_digest = hashlib.sha256(
+                json.dumps(
+                    canonical_states,
+                    sort_keys=True,
+                    separators=(",", ":"),
+                    ensure_ascii=False,
+                ).encode("utf-8")
+            ).hexdigest()
+            _match(
+                self.resulting_source_states_digest,
+                expected_digest,
+                "resulting_source_states_digest",
+            )
+        if self.attestation_scheme != "ed25519-v1":
+            raise StudioBoundaryValidationError("attestation_scheme is unsupported")
+        _nonempty(self.attestation_key_id, "attestation_key_id", maximum=512)
+        _bounded_int(
+            self.attestation_key_version,
+            "attestation_key_version",
+            1,
+            (1 << 63) - 1,
+        )
+
+
+@dataclass(frozen=True)
+class _StudioAPI:
+    models: ModuleType
+    unset: Any
+    identity: StudioContractIdentity
+
+
+def client_contract_identity() -> StudioContractIdentity:
+    """Load and verify the optional generated client, returning its pinned identity."""
+
+    return _studio_api().identity
+
+
+def ensure_studio_client() -> None:
+    """Fail closed if the installed hosted extra is absent or incompatible."""
+
+    _studio_api()
+
+
+@lru_cache(maxsize=1)
+def _studio_api() -> _StudioAPI:
+    try:
+        contract_info = importlib.import_module("mostlyright_studio.contract_info")
+        models = importlib.import_module("mostlyright_studio.models")
+        studio_types = importlib.import_module("mostlyright_studio.types")
+    except ModuleNotFoundError as exc:
+        raise StudioClientUnavailableError(
+            "Hosted Studio functionality requires the exact generated Studio V3 client. "
+            "Install the supported 'mostlyright-data[hosted]' distribution; the "
+            "base worker/crawler distribution intentionally excludes Studio client code."
+        ) from exc
+
+    actual = StudioContractIdentity(
+        contract_set=getattr(contract_info, "CONTRACT_SET", ""),
+        contract_version=getattr(contract_info, "CONTRACT_VERSION", ""),
+        generator=getattr(contract_info, "GENERATOR", ""),
+        generator_version=getattr(contract_info, "GENERATOR_VERSION", ""),
+        openapi_source_sha256=getattr(contract_info, "OPENAPI_SOURCE_SHA256", ""),
+    )
+    expected = StudioContractIdentity(
+        contract_set=PINNED_CONTRACT_SET,
+        contract_version=PINNED_CONTRACT_VERSION,
+        generator=PINNED_GENERATOR,
+        generator_version=PINNED_GENERATOR_VERSION,
+        openapi_source_sha256=PINNED_OPENAPI_SOURCE_SHA256,
+    )
+    if actual != expected:
+        raise StudioClientIncompatibleError(
+            f"generated Studio client identity mismatch: expected {expected.to_dict()}, "
+            f"got {actual.to_dict()}"
+        )
+    # Import-time probe, not the complete dependency list.  Other generated symbols this module
+    # resolves are absent here on purpose: SourceHealthObservation, SourceFitnessReport,
+    # ContractHalfOpenTimeRange, and every generated enum.  A client missing one of those fails
+    # at first use instead, as StudioClientIncompatibleError from _strict_generated_parse or
+    # _require_generated_model, or as AttributeError from a direct api.models access.
+    required_models = {
+        "CandidateAdmissionAndStudioSelection",
+        "ContractProducerAgentCallCommand",
+        "ContractProducerSignedSession",
+        "ContractProducerSourceFitnessCommand",
+        "ContractProducerSourceObservationCommand",
+        "ContractAffectedArtifact",
+        "ContractApprovedBackfillPolicy",
+        "ContractCategory",
+        "ContractFindingProposal",
+        "ContractRightsDecisionCommand",
+        "ContractRightsReview",
+        "ContractSubmissionCommand",
+        "ContractVerifierDownloadCommand",
+        "ContractVerifierFindingCommand",
+        "ContractVerifierRuntimeJob",
+        "ContractVerifierSignedSession",
+        "TablePlanProposalPrecursor",
+        "TableQuestion",
+        "TableRequirements",
+        "DurableRunEvent",
+        "ImmutableArtifactMetadata",
+        "LosslessAgentCallEvidence",
+        "RecipeBoundDeterministicFinding",
+        "SourceRegistryEntry",
+    }
+    missing = sorted(required_models - set(vars(models)))
+    if missing:
+        raise StudioClientIncompatibleError(
+            f"generated Studio client is missing required models: {missing}"
+        )
+    return _StudioAPI(models=models, unset=studio_types.UNSET, identity=actual)
+
+
+def map_question(question: LocalQuestion, identity: QuestionIdentity) -> MappedStudioValue:
+    api = _studio_api()
+    if len(question.text) < 10:
+        raise StudioBoundaryValidationError("question.text is shorter than Studio's minimum")
+    question_preimage = {
+        "workspace_id": str(identity.workspace_id),
+        "dataset_id": str(identity.dataset_id),
+        "question_id": str(identity.question_id),
+        "text": question.text,
+    }
+    question_digest = (
+        "sha256:"
+        + hashlib.sha256(
+            json.dumps(
+                question_preimage,
+                ensure_ascii=False,
+                allow_nan=False,
+                separators=(",", ":"),
+                sort_keys=True,
+            ).encode("utf-8")
+        ).hexdigest()
+    )
+    model = api.models.TableQuestion(
+        schema_version=PINNED_CONTRACT_VERSION,
+        question_id=identity.question_id,
+        workspace_id=identity.workspace_id,
+        dataset_id=identity.dataset_id,
+        text=question.text,
+        question_digest=question_digest,
+        status=_generated_enum(
+            api.models.TableQuestionStatus,
+            identity.status,
+            "question.status",
+        ),
+        created_at=_parse_utc(question.created_at, "question.created_at"),
+        created_by_principal_id=identity.created_by_principal_id,
+    )
+    return _mapped(model, question, identity.workspace_id)
+
+
+def map_requirements(
+    requirements: LocalRequirements,
+    identity: RequirementsIdentity,
+) -> MappedStudioValue:
+    api = _studio_api()
+    prediction_cutoff = (
+        api.unset
+        if identity.prediction_cutoff is None
+        else _parse_utc(identity.prediction_cutoff, "prediction_cutoff")
+    )
+    model = api.models.TableRequirements(
+        schema_version=PINNED_CONTRACT_VERSION,
+        requirements_id=identity.requirements_id,
+        workspace_id=identity.workspace_id,
+        question_id=identity.question_id,
+        population=requirements.population,
+        time_range=api.models.ContractHalfOpenTimeRange(
+            start_inclusive=_parse_utc(
+                requirements.time_range.start_inclusive,
+                "requirements.time_range.start_inclusive",
+            ),
+            end_exclusive=_parse_utc(
+                requirements.time_range.end_exclusive,
+                "requirements.time_range.end_exclusive",
+            ),
+        ),
+        output_grain=list(requirements.output_grain.columns),
+        required_fields=list(requirements.required_fields),
+        target_policy=_generated_enum(
+            api.models.TableRequirementsTargetPolicy,
+            requirements.target_policy,
+            "requirements.target_policy",
+        ),
+        success_criteria=list(requirements.success_criteria),
+        feasibility=api.models.TableRequirementsFeasibility(
+            decision=_generated_enum(
+                api.models.TableRequirementsFeasibilityDecision,
+                requirements.feasibility.decision,
+                "requirements.feasibility.decision",
+            ),
+            reason_codes=[
+                _generated_enum(
+                    api.models.TableRequirementsFeasibilityReasonCodesItem,
+                    code.upper(),
+                    f"requirements.feasibility.reason_codes[{index}]",
+                )
+                for index, code in enumerate(requirements.feasibility.reason_codes)
+            ],
+            narrative=requirements.feasibility.narrative,
+        ),
+        requirements_digest=_wire_digest(
+            requirements.digest,
+            "requirements.digest",
+            allow_raw=True,
+        ),
+        created_at=_parse_utc(requirements.created_at, "requirements.created_at"),
+        prediction_cutoff=prediction_cutoff,
+    )
+    return _mapped(model, requirements, identity.workspace_id)
+
+
+def map_source_proposal(
+    proposal: SourceProposal,
+    identity: SourceIdentity,
+) -> MappedStudioValue:
+    api = _studio_api()
+    locator_kind = {
+        "artifact_reference": "artifact",
+        "https_url": "https_url",
+    }.get(proposal.locator_kind)
+    if locator_kind is None:
+        raise StudioBoundaryValidationError(
+            f"source locator kind {proposal.locator_kind!r} has no Studio wire representation"
+        )
+    if proposal.rights_status in {"approved", "conditional"} and (
+        identity.rights_evidence_digest is None
+    ):
+        raise StudioBoundaryValidationError(
+            "approved/conditional source mapping requires rights_evidence_digest"
+        )
+    connector_version: Any = (
+        api.unset
+        if identity.connector_contract_version is None
+        else identity.connector_contract_version
+    )
+    rights_digest: Any = (
+        api.unset if identity.rights_evidence_digest is None else identity.rights_evidence_digest
+    )
+    rights_decision_id: Any = (
+        api.unset if identity.rights_decision_id is None else identity.rights_decision_id
+    )
+    model = api.models.SourceRegistryEntry(
+        schema_version=PINNED_CONTRACT_VERSION,
+        source_id=identity.source_id,
+        workspace_id=identity.workspace_id,
+        dataset_id=identity.dataset_id,
+        name=proposal.display_name,
+        source_class=_generated_enum(
+            api.models.SourceRegistryEntrySourceClass,
+            proposal.source_class,
+            "source.source_class",
+        ),
+        locator=api.models.SourceRegistryEntryLocator(
+            kind=_generated_enum(
+                api.models.SourceRegistryEntryLocatorKind,
+                locator_kind,
+                "source.locator.kind",
+            ),
+            display_locator=proposal.locator,
+            connector_contract_version=connector_version,
+        ),
+        credential_reference_ids=list(identity.credential_reference_ids),
+        data_classification=_generated_enum(
+            api.models.SourceRegistryEntryDataClassification,
+            identity.data_classification,
+            "source.data_classification",
+        ),
+        rights_status=_generated_enum(
+            api.models.SourceRegistryEntryRightsStatus,
+            proposal.rights_status,
+            "source.rights_status",
+        ),
+        rights_claim_digest=identity.rights_claim_digest,
+        rights_policy_digest=identity.rights_policy_digest,
+        rights_adjudication=_generated_enum(
+            api.models.SourceRegistryEntryRightsAdjudication,
+            identity.rights_adjudication,
+            "source.rights_adjudication",
+        ),
+        retention_policy=api.models.SourceRegistryEntryRetentionPolicy(
+            raw_days=identity.raw_retention_days,
+            derived_days=identity.derived_retention_days,
+            tombstone_required=identity.tombstone_required,
+        ),
+        status=_generated_enum(
+            api.models.SourceRegistryEntryStatus,
+            identity.status,
+            "source.status",
+        ),
+        created_at=_parse_utc(proposal.observed_at, "proposal.observed_at"),
+        rights_evidence_digest=rights_digest,
+        rights_decision_id=rights_decision_id,
+    )
+    return _mapped(model, proposal, identity.workspace_id)
+
+
+def map_plan(plan: LocalTablePlan, identity: PlanIdentity) -> MappedStudioValue:
+    api = _studio_api()
+    mapping = dict(identity.source_ids)
+    local_sources = {source.source_id for source in plan.sources}
+    if set(mapping) != local_sources:
+        raise StudioBoundaryValidationError(
+            "plan source identity mapping must exactly match local plan sources"
+        )
+    predecessor: Any = (
+        api.unset
+        if identity.predecessor_table_plan_id is None
+        else identity.predecessor_table_plan_id
+    )
+    if identity.semantic_approval_key_digest is not None:
+        raise StudioBoundaryValidationError(
+            "semantic_approval_key_digest is retired from the model-free V3 plan boundary"
+        )
+    approved_backfill_policy = _strict_generated_parse(
+        "ContractApprovedBackfillPolicy",
+        identity.backfill_policy.to_dict(),
+        expected_schema_version=BACKFILL_POLICY_SCHEMA_VERSION,
+    )
+    model = api.models.TablePlanProposalPrecursor(
+        schema_version=PINNED_CONTRACT_VERSION,
+        table_plan_id=identity.table_plan_id,
+        workspace_id=identity.workspace_id,
+        dataset_id=identity.dataset_id,
+        question_id=identity.question_id,
+        requirements_id=identity.requirements_id,
+        revision=identity.revision,
+        source_ids=[mapping[source.source_id] for source in plan.sources],
+        output_grain=list(plan.grain),
+        transformation_contract_version=identity.transformation_contract_version,
+        validation_policy_digest=identity.validation_policy_digest,
+        approved_backfill_policy=approved_backfill_policy,
+        backfill_policy_digest=identity.backfill_policy_digest,
+        plan_digest=_wire_digest(plan.digest, "plan.digest", allow_raw=True),
+        status=_generated_enum(
+            api.models.TablePlanProposalPrecursorStatus,
+            identity.status,
+            "plan.status",
+        ),
+        created_at=_parse_utc(identity.created_at, "created_at"),
+        predecessor_table_plan_id=predecessor,
+    )
+    return _mapped(model, plan, identity.workspace_id)
+
+
+def map_agent_call_evidence(
+    evidence: AgentCallEvidence,
+    identity: AgentCallIdentity,
+) -> MappedStudioValue:
+    api = _studio_api()
+    if identity.evidence_digest != evidence.evidence_sha256:
+        raise StudioBoundaryValidationError("agent-call identity is not bound to this evidence")
+    wall_elapsed = _parse_utc(identity.completed_at, "completed_at") - _parse_utc(
+        identity.started_at, "started_at"
+    )
+    if int(wall_elapsed.total_seconds() * 1_000_000) != evidence.timing.elapsed_micros:
+        raise StudioBoundaryValidationError(
+            "hosted wall-clock interval does not match deterministic timing evidence"
+        )
+    secret_references: list[dict[str, Any]] = []
+    for index, reference in enumerate(evidence.secret_references):
+        path = f"secret_references[{index}]"
+        try:
+            workspace_id = UUID(reference.workspace_id)
+            connector_id = UUID(reference.connector_id)
+            attempt_id = UUID(reference.attempt_id)
+        except ValueError as exc:
+            raise StudioBoundaryValidationError(
+                f"{path} scope identifiers must be canonical UUIDs"
+            ) from exc
+        _match(workspace_id, identity.workspace_id, f"{path}.workspace_id")
+        _match(attempt_id, identity.attempt_id, f"{path}.attempt_id")
+        secret_references.append(
+            {
+                "name": reference.name,
+                "handle_id": reference.handle_id,
+                "workspace_id": str(workspace_id),
+                "connector_id": str(connector_id),
+                "attempt_id": str(attempt_id),
+                "purpose": reference.purpose,
+            }
+        )
+    tool_names = {
+        "search": "sanctioned_search",
+        "browse": "sanctioned_browse",
+    }
+    tool_evidence: list[dict[str, Any]] = []
+    for index, item in enumerate(evidence.tool_evidence):
+        tool_name = tool_names.get(item.name)
+        if tool_name is None:
+            raise StudioBoundaryValidationError(
+                f"tool_evidence[{index}].name has no Studio wire representation"
+            )
+        tool_evidence.append(
+            {
+                "sequence": item.sequence,
+                "name": tool_name,
+                "arguments_digest": _wire_digest(
+                    item.arguments_sha256,
+                    f"tool_evidence[{index}].arguments_sha256",
+                    allow_raw=True,
+                ),
+                "invocation_digest": _wire_digest(
+                    item.invocation_sha256,
+                    f"tool_evidence[{index}].invocation_sha256",
+                    allow_raw=True,
+                ),
+            }
+        )
+    wire: dict[str, Any] = {
+        "schema_version": PINNED_CONTRACT_VERSION,
+        "call_id": str(identity.call_id),
+        "workspace_id": str(identity.workspace_id),
+        "run_id": str(identity.run_id),
+        "attempt_id": str(identity.attempt_id),
+        "budget_id": str(identity.budget_id),
+        "runtime_version": evidence.runtime_version,
+        "request_contract_version": evidence.request_contract_version,
+        "response_contract_version": evidence.response_contract_version,
+        "provider": evidence.provider,
+        "model_identifier": evidence.model_identifier,
+        "provider_configuration_digest": _wire_digest(
+            evidence.provider_configuration_sha256,
+            "provider_configuration_sha256",
+            allow_raw=True,
+        ),
+        "role": evidence.role,
+        "prompt_template_version": evidence.prompt_template_version,
+        "prompt_digest": _wire_digest(
+            evidence.prompt_sha256,
+            "prompt_sha256",
+            allow_raw=True,
+        ),
+        "tool_policy_version": evidence.tool_policy_version,
+        "request_digest": _wire_digest(
+            evidence.request_sha256,
+            "request_sha256",
+            allow_raw=True,
+        ),
+        "secret_references": secret_references,
+        "tool_evidence": tool_evidence,
+        "usage": {
+            "accounting_status": evidence.usage.accounting_status,
+            "input_tokens": evidence.usage.input_tokens,
+            "output_tokens": evidence.usage.output_tokens,
+            "total_tokens": evidence.usage.total_tokens,
+            "cached_input_tokens": evidence.usage.cached_input_tokens,
+            "reasoning_tokens": evidence.usage.reasoning_tokens,
+            "cost_usd_micros": evidence.usage.cost_usd_micros,
+        },
+        "timing": {
+            **evidence.timing.to_dict(),
+            "deadline_micros": evidence.deadline_micros,
+        },
+        "outcome": evidence.outcome,
+        "started_at": identity.started_at,
+        "completed_at": identity.completed_at,
+    }
+    if evidence.replay_fixture_version is not None:
+        wire["replay_fixture_version"] = evidence.replay_fixture_version
+    if evidence.response_sha256 is not None:
+        wire["response_digest"] = _wire_digest(
+            evidence.response_sha256,
+            "response_sha256",
+            allow_raw=True,
+        )
+    if evidence.raw_response_sha256 is not None:
+        wire["raw_response_digest"] = _wire_digest(
+            evidence.raw_response_sha256,
+            "raw_response_sha256",
+            allow_raw=True,
+        )
+    if evidence.failure_code is not None:
+        wire["failure_code"] = evidence.failure_code
+    model = _strict_generated_parse("LosslessAgentCallEvidence", wire)
+    return MappedStudioValue(
+        model=model,
+        evidence=BoundaryMappingEvidence(
+            contract=api.identity,
+            model_name=type(model).__name__,
+            local_schema_version=evidence.schema_version,
+            local_digest=evidence.evidence_sha256,
+            workspace_id=identity.workspace_id,
+            run_id=identity.run_id,
+            attempt_id=identity.attempt_id,
+        ),
+    )
+
+
+def map_producer_agent_call_submission(
+    evidence: AgentCallEvidence,
+    identity: AgentCallIdentity,
+    scope: ProducerEvidenceScope,
+) -> Any:
+    """Map local lossless agent evidence into the typed fenced producer command."""
+
+    _match(identity.workspace_id, scope.workspace_id, "workspace_id")
+    _match(identity.run_id, scope.run_id, "run_id")
+    _match(identity.attempt_id, scope.attempt_id, "attempt_id")
+    mapped = map_agent_call_evidence(evidence, identity)
+    api = _studio_api()
+    return api.models.ContractProducerAgentCallCommand(
+        schema_version=PINNED_CONTRACT_VERSION,
+        workspace_id=scope.workspace_id,
+        run_id=scope.run_id,
+        attempt_id=scope.attempt_id,
+        producer_generation=scope.producer_generation,
+        producer_fence=scope.producer_fence,
+        authority="producer_attempt_evidence",
+        payload_digest=_evidence_payload_digest(
+            "submitProducerAgentCallEvidence",
+            mapped.to_wire_dict(),
+        ),
+        agent_call=mapped.model,
+    )
+
+
+def map_producer_source_observation_submission(
+    observation: Any,
+    scope: ProducerEvidenceScope,
+) -> Any:
+    """Wrap an exact generated source observation in producer-only ingress authority."""
+
+    _require_generated_model(observation, "SourceHealthObservation")
+    _match(observation.workspace_id, scope.workspace_id, "source_observation.workspace_id")
+    api = _studio_api()
+    return api.models.ContractProducerSourceObservationCommand(
+        schema_version=PINNED_CONTRACT_VERSION,
+        workspace_id=scope.workspace_id,
+        run_id=scope.run_id,
+        attempt_id=scope.attempt_id,
+        producer_generation=scope.producer_generation,
+        producer_fence=scope.producer_fence,
+        authority="producer_attempt_evidence",
+        payload_digest=_evidence_payload_digest(
+            "submitProducerSourceObservation",
+            studio_wire_dict(observation),
+        ),
+        source_observation=observation,
+    )
+
+
+def map_producer_source_fitness_submission(
+    report: Any,
+    scope: ProducerEvidenceScope,
+) -> Any:
+    """Wrap an exact generated source-fitness report in producer-only authority."""
+
+    _require_generated_model(report, "SourceFitnessReport")
+    _match(report.workspace_id, scope.workspace_id, "source_fitness_report.workspace_id")
+    api = _studio_api()
+    return api.models.ContractProducerSourceFitnessCommand(
+        schema_version=PINNED_CONTRACT_VERSION,
+        workspace_id=scope.workspace_id,
+        run_id=scope.run_id,
+        attempt_id=scope.attempt_id,
+        producer_generation=scope.producer_generation,
+        producer_fence=scope.producer_fence,
+        authority="producer_attempt_evidence",
+        payload_digest=_evidence_payload_digest(
+            "submitProducerSourceFitness",
+            studio_wire_dict(report),
+        ),
+        source_fitness_report=report,
+    )
+
+
+def map_verifier_semantic_review_submission(
+    scope: VerifierReviewScope,
+    *,
+    decision: str,
+    review_digest: str,
+) -> Any:
+    """Reject the retired semantic-review ingress under the model-free V3 boundary."""
+
+    del scope, decision, review_digest
+    raise StudioBoundaryValidationError(
+        "semantic-review submission is retired from the model-free V3 verifier boundary"
+    )
+
+
+def map_verifier_finding_submission(
+    scope: VerifierReviewScope,
+    *,
+    check_id: str,
+    code: str,
+    severity: str,
+    summary: str,
+    evidence_digest: str,
+    finding_source: str,
+    evaluator_finding_id: str | None = None,
+    category: str | None = None,
+    affected_artifact: Mapping[str, Any] | None = None,
+    acceptance_conditions: Sequence[str] | None = None,
+) -> Any:
+    """Submit finding content while Studio derives status, scope, identity, and closure."""
+
+    if check_id not in scope.required_check_ids:
+        raise StudioBoundaryValidationError(
+            "finding check_id is outside the verifier required-check inventory"
+        )
+    expected_code = f"REQUIRED_CHECK_FAILED_{check_id}"[:128]
+    if code != expected_code:
+        raise StudioBoundaryValidationError("finding code does not bind its check_id")
+    if not re.fullmatch(r"[A-Z][A-Z0-9_]{2,127}", code):
+        raise StudioBoundaryValidationError("finding code is not canonical")
+    _nonempty(summary, "summary", maximum=2000)
+    api = _studio_api()
+    if finding_source != "deterministic_check":
+        raise StudioBoundaryValidationError(
+            "finding_source must be deterministic_check in model-free V3"
+        )
+    if evaluator_finding_id is not None:
+        raise StudioBoundaryValidationError(
+            "evaluator_finding_id is retired from the model-free V3 finding boundary"
+        )
+    proposal_fields: dict[str, Any] = {
+        "schema_version": PINNED_CONTRACT_VERSION,
+        "finding_source": "deterministic_check",
+        "check_id": check_id,
+        "code": code,
+        "severity": _generated_enum(
+            api.models.ContractSeverity,
+            severity,
+            "severity",
+        ),
+        "summary": summary,
+        "evidence_digest": _wire_digest(evidence_digest, "evidence_digest"),
+    }
+    if category is not None:
+        proposal_fields["category"] = _generated_enum(
+            api.models.ContractCategory,
+            category,
+            "category",
+        )
+    if affected_artifact is not None:
+        if not isinstance(affected_artifact, Mapping) or set(affected_artifact) != {
+            "artifact_id",
+            "kind",
+            "content_digest",
+        }:
+            raise StudioBoundaryValidationError("affected_artifact fields are not exact")
+        try:
+            artifact_id = UUID(str(affected_artifact["artifact_id"]))
+        except (TypeError, ValueError) as error:
+            raise StudioBoundaryValidationError(
+                "affected_artifact.artifact_id is not a UUID"
+            ) from error
+        kind = affected_artifact["kind"]
+        _nonempty(
+            kind,
+            "affected_artifact.kind",
+            maximum=64,
+        )
+        if not re.fullmatch(r"[a-z][a-z0-9_]{1,63}", kind):
+            raise StudioBoundaryValidationError("affected_artifact.kind is not canonical")
+        proposal_fields["affected_artifact"] = api.models.ContractAffectedArtifact(
+            artifact_id=artifact_id,
+            kind=kind,
+            content_digest=_wire_digest(
+                affected_artifact["content_digest"],
+                "affected_artifact.content_digest",
+            ),
+        )
+    if acceptance_conditions is not None:
+        conditions = list(acceptance_conditions)
+        if not conditions or len(conditions) > 32 or len(conditions) != len(set(conditions)):
+            raise StudioBoundaryValidationError(
+                "acceptance_conditions must be a nonempty unique bounded list"
+            )
+        for index, condition in enumerate(conditions):
+            _nonempty(condition, f"acceptance_conditions[{index}]", maximum=1000)
+        proposal_fields["acceptance_conditions"] = conditions
+    proposal = api.models.ContractFindingProposal(**proposal_fields)
+    return api.models.ContractVerifierFindingCommand(
+        schema_version=PINNED_CONTRACT_VERSION,
+        workspace_id=scope.workspace_id,
+        run_id=scope.run_id,
+        attempt_id=scope.attempt_id,
+        verification_generation=scope.verification_generation,
+        verifier_generation=scope.verifier_generation,
+        verifier_fence=scope.verifier_fence,
+        authority="independent_verifier_review",
+        payload_digest=_evidence_payload_digest(
+            "submitVerifierFinding",
+            studio_wire_dict(proposal),
+        ),
+        finding_proposal=proposal,
+    )
+
+
+def parse_verifier_job_scope(value: Mapping[str, Any]) -> VerifierReviewScope:
+    """Discover the complete immutable report scope from the canonical verifier job."""
+
+    model = _strict_generated_parse("ContractVerifierRuntimeJob", value)
+    wire = studio_wire_dict(model)
+    return VerifierReviewScope(
+        workspace_id=model.workspace_id,
+        run_id=model.run_id,
+        gate_lineage_id=model.gate_lineage_id,
+        attempt_id=model.attempt_id,
+        verification_generation=model.verification_generation,
+        verifier_generation=model.verifier_generation,
+        verifier_fence=model.verifier_fence,
+        admission_id=model.admission_id,
+        selection_epoch=model.selection_epoch,
+        candidate_digest=model.candidate_digest,
+        candidate_contract_version=model.candidate_contract_version,
+        dataset_id=model.dataset_id,
+        table_id=model.table_id,
+        table_recipe_id=model.table_recipe_id,
+        recipe_version=model.recipe_version,
+        recipe_digest=model.recipe_digest,
+        activation_epoch=model.activation_epoch,
+        execution_scope_digest=model.execution_scope_digest,
+        validation_policy_digest=model.validation_policy_digest,
+        release_policy_digest=model.release_policy_digest,
+        artifact_scope_digest=model.artifact_scope_digest,
+        verifier_principal_id=model.verifier_principal_id,
+        verifier_image_digest=model.verifier_image_digest,
+        required_check_ids=tuple(model.required_check_ids),
+        attestation_scheme=wire["attestation_scheme"],
+        attestation_key_id=model.attestation_key_id,
+        attestation_key_version=model.attestation_key_version,
+    )
+
+
+def map_verifier_download_command(
+    scope: VerifierReviewScope,
+    *,
+    artifact_id: UUID,
+    expected_content_digest: str,
+) -> Any:
+    """Request a download; Studio resolves and stamps immutable object generation."""
+
+    if not isinstance(artifact_id, UUID):
+        raise StudioBoundaryValidationError("artifact_id must be a UUID")
+    api = _studio_api()
+    return api.models.ContractVerifierDownloadCommand(
+        schema_version=PINNED_CONTRACT_VERSION,
+        workspace_id=scope.workspace_id,
+        run_id=scope.run_id,
+        attempt_id=scope.attempt_id,
+        verification_generation=scope.verification_generation,
+        verifier_generation=scope.verifier_generation,
+        fence=scope.verifier_fence,
+        artifact_id=artifact_id,
+        expected_content_digest=_wire_digest(
+            expected_content_digest,
+            "expected_content_digest",
+        ),
+    )
+
+
+def parse_verifier_signed_session(
+    value: Mapping[str, Any],
+    scope: VerifierReviewScope,
+    *,
+    artifact_id: UUID,
+    expected_content_digest: str,
+    expected_kind: str,
+    expected_media_type: str,
+    expected_contract_version: str,
+    expected_classification: str,
+    expected_size_bytes: int,
+) -> Any:
+    """Parse a signed session and reject any stale verification or retry scope."""
+
+    model = _strict_generated_parse("ContractVerifierSignedSession", value)
+    _match_verifier_scope(
+        model,
+        scope,
+        fence_name="fence",
+        attempt_name="attempt_id",
+    )
+    wire = studio_wire_dict(model)
+    if (
+        wire["direction"] != "download"
+        or wire["method"] != "GET"
+        or wire["purpose"] != "verifier_selected_artifact_download"
+        or wire["route_authority"] != "verifier_attempt"
+    ):
+        raise StudioBoundaryValidationError("verifier signed session is not download-only")
+    if not re.fullmatch(r"[1-9][0-9]{0,31}", wire["object_generation"]):
+        raise StudioBoundaryValidationError(
+            "verifier signed session object_generation is not canonical"
+        )
+    expected = {
+        "artifact_id": str(artifact_id),
+        "expected_content_digest": expected_content_digest,
+        "kind": expected_kind,
+        "media_type": expected_media_type,
+        "contract_version": expected_contract_version,
+        "classification": expected_classification,
+        "expected_size_bytes": expected_size_bytes,
+    }
+    for name, expected_value in expected.items():
+        _match(wire[name], expected_value, f"verifier_signed_session.{name}")
+    return model
+
+
+def parse_producer_input_signed_session(
+    value: Mapping[str, Any],
+    *,
+    workspace_id: UUID,
+    run_id: UUID,
+    attempt_id: UUID,
+    producer_generation: int,
+    producer_fence: int,
+    artifact_id: UUID,
+    media_type: str,
+    expected_size_bytes: int,
+    expected_content_digest: str,
+) -> Any:
+    """Parse one Studio-issued immutable candidate-input download session."""
+
+    required = {
+        "schema_version",
+        "session_id",
+        "reservation_id",
+        "reservation_digest",
+        "workspace_id",
+        "run_id",
+        "artifact_id",
+        "kind",
+        "purpose",
+        "classification",
+        "media_type",
+        "contract_version",
+        "object_generation",
+        "object_key_digest",
+        "direction",
+        "route_authority",
+        "method",
+        "signed_url",
+        "required_headers",
+        "expected_content_digest",
+        "expected_size_bytes",
+        "issued_at",
+        "expires_at",
+        "single_use",
+        "attempt_id",
+        "producer_generation",
+        "fence",
+    }
+    if not isinstance(value, Mapping) or set(value) != required:
+        raise StudioBoundaryValidationError(
+            "producer candidate-input signed session fields are not exact"
+        )
+    model = _strict_generated_parse("ContractProducerSignedSession", value)
+    wire = studio_wire_dict(model)
+    expected = {
+        "workspace_id": str(workspace_id),
+        "run_id": str(run_id),
+        "attempt_id": str(attempt_id),
+        "producer_generation": producer_generation,
+        "fence": producer_fence,
+        "artifact_id": str(artifact_id),
+        "kind": "candidate_input_bundle",
+        "purpose": "producer_candidate_input_download",
+        "classification": "internal",
+        "media_type": media_type,
+        "expected_size_bytes": expected_size_bytes,
+        "expected_content_digest": expected_content_digest,
+        "contract_version": PINNED_CONTRACT_VERSION,
+        "direction": "download",
+        "route_authority": "producer_attempt",
+        "method": "GET",
+        "single_use": False,
+    }
+    mismatched = [name for name, item in expected.items() if wire.get(name) != item]
+    if mismatched:
+        raise StudioBoundaryValidationError(
+            "producer candidate-input signed session differs at " + ",".join(mismatched)
+        )
+    if not re.fullmatch(r"[1-9][0-9]{0,31}", wire["object_generation"]):
+        raise StudioBoundaryValidationError(
+            "producer candidate-input object_generation is not canonical"
+        )
+    for name in (
+        "reservation_digest",
+        "object_key_digest",
+        "expected_content_digest",
+    ):
+        _wire_digest(wire[name], f"producer_candidate_input.{name}")
+    _bounded_int(
+        wire["expected_size_bytes"],
+        "producer_candidate_input.expected_size_bytes",
+        1,
+        2_147_483_648,
+    )
+    return model
+
+
+def parse_verifier_submission(
+    value: Mapping[str, Any],
+    scope: VerifierReviewScope,
+) -> Any:
+    """Parse a report command and reject a stale stable generation or retry lease."""
+
+    model = _strict_generated_parse("ContractSubmissionCommand", value)
+    _match_verifier_scope(
+        model,
+        scope,
+        fence_name="verifier_fence",
+        attempt_name="verifier_attempt_id",
+    )
+    _match_verifier_report_scope(model, scope)
+    return model
+
+
+def parse_verifier_semantic_evidence(
+    value: Mapping[str, Any],
+    scope: VerifierReviewScope,
+    *,
+    artifact_references: Sequence[Mapping[str, Any]],
+) -> Any:
+    """Reject the retired model-mediated semantic evidence surface."""
+
+    del value, scope, artifact_references
+    raise StudioBoundaryValidationError(
+        "semantic evaluation evidence is retired from the model-free V3 verifier boundary"
+    )
+
+
+def parse_source_rights_review(
+    value: Mapping[str, Any],
+    *,
+    workspace_id: UUID,
+    source_id: UUID,
+) -> Any:
+    """Parse a rights-review body and bind it to one workspace and source.
+
+    The parsed review carries the source version and the rights, evidence, policy, and review
+    coordinate digests required by a decision. This module validates only the body.
+    """
+
+    model = _strict_generated_parse("ContractRightsReview", value)
+    _match(model.workspace_id, workspace_id, "workspace_id")
+    _match(model.source_id, source_id, "source_id")
+    return model
+
+
+def map_source_rights_decision(
+    review: Any,
+    *,
+    step_up_challenge_id: UUID,
+    decision: str,
+    conditions_digest: str | None = None,
+    reason: str | None = None,
+) -> Any:
+    """Carry every canonical rights-review coordinate into a human decision."""
+
+    _require_generated_model(review, "ContractRightsReview")
+    if not isinstance(step_up_challenge_id, UUID):
+        raise StudioBoundaryValidationError("step_up_challenge_id must be a UUID")
+    api = _studio_api()
+    if conditions_digest is not None:
+        _wire_digest(conditions_digest, "conditions_digest")
+    if reason is not None:
+        _nonempty(reason, "reason", maximum=4000)
+    return api.models.ContractRightsDecisionCommand(
+        schema_version=PINNED_CONTRACT_VERSION,
+        workspace_id=review.workspace_id,
+        source_id=review.source_id,
+        rights_claim_digest=review.rights_claim_digest,
+        rights_evidence_digest=review.rights_evidence_digest,
+        rights_policy_digest=review.rights_policy_digest,
+        rights_review_coordinate_digest=review.rights_review_coordinate_digest,
+        decision=_generated_enum(
+            api.models.ContractRightsDecisionCommandDecision,
+            decision,
+            "decision",
+        ),
+        expected_source_version=review.source_version,
+        step_up_challenge_id=step_up_challenge_id,
+        conditions_digest=(api.unset if conditions_digest is None else conditions_digest),
+        reason=api.unset if reason is None else reason,
+    )
+
+
+def validate_source_rights_decision_scope(command: Any, current_review: Any) -> None:
+    """Fail closed when a decision no longer matches the current rights review.
+
+    Compares the command's workspace, source, rights claim/evidence/policy digests, review
+    coordinate digest, and expected_source_version against a freshly parsed review.  One
+    difference means the review moved after the decision was built, so the decision is stale.
+    """
+
+    _require_generated_model(command, "ContractRightsDecisionCommand")
+    _require_generated_model(current_review, "ContractRightsReview")
+    bindings = (
+        ("workspace_id", "workspace_id"),
+        ("source_id", "source_id"),
+        ("rights_claim_digest", "rights_claim_digest"),
+        ("rights_evidence_digest", "rights_evidence_digest"),
+        ("rights_policy_digest", "rights_policy_digest"),
+        ("rights_review_coordinate_digest", "rights_review_coordinate_digest"),
+        ("expected_source_version", "source_version"),
+    )
+    for command_name, review_name in bindings:
+        _match(
+            getattr(command, command_name),
+            getattr(current_review, review_name),
+            command_name,
+        )
+
+
+def parse_run_event(value: Mapping[str, Any], fence: HostedFence) -> Any:
+    model = _strict_generated_parse("DurableRunEvent", value)
+    _match(model.workspace_id, fence.workspace_id, "workspace_id")
+    _match(model.run_id, fence.run_id, "run_id")
+    _match_optional_attempt(model, fence)
+    _bounded_int(model.sequence, "sequence", 1, (1 << 63) - 1)
+    if not re.fullmatch(r"[A-Za-z0-9_-]+", model.cursor):
+        raise StudioBoundaryValidationError("cursor is not a canonical opaque cursor")
+    return model
+
+
+def parse_artifact(value: Mapping[str, Any], fence: HostedFence) -> Any:
+    if fence.attempt_id is None:
+        raise StudioBoundaryValidationError("artifact parsing requires an attempt fence")
+    model = _strict_generated_parse("ImmutableArtifactMetadata", value)
+    _match(model.workspace_id, fence.workspace_id, "workspace_id")
+    _match(model.run_id, fence.run_id, "run_id")
+    _match(model.attempt_id, fence.attempt_id, "attempt_id")
+    _bounded_int(model.size_bytes, "size_bytes", 0, (1 << 63) - 1)
+    wire = studio_wire_dict(model)
+    _semver(wire["contract_version"], "contract_version")
+    if not re.fullmatch(r"[a-z0-9.+-]+/[a-z0-9.+-]+", wire["media_type"]):
+        raise StudioBoundaryValidationError("media_type is not canonical")
+    if wire["storage_state"] == "sealed" and "sealed_at" not in wire:
+        raise StudioBoundaryValidationError("sealed artifact lacks sealed_at")
+    return model
+
+
+def parse_candidate_admission(value: Mapping[str, Any], fence: HostedFence) -> Any:
+    required = {
+        "attempt_id": fence.attempt_id,
+        "gate_lineage_id": fence.gate_lineage_id,
+        "producer_generation": fence.producer_generation,
+        "producer_fence": fence.producer_fence,
+    }
+    missing = sorted(name for name, item in required.items() if item is None)
+    if missing:
+        raise StudioBoundaryValidationError(
+            f"candidate admission parsing requires explicit fences: {missing}"
+        )
+    model = _strict_generated_parse("CandidateAdmissionAndStudioSelection", value)
+    _match(model.workspace_id, fence.workspace_id, "workspace_id")
+    _match(model.run_id, fence.run_id, "run_id")
+    _match(model.gate_lineage_id, fence.gate_lineage_id, "gate_lineage_id")
+    _match(model.producer_attempt_id, fence.attempt_id, "producer_attempt_id")
+    _match(model.producer_generation, fence.producer_generation, "producer_generation")
+    _match(model.producer_fence, fence.producer_fence, "producer_fence")
+    wire = studio_wire_dict(model)
+    _semver(wire["candidate_contract_version"], "candidate_contract_version")
+    if "selection_epoch" in wire:
+        _bounded_int(wire["selection_epoch"], "selection_epoch", 1, (1 << 63) - 1)
+    status_requirements = {
+        "selected": {"selection_epoch", "selected_at", "selection_actor"},
+        "superseded": {"selection_epoch", "superseded_by_admission_id"},
+        "revoked": {"selection_epoch", "revoked_at", "revocation_reason"},
+    }
+    absent = sorted(status_requirements.get(wire["status"], set()) - set(wire))
+    if absent:
+        raise StudioBoundaryValidationError(
+            f"{wire['status']} admission lacks conditional fields: {absent}"
+        )
+    if not wire["artifact_references"]:
+        raise StudioBoundaryValidationError("candidate admission requires artifact references")
+    references = [
+        (
+            item["workspace_id"],
+            item["artifact_id"],
+            item["contract_version"],
+            item["content_digest"],
+        )
+        for item in wire["artifact_references"]
+    ]
+    if len(references) != len(set(references)):
+        raise StudioBoundaryValidationError("candidate admission has duplicate artifact references")
+    for index, item in enumerate(wire["artifact_references"]):
+        if item["workspace_id"] != str(fence.workspace_id):
+            raise StudioBoundaryValidationError(
+                f"artifact_references[{index}].workspace_id fence mismatch"
+            )
+        _semver(item["contract_version"], f"artifact_references[{index}].contract_version")
+    return model
+
+
+def parse_finding(value: Mapping[str, Any], fence: HostedFence) -> Any:
+    if fence.gate_lineage_id is None:
+        raise StudioBoundaryValidationError("finding parsing requires gate_lineage_id")
+    model = _strict_generated_parse("RecipeBoundDeterministicFinding", value)
+    _match(model.workspace_id, fence.workspace_id, "workspace_id")
+    _match(model.run_id, fence.run_id, "run_id")
+    _match(model.gate_lineage_id, fence.gate_lineage_id, "gate_lineage_id")
+    wire = studio_wire_dict(model)
+    if not re.fullmatch(r"[A-Z][A-Z0-9_]{2,127}", wire["code"]):
+        raise StudioBoundaryValidationError("finding code is not canonical")
+    if type(wire["blocks_release"]) is not bool:
+        raise StudioBoundaryValidationError("blocks_release must be a boolean")
+    if wire["status"] == "closed":
+        required = {"closed_at", "closure_review_id", "closure_evidence_digest"}
+        absent = sorted(required - set(wire))
+        if absent or wire["blocks_release"]:
+            raise StudioBoundaryValidationError("closed finding violates closure invariants")
+    if wire["severity"] in {"blocker", "critical", "high"} and wire["status"] in {
+        "open",
+        "repair_in_progress",
+        "closure_review_pending",
+    }:
+        if not wire["blocks_release"]:
+            raise StudioBoundaryValidationError(
+                "unresolved high-severity finding must block release"
+            )
+    return model
+
+
+def studio_wire_dict(model: Any) -> dict[str, Any]:
+    """Serialize only a generated model and normalize its UTC lexical wire form."""
+
+    to_dict = getattr(model, "to_dict", None)
+    if not callable(to_dict) or not type(model).__module__.startswith("mostlyright_studio.models."):
+        raise StudioBoundaryValidationError("value is not a generated Studio model")
+    value = _wire_value(to_dict(), key=None)
+    if not isinstance(value, dict):
+        raise StudioBoundaryValidationError("generated Studio model did not serialize to an object")
+    # The root path is the only marker _assert_wire_scalars has for the two crawl-session
+    # exceptions: a session's request_digest is a bare hex digest, and its source_id names a
+    # source inside the frozen recipe rather than a Studio row.
+    model_name = type(model).__name__
+    path = (
+        "$.public_crawl"
+        if model_name in {"PublicCrawlSession", "HostedPublicHTTPSAcquisitionSession"}
+        else (
+            "$.source_cadence"
+            if model_name in {"ContractProducerAppendContext", "ContractInferenceRecord"}
+            else "$"
+        )
+    )
+    _assert_wire_scalars(value, path)
+    return value
+
+
+def _evidence_payload_digest(operation: str, payload: Mapping[str, Any]) -> str:
+    """Derive the Studio evidence digest; callers cannot supply an outer digest."""
+
+    operations = {
+        "submitProducerAgentCallEvidence",
+        "submitProducerSourceObservation",
+        "submitProducerSourceFitness",
+        "submitVerifierSemanticReview",
+        "submitVerifierFinding",
+    }
+    if operation not in operations:
+        raise StudioBoundaryValidationError(f"unsupported evidence-ingress operation {operation!r}")
+    _assert_wire_scalars(payload, "$.payload")
+    preimage = {
+        "domain": "mostlyright.studio.evidence-ingress",
+        "version": "1",
+        "type": operation,
+        "payload": dict(payload),
+    }
+    encoded = json.dumps(
+        preimage,
+        ensure_ascii=False,
+        allow_nan=False,
+        separators=(",", ":"),
+        sort_keys=True,
+    ).encode("utf-8")
+    return f"sha256:{hashlib.sha256(encoded).hexdigest()}"
+
+
+def _strict_generated_parse(
+    model_name: str,
+    value: Mapping[str, Any],
+    *,
+    expected_schema_version: str = PINNED_CONTRACT_VERSION,
+) -> Any:
+    if not isinstance(value, Mapping) or not all(isinstance(key, str) for key in value):
+        raise StudioBoundaryValidationError(
+            f"{model_name} wire value must be a string-keyed object"
+        )
+    api = _studio_api()
+    model_type = getattr(api.models, model_name, None)
+    if model_type is None:
+        raise StudioClientIncompatibleError(f"generated model {model_name!r} is unavailable")
+    original = dict(value)
+    try:
+        model = model_type.from_dict(original)
+        serialized = studio_wire_dict(model)
+    except (KeyError, TypeError, ValueError, AttributeError) as exc:
+        raise StudioBoundaryValidationError(
+            f"{model_name} failed generated-model parsing: {exc}"
+        ) from exc
+    if serialized != original:
+        raise StudioBoundaryValidationError(
+            f"{model_name} contains unknown, missing, lossy, or noncanonical wire values"
+        )
+    if serialized.get("schema_version") != expected_schema_version:
+        raise StudioBoundaryValidationError(f"{model_name} has an unsupported schema_version")
+    return model
+
+
+def _require_generated_model(value: Any, model_name: str) -> None:
+    api = _studio_api()
+    model_type = getattr(api.models, model_name, None)
+    if model_type is None:
+        raise StudioClientIncompatibleError(f"generated model {model_name!r} is unavailable")
+    if type(value) is not model_type:
+        raise StudioBoundaryValidationError(f"value must be the exact generated {model_name} model")
+    studio_wire_dict(value)
+
+
+def _match_verifier_scope(
+    model: Any,
+    scope: VerifierReviewScope,
+    *,
+    fence_name: str,
+    attempt_name: str,
+) -> None:
+    _match(model.workspace_id, scope.workspace_id, "workspace_id")
+    _match(model.run_id, scope.run_id, "run_id")
+    _match(getattr(model, attempt_name), scope.attempt_id, attempt_name)
+    _match(
+        model.verification_generation,
+        scope.verification_generation,
+        "verification_generation",
+    )
+    _match(model.verifier_generation, scope.verifier_generation, "verifier_generation")
+    _match(getattr(model, fence_name), scope.verifier_fence, fence_name)
+
+
+def _match_verifier_report_scope(model: Any, scope: VerifierReviewScope) -> None:
+    """Reject a report that differs from any server-issued immutable coordinate."""
+
+    wire = studio_wire_dict(model)
+    for name in (
+        "gate_lineage_id",
+        "admission_id",
+        "selection_epoch",
+        "candidate_digest",
+        "candidate_contract_version",
+        "dataset_id",
+        "table_id",
+        "table_recipe_id",
+        "recipe_version",
+        "recipe_digest",
+        "activation_epoch",
+        "execution_scope_digest",
+        "validation_policy_digest",
+        "release_policy_digest",
+        "artifact_scope_digest",
+        "verifier_principal_id",
+        "verifier_image_digest",
+    ):
+        _match(getattr(model, name), getattr(scope, name), name)
+    _match(
+        tuple(model.required_check_ids),
+        scope.required_check_ids,
+        "required_check_ids",
+    )
+    if scope.resulting_source_states is None:
+        raise StudioBoundaryValidationError(
+            "report parsing requires candidate-bound resulting source states"
+        )
+    _match(
+        tuple(wire["resulting_source_states"]),
+        scope.resulting_source_states,
+        "resulting_source_states",
+    )
+    _match(
+        model.resulting_source_states_digest,
+        scope.resulting_source_states_digest,
+        "resulting_source_states_digest",
+    )
+    attestation = wire["attestation"]
+    _match(attestation["scheme"], scope.attestation_scheme, "attestation.scheme")
+    _match(attestation["key_id"], scope.attestation_key_id, "attestation.key_id")
+    _match(
+        attestation["key_version"],
+        scope.attestation_key_version,
+        "attestation.key_version",
+    )
+
+
+def _mapped(model: Any, local: Any, workspace_id: UUID) -> MappedStudioValue:
+    api = _studio_api()
+    return MappedStudioValue(
+        model=model,
+        evidence=BoundaryMappingEvidence(
+            contract=api.identity,
+            model_name=type(model).__name__,
+            local_schema_version=local.schema_version,
+            local_digest=local.digest,
+            workspace_id=workspace_id,
+        ),
+    )
+
+
+def _wire_value(value: Any, *, key: str | None) -> Any:
+    if isinstance(value, dict):
+        return {item_key: _wire_value(item, key=item_key) for item_key, item in value.items()}
+    if isinstance(value, list):
+        return [_wire_value(item, key=key) for item in value]
+    if isinstance(value, str) and key in _TIMESTAMP_FIELDS and value.endswith("+00:00"):
+        return f"{value[:-6]}Z"
+    return value
+
+
+def _assert_wire_scalars(value: Any, path: str = "$") -> None:
+    if isinstance(value, dict):
+        for key, item in value.items():
+            item_path = f"{path}.{key}"
+            if item is None:
+                continue
+            if key in _TIMESTAMP_FIELDS:
+                _parse_utc(item, item_path)
+            if key in {"image_digest", "verifier_image_digest"}:
+                if not _IMAGE_DIGEST.fullmatch(item):
+                    raise StudioBoundaryValidationError(f"{item_path} is not canonical")
+            elif (
+                key in _BARE_DIGEST_FIELDS
+                or (key == "request_digest" and "public_crawl" in path)
+                or (key == "cadence_probe_receipt_digest" and "public_crawl" in path)
+                or (key.endswith("digest") and "cadence_authority" in path)
+                or (key.endswith("digest") and "source_cadence" in path)
+                # Everything under reviewed_build is the Harness's own frozen-recipe
+                # evidence; dataset-recipe.schema.json pins those digests as bare
+                # lowercase hex "intentionally unprefixed to match the Harness contract".
+                or (key.endswith("digest") and "reviewed_build" in path)
+            ):
+                _bare_digest(item, item_path)
+            elif key.endswith("digest"):
+                _wire_digest(item, item_path)
+            # Under these subtrees source_id is a frozen-recipe source name, not a Studio
+            # source row, so the canonical-UUID check below must not apply to it.
+            harness_source_id = key == "source_id" and any(
+                marker in path
+                for marker in (
+                    "committed_source_states",
+                    "resulting_source_states",
+                    "source_authority_bindings",
+                    "public_crawl",
+                    "source_cadence",
+                    "reviewed_build",
+                )
+            )
+            if key in _UUID_FIELDS and not harness_source_id:
+                try:
+                    parsed = UUID(item)
+                except (TypeError, ValueError, AttributeError) as exc:
+                    raise StudioBoundaryValidationError(
+                        f"{item_path} must be a canonical UUID"
+                    ) from exc
+                if str(parsed) != item:
+                    raise StudioBoundaryValidationError(
+                        f"{item_path} must be a canonical lowercase UUID"
+                    )
+            _assert_wire_scalars(item, item_path)
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            _assert_wire_scalars(item, f"{path}[{index}]")
+    elif value is None or type(value) in {str, int, bool}:
+        return
+    else:
+        raise StudioBoundaryValidationError(f"{path} is not a strict JSON value")
+
+
+def _wire_digest(value: str, path: str, *, allow_raw: bool = False) -> str:
+    if allow_raw and re.fullmatch(r"[0-9a-f]{64}", value):
+        value = f"sha256:{value}"
+    if not isinstance(value, str) or not _DIGEST.fullmatch(value):
+        raise StudioBoundaryValidationError(f"{path} must be a sha256:<lowercase hex> digest")
+    return value
+
+
+def _bare_digest(value: str, path: str) -> str:
+    if not isinstance(value, str) or not re.fullmatch(r"[0-9a-f]{64}", value):
+        raise StudioBoundaryValidationError(f"{path} must be a bare sha256 lowercase hex digest")
+    return value
+
+
+def _parse_utc(value: str, path: str) -> datetime:
+    if not isinstance(value, str) or not _UTC.fullmatch(value):
+        raise StudioBoundaryValidationError(f"{path} must be a canonical UTC timestamp ending in Z")
+    try:
+        parsed = datetime.fromisoformat(value[:-1] + "+00:00")
+    except ValueError as exc:
+        raise StudioBoundaryValidationError(f"{path} is not a calendar-valid timestamp") from exc
+    if parsed.tzinfo != UTC:
+        raise StudioBoundaryValidationError(f"{path} must be UTC")
+    return parsed
+
+
+def _semver(value: str, path: str) -> str:
+    if not isinstance(value, str) or not _SEMVER.fullmatch(value):
+        raise StudioBoundaryValidationError(f"{path} must be a nonzero-major semantic version")
+    return value
+
+
+def _generated_enum(enum_type: Any, value: str, path: str) -> Any:
+    try:
+        return enum_type(value)
+    except (TypeError, ValueError) as exc:
+        raise StudioBoundaryValidationError(
+            f"{path} is not supported by the pinned generated Studio client: {value!r}"
+        ) from exc
+
+
+def _nonempty(value: str, path: str, *, maximum: int) -> None:
+    if not isinstance(value, str) or not value or len(value) > maximum:
+        raise StudioBoundaryValidationError(f"{path} must be 1..{maximum} characters")
+
+
+def _bounded_int(value: int, path: str, minimum: int, maximum: int) -> None:
+    if type(value) is not int or not minimum <= value <= maximum:
+        raise StudioBoundaryValidationError(
+            f"{path} must be an integer from {minimum} through {maximum}"
+        )
+
+
+def _uuids(value: Any) -> None:
+    """Require UUID instances for the attributes named in _UUID_FIELDS.
+
+    Attributes outside that allowlist are not inspected, so a UUID-annotated field whose name is
+    absent from _UUID_FIELDS goes unchecked here.
+    """
+
+    for name, item in vars(value).items():
+        if name in _UUID_FIELDS and item is not None and not isinstance(item, UUID):
+            raise StudioBoundaryValidationError(f"{name} must be a UUID")
+
+
+def _match(actual: Any, expected: Any, path: str) -> None:
+    """Require an exact match against the server-issued value named by path.
+
+    Callers use it for fences, digests, identities, and policy coordinates alike.  The raised
+    message says fence mismatch in every case, so path is what names the value that differed.
+    """
+
+    if actual != expected:
+        raise StudioBoundaryValidationError(
+            f"{path} fence mismatch: expected {expected!s}, got {actual!s}"
+        )
+
+
+def _match_optional_attempt(model: Any, fence: HostedFence) -> None:
+    api = _studio_api()
+    actual = model.attempt_id
+    if isinstance(actual, type(api.unset)):
+        if fence.attempt_id is not None:
+            raise StudioBoundaryValidationError("attempt_id fence expected but event omitted it")
+    elif fence.attempt_id is None:
+        raise StudioBoundaryValidationError("event carries attempt_id without an explicit fence")
+    else:
+        _match(actual, fence.attempt_id, "attempt_id")
+
+
+__all__ = [
+    "PINNED_CONTRACT_SET",
+    "PINNED_CONTRACT_VERSION",
+    "PINNED_GENERATOR",
+    "PINNED_GENERATOR_VERSION",
+    "PINNED_OPENAPI_SOURCE_SHA256",
+    "AgentCallIdentity",
+    "BoundaryMappingEvidence",
+    "HostedFence",
+    "MappedStudioValue",
+    "OpaqueSecretBinding",
+    "PlanIdentity",
+    "ProducerEvidenceScope",
+    "QuestionIdentity",
+    "RequirementsIdentity",
+    "SourceIdentity",
+    "StudioBoundaryError",
+    "StudioBoundaryValidationError",
+    "StudioClientIncompatibleError",
+    "StudioClientUnavailableError",
+    "StudioContractIdentity",
+    "VerifierReviewScope",
+    "client_contract_identity",
+    "ensure_studio_client",
+    "map_agent_call_evidence",
+    "map_plan",
+    "map_producer_agent_call_submission",
+    "map_producer_source_fitness_submission",
+    "map_producer_source_observation_submission",
+    "map_question",
+    "map_requirements",
+    "map_source_proposal",
+    "map_source_rights_decision",
+    "map_verifier_download_command",
+    "map_verifier_finding_submission",
+    "map_verifier_semantic_review_submission",
+    "parse_artifact",
+    "parse_candidate_admission",
+    "parse_finding",
+    "parse_producer_input_signed_session",
+    "parse_run_event",
+    "parse_source_rights_review",
+    "parse_verifier_job_scope",
+    "parse_verifier_semantic_evidence",
+    "parse_verifier_signed_session",
+    "parse_verifier_submission",
+    "studio_wire_dict",
+    "validate_source_rights_decision_scope",
+]