synth-ai 0.18.0.dev590__tar.gz → 0.18.1.dev595__tar.gz

{synth_ai-0.18.0.dev590/synth_ai.egg-info → synth_ai-0.18.1.dev595}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: synth-ai
-Version: 0.18.0.dev590
+Version: 0.18.1.dev595
 Summary: Python SDK and CLI for Synth Managed Research and Research Factory
 Author-email: Synth AI <josh@usesynth.ai>
 License-Expression: MIT
@@ -27,7 +27,7 @@ Dynamic: license-file
 
 # Synth AI SDK
 
-<!-- CI release pins: PyPI-0.18.0-orange synth-ai==0.18.0 -->
+<!-- CI release pins: PyPI-0.18.1-orange synth-ai==0.18.1 -->
 
 [![PyPI version](https://img.shields.io/pypi/v/synth-ai.svg)](https://pypi.org/project/synth-ai/)
 [![License](https://img.shields.io/pypi/l/synth-ai.svg)](https://pypi.org/project/synth-ai/)

{synth_ai-0.18.0.dev590 → synth_ai-0.18.1.dev595}/README.md

@@ -1,6 +1,6 @@
 # Synth AI SDK
 
-<!-- CI release pins: PyPI-0.18.0-orange synth-ai==0.18.0 -->
+<!-- CI release pins: PyPI-0.18.1-orange synth-ai==0.18.1 -->
 
 [![PyPI version](https://img.shields.io/pypi/v/synth-ai.svg)](https://pypi.org/project/synth-ai/)
 [![License](https://img.shields.io/pypi/l/synth-ai.svg)](https://pypi.org/project/synth-ai/)

{synth_ai-0.18.0.dev590 → synth_ai-0.18.1.dev595}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "synth-ai"
-version = "0.18.0.dev590"
+version = "0.18.1.dev595"
 description = "Python SDK and CLI for Synth Managed Research and Research Factory"
 authors = [{name = "Synth AI", email = "josh@usesynth.ai"}]
 license = "MIT"

{synth_ai-0.18.0.dev590 → synth_ai-0.18.1.dev595}/synth_ai/sdk/research/contracts/__init__.py

@@ -177,7 +177,15 @@ from synth_ai.sdk.research.contracts.factory_role_receipts import (
     FactoryRoleReceiptResponse,
     FactoryRoleReceiptRuntimeEvidence,
 )
+from synth_ai.sdk.research.contracts.failure import (
+    ActorFailureReason,
+    ManagedResearchFailureClassification,
+    ManagedResearchFailureFamily,
+    ManagedResearchFailureScope,
+    ManagedResearchFailureSeverity,
+)
 from synth_ai.sdk.research.contracts.image_releases import (
+    ActorImageCapability,
     ActorRuntimeImageMaterialization,
     ActorRuntimeImageRelease,
     ActorRuntimeImageReleaseArchive,
@@ -475,6 +483,7 @@ def __getattr__(name: str) -> object:
 
 
 __all__ = [
+    "ActorFailureReason",
     "DataBindingCreateRequest",
     "DataBindingResponse",
     "DatasetRevisionContent",
@@ -512,6 +521,10 @@ __all__ = [
     "MagiDecisionReceiptResponse",
     "MagiDecisionRequest",
     "MagiMode",
+    "ManagedResearchFailureClassification",
+    "ManagedResearchFailureFamily",
+    "ManagedResearchFailureScope",
+    "ManagedResearchFailureSeverity",
     "ActivityActor",
     "ActivityActorState",
     "ActivityCursor",
@@ -530,6 +543,7 @@ __all__ = [
     "ActiveActorModel",
     "ActorHarness",
     "ActorImageBinding",
+    "ActorImageCapability",
     "ActorModel",
     "ActorModelAssignment",
     "ActorSubtype",

{synth_ai-0.18.0.dev590 → synth_ai-0.18.1.dev595}/synth_ai/sdk/research/contracts/actor_images.py

@@ -11,6 +11,7 @@ from __future__ import annotations
 from collections.abc import Mapping
 from dataclasses import dataclass
 from typing import TypeAlias
+from uuid import UUID
 
 ACTOR_IMAGE_ROLES: tuple[str, ...] = (
     "orchestrator",
@@ -28,14 +29,21 @@ class ActorImageBinding:
     notes: str | None = None
 
     def __post_init__(self) -> None:
-        if not isinstance(self.release_id, str) or not self.release_id.strip():
-            raise ValueError("ActorImageBinding.release_id must be a nonempty string")
+        if not isinstance(self.release_id, str):
+            raise ValueError("ActorImageBinding.release_id must be a UUID string")
+        try:
+            release_id = str(UUID(self.release_id.strip()))
+        except (AttributeError, ValueError) as exc:
+            raise ValueError("ActorImageBinding.release_id must be a UUID string") from exc
+        object.__setattr__(self, "release_id", release_id)
         for field_name in ("reason", "notes"):
             value = getattr(self, field_name)
             if value is not None and (not isinstance(value, str) or not value.strip()):
                 raise ValueError(
                     f"ActorImageBinding.{field_name} must be a nonempty string when set"
                 )
+            if value is not None:
+                object.__setattr__(self, field_name, value.strip())
 
     def to_wire(self) -> dict[str, object]:
         payload: dict[str, object] = {"release_id": self.release_id.strip()}
@@ -60,10 +68,14 @@ class ActorImageBinding:
                 raise ValueError("actor image binding release_id must be a string")
             reason = payload.get("reason")
             notes = payload.get("notes")
+            if reason is not None and not isinstance(reason, str):
+                raise ValueError("actor image binding reason must be a string when set")
+            if notes is not None and not isinstance(notes, str):
+                raise ValueError("actor image binding notes must be a string when set")
             return cls(
                 release_id=release_id,
-                reason=reason if isinstance(reason, str) or reason is None else None,
-                notes=notes if isinstance(notes, str) or notes is None else None,
+                reason=reason,
+                notes=notes,
             )
         raise ValueError(
             "actor image binding must be an ActorImageBinding, release id string, or mapping"
@@ -83,10 +95,14 @@ def actor_image_overrides_payload(
         raise ValueError("actor_image_overrides must map actor roles to bindings")
     payload: dict[str, dict[str, object]] = {}
     for raw_role, raw_binding in overrides.items():
-        role = str(raw_role or "").strip().lower()
+        if not isinstance(raw_role, str):
+            raise ValueError("actor_image_overrides roles must be strings")
+        role = raw_role.strip().lower()
         if role not in ACTOR_IMAGE_ROLES:
             allowed = ", ".join(ACTOR_IMAGE_ROLES)
             raise ValueError(f"actor_image_overrides role must be one of: {allowed}")
+        if role in payload:
+            raise ValueError(f"actor_image_overrides repeats role: {role}")
         payload[role] = ActorImageBinding.from_wire(raw_binding).to_wire()
     return payload or None
 

{synth_ai-0.18.0.dev590 → synth_ai-0.18.1.dev595}/synth_ai/sdk/research/contracts/factories.py

@@ -550,7 +550,6 @@ class FactorySpec:
             "name": self.name,
             "kind": self.kind.value,
             "status": self.state.value,
-            "result_authority_generation": self.result_authority_generation.value,
             "budget_policy": self.budget.to_wire() if self.budget is not None else {},
             "cap_policy": self.capacity.to_wire() if self.capacity is not None else {},
             "homeostasis_policy": {},
@@ -558,6 +557,11 @@ class FactorySpec:
             "authorization_policy": {},
             "metadata": dict(self.metadata),
         }
+        # Older production control planes predate this opt-in field and reject
+        # unknown keys.  Legacy is the backend default, so only transmit an
+        # explicit non-legacy authority choice.
+        if self.result_authority_generation is not FactoryResultAuthorityGeneration.LEGACY:
+            value["result_authority_generation"] = self.result_authority_generation.value
         if self.description is not None:
             value["description"] = self.description
         return value

synth_ai-0.18.1.dev595/synth_ai/sdk/research/contracts/failure.py

@@ -0,0 +1,173 @@
+"""Public Managed Research failure vocabulary and wire contract."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class ActorFailureReason(StrEnum):
+    ACTOR_STARTUP_RETRY_BUDGET_EXHAUSTED = "actor_startup_retry_budget_exhausted"
+    TASK_BLOCKED = "task_blocked"
+    TASK_FAILED = "task_failed"
+    RUN_FAILED = "run_failed"
+    ORCHESTRATOR_SESSION_START_FAILED = "orchestrator_session_start_failed"
+    ORCHESTRATOR_SESSION_FAILED = "orchestrator_session_failed"
+    TASK_CLAIM_MATERIALIZATION_FAILED = "task_claim_materialization_failed"
+    CLAIMED_ACTOR_MISSING_TASK_BINDING = "claimed_actor_missing_task_binding"
+    WORKER_HOST_CLAIMED_NON_TASK_ACTOR = "worker_host_claimed_non_task_actor"
+    WORKER_HOST_ACTOR_RUN_MISSING = "worker_host_actor_run_missing"
+    WORKER_HOST_CLAIMED_ACTOR_TASK_MISSING = "worker_host_claimed_actor_task_missing"
+    TASK_ALREADY_TERMINAL = "task_already_terminal"
+    DB_POOL_PRESSURE = "db_pool_pressure"
+    CONTROL_PLANE_PRESSURE = "control_plane_pressure"
+    PARTICIPANT_START_BACKPRESSURE = "participant_start_backpressure"
+    PARTICIPANT_SYNC_DEFERRED_UNCONSUMED = "participant_sync_deferred_unconsumed"
+    TERMINAL_TRANSITION_DEFERRED_UNCONSUMED = "terminal_transition_deferred_unconsumed"
+    PARTICIPANT_LIVE_CAPACITY_EXHAUSTED = "participant_live_capacity_exhausted"
+    PARTICIPANT_MEMORY_CAPACITY_EXHAUSTED = "participant_memory_capacity_exhausted"
+    EXTERNAL_IO_DEFERRED = "external_io_deferred"
+    OPENCODE_ENDPOINT_UNREACHABLE = "opencode_endpoint_unreachable"
+    OPENCODE_ENDPOINT_REFUSED = "opencode_endpoint_refused"
+    OPENCODE_ENDPOINT_LOST = "opencode_endpoint_lost"
+    OPENCODE_ENDPOINT_HEALTH_TIMEOUT = "opencode_endpoint_health_timeout"
+    OPENCODE_CONTAINER_OOM = "opencode_container_oom"
+    OPENCODE_EVENT_STREAM_ROUTE_UNREACHABLE = "opencode_event_stream_route_unreachable"
+    OPENCODE_EVENT_STREAM_ENDPOINT_REFUSED = "opencode_event_stream_endpoint_refused"
+    OPENCODE_EVENT_STREAM_READ_TIMEOUT = "opencode_event_stream_read_timeout"
+    OPENCODE_EVENT_STREAM_URL_ERROR = "opencode_event_stream_url_error"
+    OPENCODE_EVENT_STREAM_RECONNECT_GRACE_EXHAUSTED = (
+        "opencode_event_stream_reconnect_grace_exhausted"
+    )
+    PARTICIPANT_SESSION_MISSING = "participant_session_missing"
+    PARTICIPANT_SESSION_START_FAILED = "participant_session_start_failed"
+    PARTICIPANT_LIVE_UNBOUND = "participant_live_unbound"
+    PARTICIPANT_LIVE_HANDLE_MISSING = "participant_live_handle_missing"
+    PARTICIPANT_BINDING_FAILED = "participant_binding_failed"
+    CLAIMED_TASK_WITHOUT_PARTICIPANT = "claimed_task_without_participant"
+    STALE_CLAIM_REAPED = "stale_claim_reaped"
+    RUNTIME_INTENT_BACKLOG = "runtime_intent_backlog"
+    UNKNOWN_UNHEALTHY_EXPIRED = "unknown_unhealthy_expired"
+    RUNTIME_NO_PRODUCTIVE_PROGRESS = "runtime_no_productive_progress"
+
+
+class ManagedResearchFailureFamily(StrEnum):
+    UNKNOWN = "unknown"
+    VALIDATION = "validation"
+    BOOTSTRAP = "bootstrap"
+    DISPATCH = "dispatch"
+    RUNTIME = "runtime"
+    RUNTIME_RECOVERY = "runtime_recovery"
+    TERMINALIZATION = "terminalization"
+    CLEANUP = "cleanup"
+    INFRASTRUCTURE = "infrastructure"
+    USAGE_CAPTURE = "usage_capture"
+    PARTICIPANT_START = "participant_start"
+    ORCHESTRATOR_CYCLE = "orchestrator_cycle"
+    ORCHESTRATOR_PROVIDER = "orchestrator_provider"
+    ORCHESTRATOR_CODEX = "orchestrator_codex"
+
+
+class ManagedResearchFailureSeverity(StrEnum):
+    WARNING = "warning"
+    ERROR = "error"
+    FATAL = "fatal"
+
+
+class ManagedResearchFailureScope(StrEnum):
+    ACTOR = "actor"
+    TASK = "task"
+    RUN = "run"
+
+
+@dataclass(frozen=True)
+class ManagedResearchFailureClassification:
+    family: ManagedResearchFailureFamily
+    code: str
+    severity: ManagedResearchFailureSeverity
+    retryable: bool
+    scope: ManagedResearchFailureScope | None = None
+    operator_action: str | None = None
+    detail: str | None = None
+    actor_id: str | None = None
+    actor_key: str | None = None
+    task_id: str | None = None
+    task_key: str | None = None
+    recorded_at: str | None = None
+    family_raw: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict, repr=False, compare=False)
+
+    @classmethod
+    def from_wire(cls, payload: object) -> ManagedResearchFailureClassification:
+        if not isinstance(payload, dict):
+            raise ValueError("run failure classification must be an object")
+        family = payload.get("family")
+        code = payload.get("code")
+        severity = payload.get("severity")
+        retryable = payload.get("retryable")
+        if not isinstance(family, str) or not isinstance(code, str):
+            raise ValueError("run failure classification requires family and code")
+        if not isinstance(severity, str) or not isinstance(retryable, bool):
+            raise ValueError("run failure classification requires severity and retryable")
+        try:
+            parsed_family = ManagedResearchFailureFamily(family)
+        except ValueError:
+            parsed_family = ManagedResearchFailureFamily.UNKNOWN
+        return cls(
+            family=parsed_family,
+            code=code,
+            severity=ManagedResearchFailureSeverity(severity),
+            retryable=retryable,
+            scope=(
+                ManagedResearchFailureScope(payload["scope"])
+                if isinstance(payload.get("scope"), str)
+                else None
+            ),
+            operator_action=payload.get("operator_action")
+            if isinstance(payload.get("operator_action"), str)
+            else None,
+            detail=payload.get("detail") if isinstance(payload.get("detail"), str) else None,
+            actor_id=payload.get("actor_id") if isinstance(payload.get("actor_id"), str) else None,
+            actor_key=payload.get("actor_key")
+            if isinstance(payload.get("actor_key"), str)
+            else None,
+            task_id=payload.get("task_id") if isinstance(payload.get("task_id"), str) else None,
+            task_key=payload.get("task_key") if isinstance(payload.get("task_key"), str) else None,
+            recorded_at=payload.get("recorded_at")
+            if isinstance(payload.get("recorded_at"), str)
+            else None,
+            family_raw=family if parsed_family is ManagedResearchFailureFamily.UNKNOWN else None,
+            raw={str(key): value for key, value in payload.items()},
+        )
+
+    def to_wire(self) -> dict[str, Any]:
+        return {
+            key: value
+            for key, value in {
+                **self.raw,
+                "family": self.family.value,
+                "code": self.code,
+                "severity": self.severity.value,
+                "retryable": self.retryable,
+                "scope": self.scope.value if self.scope is not None else None,
+                "operator_action": self.operator_action,
+                "detail": self.detail,
+                "actor_id": self.actor_id,
+                "actor_key": self.actor_key,
+                "task_id": self.task_id,
+                "task_key": self.task_key,
+                "recorded_at": self.recorded_at,
+                "family_raw": self.family_raw,
+            }.items()
+            if value is not None
+        }
+
+
+__all__ = [
+    "ActorFailureReason",
+    "ManagedResearchFailureClassification",
+    "ManagedResearchFailureFamily",
+    "ManagedResearchFailureScope",
+    "ManagedResearchFailureSeverity",
+]

{synth_ai-0.18.0.dev590 → synth_ai-0.18.1.dev595}/synth_ai/sdk/research/contracts/image_releases.py

@@ -82,6 +82,26 @@ class ImageReleaseKind(StrEnum):
     CRAFTAX_SCORER = "craftax_scorer"
 
 
+class ActorImageCapability(StrEnum):
+    """Capabilities admitted by the backend actor-runtime image contract."""
+
+    CODEX_CLI = "codex_cli"
+    CRAFTAX_EVAL = "craftax_eval"
+    CRAFTER_EVAL = "crafter_eval"
+    DUNGEONGRID_EVAL = "dungeongrid_eval"
+    IMAGE_ARTIFACTS = "image_artifacts"
+    JAX_CPU = "jax_cpu"
+    MANAGED_RESEARCH_SDK = "managed_research_sdk"
+    MCP_CLIENT = "mcp_client"
+    MODAL_CLIENT = "modal_client"
+    NETHACK_EVAL = "nethack_eval"
+    NUMPY_STACK = "numpy_stack"
+    OPENCODE = "opencode"
+    OPENROUTER_CLIENT = "openrouter_client"
+    SYNTH_SDK = "synth_sdk"
+    VIDEO_ARTIFACTS = "video_artifacts"
+
+
 class RuntimeImageReleaseStatus(StrEnum):
     ACTIVE = "active"
     ARCHIVED = "archived"
@@ -149,6 +169,15 @@ def _strings(
     return tuple(out)
 
 
+def _capabilities(value: JsonValue) -> tuple[str, ...]:
+    capabilities = _strings(value, "capabilities", minimum=1)
+    allowed = frozenset(capability.value for capability in ActorImageCapability)
+    unexpected = sorted(set(capabilities) - allowed)
+    if unexpected:
+        raise ValueError(f"capabilities contain unsupported values: {unexpected!r}")
+    return capabilities
+
+
 def _datetime(value: object, field: str) -> datetime:
     parsed = (
         value
@@ -260,7 +289,9 @@ class CraftaxScorerImageReleaseDeclaration(_DeclarationBase):
     fixture_binary_sha256: str
 
     def __post_init__(self) -> None:
-        super().__post_init__()
+        # Explicit base dispatch is required for frozen slotted dataclasses on
+        # Python 3.12: zero-argument super() can retain the pre-slots class.
+        _DeclarationBase.__post_init__(self)
         if self.kind is not ImageReleaseKind.CRAFTAX_SCORER:
             raise ValueError("craftax scorer declaration kind must be craftax_scorer")
         object.__setattr__(
@@ -304,7 +335,8 @@ class ActorRuntimeImageReleaseDeclaration(_DeclarationBase):
     recipe_digest: str | None = None
 
     def __post_init__(self) -> None:
-        super().__post_init__()
+        # See CraftaxScorerImageReleaseDeclaration.__post_init__.
+        _DeclarationBase.__post_init__(self)
         if self.kind is not ImageReleaseKind.ACTOR_RUNTIME:
             raise ValueError("actor runtime declaration kind must be actor_runtime")
         object.__setattr__(self, "actor_role", _const(self.actor_role, "actor_role", "worker"))
@@ -313,9 +345,7 @@ class ActorRuntimeImageReleaseDeclaration(_DeclarationBase):
             "interface_mode",
             _const(self.interface_mode, "interface_mode", "synth_actor_runtime"),
         )
-        object.__setattr__(
-            self, "capabilities", _strings(list(self.capabilities), "capabilities", minimum=1)
-        )
+        object.__setattr__(self, "capabilities", _capabilities(list(self.capabilities)))
         object.__setattr__(
             self,
             "python_packages",
@@ -439,7 +469,7 @@ def declaration_from_wire(value: JsonValue) -> ImageReleaseDeclaration:
         source_commit_sha=source_commit_sha,
         actor_role=_const(payload["actor_role"], "actor_role", "worker"),
         interface_mode=_const(payload["interface_mode"], "interface_mode", "synth_actor_runtime"),
-        capabilities=_strings(payload["capabilities"], "capabilities", minimum=1),
+        capabilities=_capabilities(payload["capabilities"]),
         python_packages=_strings(payload["python_packages"], "python_packages", pattern=_PACKAGE),
         recipe_digest=optional_digest(payload.get("recipe_digest"), field="recipe_digest"),
     )
@@ -717,7 +747,7 @@ class ActorRuntimeImageMaterialization:
             selection_kind=_const(
                 payload["selection_kind"], "selection_kind", "customer_actor_runtime"
             ),
-            capabilities=_strings(payload["capabilities"], "capabilities", minimum=1),
+            capabilities=_capabilities(payload["capabilities"]),
             python_packages=_strings(
                 payload["python_packages"], "python_packages", pattern=_PACKAGE
             ),
@@ -1199,6 +1229,7 @@ __all__ = [
     "ActorRuntimeImageReleaseArchive",
     "ActorRuntimeImageReleaseDeclaration",
     "ActorRuntimeImageReleaseList",
+    "ActorImageCapability",
     "CraftaxScorerImageRelease",
     "CraftaxScorerImageReleaseDeclaration",
     "ImageRelease",

{synth_ai-0.18.0.dev590 → synth_ai-0.18.1.dev595}/synth_ai/sdk/research/contracts/run_observability.py

@@ -6,6 +6,7 @@ from collections.abc import Mapping
 from dataclasses import dataclass, field
 from enum import StrEnum
 
+from synth_ai.sdk.research.contracts.failure import ManagedResearchFailureClassification
 from synth_ai.sdk.research.contracts.run_state import (
     ManagedResearchRun,
     ManagedResearchRunLivenessPhase,
@@ -1307,7 +1308,7 @@ class ManagedResearchRunContractIncidents:
 class ManagedResearchRunContractDiagnostics:
     lifecycle_invariants: list[dict[str, object]] = field(default_factory=list)
     resource_wait: dict[str, object] | None = None
-    failure_classification: dict[str, object] | None = None
+    failure_classification: ManagedResearchFailureClassification | None = None
 
     @classmethod
     def from_wire(cls, payload: object) -> ManagedResearchRunContractDiagnostics:
@@ -1327,10 +1328,12 @@ class ManagedResearchRunContractDiagnostics:
             )
             if resource_wait is not None
             else None,
-            failure_classification=dict(
-                _require_mapping(
-                    failure_classification,
-                    label="run_contract.diagnostics.failure_classification",
+            failure_classification=ManagedResearchFailureClassification.from_wire(
+                dict(
+                    _require_mapping(
+                        failure_classification,
+                        label="run_contract.diagnostics.failure_classification",
+                    )
                 )
             )
             if failure_classification is not None
@@ -1509,6 +1512,7 @@ __all__ = [
     "ManagedResearchRunContractArtifacts",
     "ManagedResearchRunContractContainerEvalPackages",
     "ManagedResearchRunContractDiagnostics",
+    "ManagedResearchFailureClassification",
     "ManagedResearchRunContractExecutionRoute",
     "ManagedResearchRunContractFinalization",
     "ManagedResearchRunContractIncidents",

{synth_ai-0.18.0.dev590 → synth_ai-0.18.1.dev595}/synth_ai/sdk/research/image_releases.py

@@ -5,8 +5,12 @@
 
 from __future__ import annotations
 
+import hashlib
+from pathlib import Path
 from typing import cast
 
+import httpx
+
 from synth_ai.core.contracts.json_value import JsonObject, JsonValue
 from synth_ai.core.http.async_transport import AsyncHttpTransport
 from synth_ai.core.http.request import HttpRequest
@@ -79,6 +83,52 @@ def _retrieve(value: object, *, release_id: ImageReleaseId) -> ImageRelease:
     return release
 
 
+def _archive_path(
+    archive_path: str | Path,
+    *,
+    request: ImageReleaseUploadRequest,
+) -> Path:
+    """Verify the exact bytes that the backend will materialize.
+
+    The signed upload URL is intentionally the only direct-storage capability
+    used here.  Authentication for the Research API is never forwarded to the
+    object store.
+    """
+    path = Path(archive_path).expanduser().resolve()
+    if not path.is_file():
+        raise ValueError(f"image release archive is not a file: {path}")
+    if path.stat().st_size != request.declaration.archive_size_bytes:
+        raise ValueError("image release archive size does not match its declaration")
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for block in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(block)
+    if digest.hexdigest() != request.declaration.archive_sha256:
+        raise ValueError("image release archive digest does not match its declaration")
+    return path
+
+
+def _upload_timeout_seconds(value: float) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError("upload_timeout_seconds must be a number")
+    timeout_seconds = float(value)
+    if not 1.0 <= timeout_seconds <= 7200.0:
+        raise ValueError("upload_timeout_seconds must be between 1 and 7200")
+    return timeout_seconds
+
+
+def _verify_finalized_upload(
+    finalized: ImageReleaseFinalize,
+    *,
+    upload: ImageReleaseUpload,
+) -> ImageReleaseFinalize:
+    if finalized.release.release_id != upload.release_id:
+        raise ValueError("image finalize response changed its release identity")
+    if finalized.upload_reconciliation.upload_id != upload.upload_id:
+        raise ValueError("image finalize response changed its upload identity")
+    return finalized
+
+
 class ImageReleasesAPI:
     """Immutable uploads plus executable actor-image materializations."""
 
@@ -115,6 +165,48 @@ class ImageReleasesAPI:
         )
         return _finalize(value, request=request)
 
+    def upload_archive(
+        self,
+        archive_path: str | Path,
+        request: ImageReleaseUploadRequest,
+        *,
+        upload_timeout_seconds: float = 1800.0,
+    ) -> ImageReleaseFinalize:
+        """Upload and materialize an exact declared OCI archive.
+
+        The local archive is validated before requesting a presigned URL.  A
+        non-2xx object-store response is terminal: finalize is never attempted
+        against bytes the SDK did not observe as successfully uploaded.
+        """
+        if not isinstance(request, ImageReleaseUploadRequest):
+            raise ValueError("request must be ImageReleaseUploadRequest")
+        path = _archive_path(archive_path, request=request)
+        timeout_seconds = _upload_timeout_seconds(upload_timeout_seconds)
+        upload = self.create_upload(request)
+        if upload.upload_required:
+            with (
+                httpx.Client(timeout=timeout_seconds, follow_redirects=False) as client,
+                path.open("rb") as archive,
+            ):
+                response = client.put(
+                    upload.upload_url,
+                    content=archive,
+                    headers={"Content-Length": str(request.declaration.archive_size_bytes)},
+                )
+            if not response.is_success:
+                raise RuntimeError(
+                    f"image release archive upload failed with HTTP {response.status_code}"
+                )
+        return _verify_finalized_upload(
+            self.finalize(
+                ImageReleaseFinalizeRequest(
+                    upload_id=upload.upload_id,
+                    declaration=request.declaration,
+                )
+            ),
+            upload=upload,
+        )
+
     def list(self) -> ActorRuntimeImageReleaseList:
         value = self._transport.execute(
             _request(
@@ -147,6 +239,14 @@ class ImageReleasesAPI:
         )
         return _retrieve(value, release_id=release_id)
 
+    def get(self, release_id: ImageReleaseId) -> ImageRelease:
+        """Retrieve one immutable image-release receipt.
+
+        ``retrieve`` remains available for callers on the earlier core-client
+        surface; ``get`` matches the lifecycle verb used by the session API.
+        """
+        return self.retrieve(release_id)
+
 
 class AsyncImageReleasesAPI:
     """Native-async peer of :class:`ImageReleasesAPI`."""
@@ -184,6 +284,44 @@ class AsyncImageReleasesAPI:
         )
         return _finalize(value, request=request)
 
+    async def upload_archive(
+        self,
+        archive_path: str | Path,
+        request: ImageReleaseUploadRequest,
+        *,
+        upload_timeout_seconds: float = 1800.0,
+    ) -> ImageReleaseFinalize:
+        """Native-async upload and materialization of an exact OCI archive."""
+        if not isinstance(request, ImageReleaseUploadRequest):
+            raise ValueError("request must be ImageReleaseUploadRequest")
+        path = _archive_path(archive_path, request=request)
+        timeout_seconds = _upload_timeout_seconds(upload_timeout_seconds)
+        upload = await self.create_upload(request)
+        if upload.upload_required:
+            async with httpx.AsyncClient(
+                timeout=timeout_seconds,
+                follow_redirects=False,
+            ) as client:
+                with path.open("rb") as archive:
+                    response = await client.put(
+                        upload.upload_url,
+                        content=archive,
+                        headers={"Content-Length": str(request.declaration.archive_size_bytes)},
+                    )
+            if not response.is_success:
+                raise RuntimeError(
+                    f"image release archive upload failed with HTTP {response.status_code}"
+                )
+        return _verify_finalized_upload(
+            await self.finalize(
+                ImageReleaseFinalizeRequest(
+                    upload_id=upload.upload_id,
+                    declaration=request.declaration,
+                )
+            ),
+            upload=upload,
+        )
+
     async def list(self) -> ActorRuntimeImageReleaseList:
         value = await self._transport.execute(
             _request(
@@ -216,5 +354,9 @@ class AsyncImageReleasesAPI:
         )
         return _retrieve(value, release_id=release_id)
 
+    async def get(self, release_id: ImageReleaseId) -> ImageRelease:
+        """Native-async peer of :meth:`ImageReleasesAPI.get`."""
+        return await self.retrieve(release_id)
+
 
 __all__ = ["AsyncImageReleasesAPI", "ImageReleasesAPI"]