dharta-runtime 0.6.77__py3-none-any.whl

dharta/__init__.py

@@ -0,0 +1,46 @@
+from dharta.agent import Agent
+from dharta.app import Dharta
+from dharta.gateway import (
+    Gateway,
+    GatewayDelivery,
+    GatewayEvent,
+    HttpGateway,
+    LocalGateway,
+    ParticipantRegistry,
+)
+from dharta.instance import AgentInstance, InstanceManager, InstanceSession, InstanceStore
+from dharta.participant import AIAgent, HumanAgent, Participant
+from dharta.policies import PolicyViolationError
+from dharta.registry import AgentRegistry, PublishedAgent
+from dharta.response import Message, Part, Response, StreamEvent, Usage
+from dharta.session import Session
+from dharta.workspace import UserAgentView, WorkspaceManager
+
+__all__ = [
+    "AgentInstance",
+    "Dharta",
+    "Agent",
+    "AIAgent",
+    "Gateway",
+    "GatewayDelivery",
+    "GatewayEvent",
+    "HttpGateway",
+    "HumanAgent",
+    "InstanceManager",
+    "InstanceSession",
+    "InstanceStore",
+    "LocalGateway",
+    "Message",
+    "Part",
+    "Participant",
+    "ParticipantRegistry",
+    "PolicyViolationError",
+    "AgentRegistry",
+    "PublishedAgent",
+    "Response",
+    "Session",
+    "StreamEvent",
+    "Usage",
+    "UserAgentView",
+    "WorkspaceManager",
+]

dharta/__main__.py

@@ -0,0 +1,4 @@
+from dharta.cli import main
+
+if __name__ == "__main__":
+    main()

dharta/active_releases.py

@@ -0,0 +1,243 @@
+"""Active-release resolution for the data plane.
+
+When a session is created for a agent URL, the data plane must learn
+WHICH materialized release to run. dharta-web is authoritative: it owns
+the ``Agent#current_release`` pointer that the deploy/activate
+flow flips. This module fetches that pointer for an ``(org, agent)``
+pair and caches it briefly so the hot path doesn't round-trip the
+control plane on every session create.
+
+Mirrors :mod:`karta.model_settings` in shape (cached control-plane GET,
+``OrgScopedTtlCache`` keyed by org first so push-invalidation matches).
+The returned :class:`ActiveRelease` carries the agent's numeric id and
+version, which :mod:`karta.agent_runtime` turns into a deterministic
+on-disk template path via :func:`karta.releases.template_path_for`.
+
+Nothing here is secret: a template path / commit sha / version is
+operational metadata already surfaced in dashboards, so no scrubbing.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any, Dict, Optional, Tuple
+from urllib.parse import quote
+
+from dharta import observability as obs
+from dharta.cache import OrgScopedTtlCache, env_number
+from dharta.control_plane import ControlPlaneUnavailable, control_plane_get
+
+logger = obs.get_logger("dharta.active_releases")
+
+
+@dataclass(frozen=True)
+class ActiveRelease:
+    """The agent's currently-active release, as resolved by dharta-web."""
+
+    agent_id: int
+    version: int
+    build_kind: str
+    template_path: Optional[str]
+    commit_sha: Optional[str]
+    status: Optional[str] = None
+    image_ref: Optional[str] = None
+    # RFC 0035 P3: the frozen per-(harness,version) image digest, and whether it's a
+    # REAL built image (vs a registry placeholder). The runtime selects the microVM
+    # image by this digest only when built; else it runs the constant runtime image.
+    harness_image_digest: Optional[str] = None
+    harness_image_built: bool = False
+    # Agent-level config the control plane attaches (RFC 0015 Phase 2b:
+    # ``event_visibility`` toggles). Agent-scoped, not version-pinned.
+    config: Dict[str, Any] = field(default_factory=dict)
+
+
+# Keyed by (organization_id, agent_ref) so invalidate_org matches on
+# the first tuple element. TTL is short by default: the cached value
+# carries the active version, so a longer window means a freshly
+# activated release keeps serving the OLD version until expiry. A new
+# session is cheap to mis-route only within this window; in-flight
+# sessions are pinned to their start version regardless (see
+# agent_runtime). dharta-web push-invalidates on activate when wired.
+_CACHE_TTL_SECONDS = env_number("DHARTA_ACTIVE_RELEASE_CACHE_TTL", 10.0, float)
+_cache: OrgScopedTtlCache[ActiveRelease] = OrgScopedTtlCache(_CACHE_TTL_SECONDS)
+
+
+# RFC 0035 P3: the per-(harness,version) microVM image ref, keyed by
+# (org, agent_id, version) so the image resolver — which only holds ids — can read
+# what fetch_active_release (slug-keyed) learned. A successful fetch records the full
+# `repo@sha256:...` ref when the release froze a REAL built image, or None (placeholder
+# / unbuilt) so the resolver falls back to the constant image. Bounded by active
+# (agent, version) count.
+_image_ref_by_id: Dict[Tuple[int, int, int], Optional[str]] = {}
+
+
+def reset_active_release_cache() -> None:
+    """Test/ops hook: drop all cached active-release entries."""
+    _cache.clear()
+    _image_ref_by_id.clear()
+
+
+def invalidate_active_release_for_org(organization_id: int) -> int:
+    """Drop every cached active-release entry for ``organization_id``.
+
+    Called when dharta-web posts a CacheInvalidationJob after a release
+    is activated or rolled back. Returns the number of entries evicted.
+    """
+    return _cache.invalidate_org(organization_id)
+
+
+def ecr_repo_base() -> Optional[str]:
+    """The repo (no :tag / @digest) of the constant runtime image, e.g.
+    ``<acct>.dkr.ecr.<region>.amazonaws.com/dharta/agentcore-runtime``. A per-version
+    image lives in the SAME repo at a different digest, so ``repo@sha256:...`` selects
+    it. None when the constant image isn't configured."""
+    img = os.environ.get("DHARTA_AGENTCORE_RUNTIME_IMAGE")
+    if not img:
+        return None
+    img = img.split("@", 1)[0]  # drop any digest suffix
+    # Drop a trailing :tag. ECR hosts carry no port, so a ':' in the LAST path
+    # segment is the tag separator (not a registry port).
+    return img.rsplit(":", 1)[0] if ":" in img.rsplit("/", 1)[-1] else img
+
+
+def _record_image_ref(organization_id: int, release: ActiveRelease) -> None:
+    """Index this release's per-version image for the id-keyed resolver. Records the
+    immutable ``repo@digest`` ref only when a REAL built image was frozen (RFC 0035
+    P3); a placeholder / unbuilt release records None so the resolver falls back."""
+    key = (organization_id, release.agent_id, release.version)
+    if release.harness_image_built and release.harness_image_digest:
+        repo = ecr_repo_base()
+        _image_ref_by_id[key] = f"{repo}@{release.harness_image_digest}" if repo else None
+    else:
+        _image_ref_by_id[key] = None
+
+
+def image_ref_for(organization_id: int, agent_id: int, version: int) -> Optional[str]:
+    """The immutable ``repo@digest`` microVM image to run for this release — AgentCore
+    pulls EXACTLY it — or None to fall back to the constant runtime image. Non-None
+    only when a real built per-version image was seen for this release (RFC 0035 P3:
+    "the right image is used, based on the agent's deployment config")."""
+    return _image_ref_by_id.get((organization_id, agent_id, version))
+
+
+def fetch_active_release(
+    *,
+    organization_id: int,
+    agent_ref: str,
+    control_plane_url: Optional[str] = None,
+    service_token: Optional[str] = None,
+) -> Optional[ActiveRelease]:
+    """Return the active release for ``(organization_id, agent_ref)``.
+
+    ``agent_ref`` is the agent slug from the agent URL. Returns
+    ``None`` when the agent has no active release, is unknown, or the
+    control plane is unreachable. The two are distinguished by caching:
+    a definitive miss (404 / non-200) is negative-cached; an outage
+    (:class:`ControlPlaneUnavailable`) is not, so the next create retries.
+    """
+    key = (organization_id, agent_ref)
+    hit, cached = _cache.get(key)
+    if hit:
+        return cached
+
+    path = f"/internal/agents/{quote(agent_ref, safe='')}/active_release"
+    try:
+        payload = control_plane_get(
+            path,
+            params={"organization_id": organization_id},
+            control_plane_url=control_plane_url,
+            service_token=service_token,
+        )
+    except ControlPlaneUnavailable:
+        return None
+
+    if payload is None:
+        _cache.put(key, None)
+        return None
+
+    agent_id = payload.get("agent_id")
+    version = payload.get("version")
+    if not isinstance(agent_id, int) or not isinstance(version, int):
+        # Malformed answer — treat as a definitive miss rather than
+        # constructing a half-formed release we can't resolve a path for.
+        logger.warning(
+            "active_release for org=%s agent=%s missing agent_id/version",
+            organization_id,
+            agent_ref,
+        )
+        _cache.put(key, None)
+        return None
+
+    release = _release_from_payload(payload)
+    _cache.put(key, release)
+    _record_image_ref(organization_id, release)
+    return release
+
+
+def fetch_release_version(
+    *,
+    organization_id: int,
+    agent_ref: str,
+    version: int,
+    control_plane_url: Optional[str] = None,
+    service_token: Optional[str] = None,
+) -> Optional[ActiveRelease]:
+    """Resolve a SPECIFIC activatable release (RFC 0021 P3.3 pinned scheduling).
+
+    Mirrors :func:`fetch_active_release` but hits the version-pinned resolver,
+    which 404s unless the release exists and is activatable. Returns ``None``
+    on a definitive miss (unknown org/agent/version, non-activatable) and on a
+    control-plane outage alike — the caller turns either into a 404/409.
+
+    Not cached: a pinned release is immutable, but pinned scheduled runs are
+    rare (one per cron tick), so the round-trip isn't a hot path.
+    # ponytail: no cache; add an immutable (org,agent,version) cache if pinned
+    # runs ever become hot.
+    """
+    path = (
+        f"/internal/agents/{quote(agent_ref, safe='')}"
+        f"/releases/{quote(str(version), safe='')}"
+    )
+    try:
+        payload = control_plane_get(
+            path,
+            params={"organization_id": organization_id},
+            control_plane_url=control_plane_url,
+            service_token=service_token,
+        )
+    except ControlPlaneUnavailable:
+        return None
+
+    if payload is None:
+        return None
+
+    if not isinstance(payload.get("agent_id"), int) or not isinstance(payload.get("version"), int):
+        logger.warning(
+            "release v%s for org=%s agent=%s missing agent_id/version",
+            version,
+            organization_id,
+            agent_ref,
+        )
+        return None
+
+    release = _release_from_payload(payload)
+    _record_image_ref(organization_id, release)
+    return release
+
+
+def _release_from_payload(payload: Dict[str, Any]) -> ActiveRelease:
+    return ActiveRelease(
+        agent_id=int(payload["agent_id"]),
+        version=int(payload["version"]),
+        build_kind=str(payload.get("build_kind") or "file_copy"),
+        template_path=(str(payload["template_path"]) if payload.get("template_path") else None),
+        commit_sha=(str(payload["commit_sha"]) if payload.get("commit_sha") else None),
+        status=(str(payload["status"]) if payload.get("status") else None),
+        image_ref=(str(payload["image_ref"]) if payload.get("image_ref") else None),
+        harness_image_digest=(
+            str(payload["harness_image_digest"]) if payload.get("harness_image_digest") else None
+        ),
+        harness_image_built=bool(payload.get("harness_image_built")),
+        config=(payload["config"] if isinstance(payload.get("config"), dict) else {}),
+    )

dharta/agent.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, AsyncIterator, Dict, Optional
+
+from dharta.harness.base import AgentDefinition
+from dharta.response import Response, StreamEvent
+
+if TYPE_CHECKING:
+    from dharta.app import Dharta
+
+
+class Agent:
+    def __init__(self, app: "Dharta", definition: AgentDefinition) -> None:
+        self._app = app
+        self.definition = definition
+
+    @property
+    def name(self) -> str:
+        return self.definition.name
+
+    async def send(
+        self,
+        text: str,
+        *,
+        metadata: Optional[Dict[str, Any]] = None,
+        thinking: bool = False,
+    ) -> Response:
+        return await self._app.send(text, metadata=metadata, agent=self, thinking=thinking)
+
+    def send_sync(
+        self,
+        text: str,
+        *,
+        metadata: Optional[Dict[str, Any]] = None,
+        thinking: bool = False,
+    ) -> Response:
+        return self._app.send_sync(text, metadata=metadata, agent=self, thinking=thinking)
+
+    async def stream(
+        self,
+        text: str,
+        *,
+        metadata: Optional[Dict[str, Any]] = None,
+        thinking: bool = False,
+    ) -> AsyncIterator[StreamEvent]:
+        async for event in self._app.stream(text, metadata=metadata, agent=self, thinking=thinking):
+            yield event
+
+    def stream_sync(
+        self,
+        text: str,
+        *,
+        metadata: Optional[Dict[str, Any]] = None,
+        thinking: bool = False,
+    ):
+        return self._app.stream_sync(text, metadata=metadata, agent=self, thinking=thinking)
+
+    def __repr__(self) -> str:
+        return f"Agent(name={self.name!r})"

dharta/agent_builder_surface_authority.py

@@ -0,0 +1,326 @@
+"""Canonical RFC 0070 AgentBuilder surface authority.
+
+This value is parsed and compared in shadow only.  The existing ``abs`` /
+``abid`` / ``abep`` bridge remains the sole serving authority until cutover.
+Customer editing coordinates intentionally have no representation here.
+
+``release_status_at_issue`` is snapshot evidence, not a continuation-policy
+decision.  Immutable artifact/model-intent digests exclude never-built stale
+reservations while a later serving milestone remains free to require active
+status or permit an already-pinned built release.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import unicodedata
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Mapping, cast
+
+from dharta.model_contracts import ModelContractError, canonical_typed_bytes
+
+DOMAIN = b"karta:agent-builder-surface-authority:v1\0"
+AUTHORITY_TYPE = "agent_builder_surface_authority_v1"
+MAX_VALIDITY_SECONDS = 3600
+MAX_DATABASE_ID = (2**63) - 1
+_CANONICAL_UTC = re.compile(r"\A\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{6}Z\Z")
+_AUTHORITY_PUBLIC_ID = re.compile(r"\Aabsa_[A-Za-z0-9_-]{22,86}\Z")
+_SESSION_IDENTITY = re.compile(r"\Aabss_[A-Za-z0-9_-]{22,86}\Z")
+_SESSION_AUTHENTICATION_EPOCH = re.compile(r"\Aabse_[A-Za-z0-9_-]{22,86}\Z")
+_CANONICAL_DATABASE_ID = re.compile(r"\A[1-9][0-9]*\Z")
+_SHA256_HEX = re.compile(r"\A[0-9a-f]{64}\Z")
+
+_ATTRIBUTE_NAMES = (
+    "authority_public_id",
+    "slot",
+    "assignment_id",
+    "assignment_revision",
+    "assignment_authorization_revision",
+    "assignment_status",
+    "agent_id",
+    "agent_organization_id",
+    "agent_authorization_revision",
+    "agent_status",
+    "release_id",
+    "release_version",
+    "release_agent_id",
+    "release_status_at_issue",
+    "release_kind",
+    "release_execution_artifact_digest",
+    "release_model_intent_manifest_digest",
+    "embed_key_id",
+    "embed_key_agent_id",
+    "embed_key_organization_id",
+    "embed_key_authorization_revision",
+    "embed_key_mode",
+    "embed_key_status",
+    "embed_key_livemode",
+    "model_policy_organization_id",
+    "billing_organization_id",
+    "organization_authorization_revision",
+    "organization_status",
+    "organization_first_party",
+    "plan_id",
+    "plan_key",
+    "plan_authorization_revision",
+    "session_identity",
+    "issued_at",
+    "expires_at",
+    "session_authentication_epoch",
+    "data_plane_install_id",
+    "data_plane_install_authorization_revision",
+    "install_kind",
+    "install_status",
+    "runtime_audience",
+)
+_FIELDS = frozenset(("schema_version", "authority_type", *_ATTRIBUTE_NAMES))
+_INTEGER_FIELDS = (
+    "assignment_id",
+    "assignment_revision",
+    "assignment_authorization_revision",
+    "agent_id",
+    "agent_organization_id",
+    "agent_authorization_revision",
+    "release_version",
+    "release_agent_id",
+    "embed_key_id",
+    "embed_key_agent_id",
+    "embed_key_organization_id",
+    "embed_key_authorization_revision",
+    "model_policy_organization_id",
+    "billing_organization_id",
+    "organization_authorization_revision",
+    "plan_id",
+    "plan_authorization_revision",
+    "data_plane_install_authorization_revision",
+)
+_IDENTIFIER_FIELDS = (
+    "data_plane_install_id",
+    "runtime_audience",
+)
+
+
+def _positive_integer(value: object, field: str) -> int:
+    if type(value) is not int or cast(int, value) <= 0:
+        raise ModelContractError(f"{field} must be a positive integer")
+    return cast(int, value)
+
+
+def _identifier(value: object, field: str) -> str:
+    if not isinstance(value, str):
+        raise ModelContractError(f"{field} must be a stable identifier")
+    try:
+        encoded = value.encode("utf-8", errors="strict")
+    except UnicodeEncodeError as exc:
+        raise ModelContractError(f"{field} must be a stable identifier") from exc
+    invalid = (
+        not encoded
+        or len(encoded) > 2048
+        or unicodedata.normalize("NFC", value) != value
+        or value != value.strip()
+        or any(character.isspace() for character in value)
+        or any(ord(character) <= 0x1F or 0x7F <= ord(character) <= 0x9F for character in value)
+    )
+    if invalid:
+        raise ModelContractError(f"{field} must be a stable identifier")
+    return value
+
+
+def _canonical_time(value: object, field: str) -> datetime:
+    if not isinstance(value, str) or _CANONICAL_UTC.fullmatch(value) is None:
+        raise ModelContractError(f"{field} must be canonical UTC with six fractional digits")
+    try:
+        parsed = datetime.strptime(value, "%Y-%m-%dT%H:%M:%S.%fZ").replace(tzinfo=timezone.utc)
+    except ValueError as exc:
+        raise ModelContractError(
+            f"{field} must be canonical UTC with six fractional digits"
+        ) from exc
+    if parsed.strftime("%Y-%m-%dT%H:%M:%S.%fZ") != value:
+        raise ModelContractError(f"{field} must be canonical UTC with six fractional digits")
+    return parsed
+
+
+def _validate_attributes(attributes: Mapping[str, object]) -> tuple[datetime, datetime]:
+    for field in _INTEGER_FIELDS:
+        _positive_integer(attributes[field], field)
+    for field in _IDENTIFIER_FIELDS:
+        _identifier(attributes[field], field)
+
+    opaque_ids = (
+        ("authority_public_id", _AUTHORITY_PUBLIC_ID),
+        ("session_identity", _SESSION_IDENTITY),
+        ("session_authentication_epoch", _SESSION_AUTHENTICATION_EPOCH),
+    )
+    for field, pattern in opaque_ids:
+        value = attributes[field]
+        if not isinstance(value, str) or pattern.fullmatch(value) is None:
+            raise ModelContractError(f"{field} must be a server-minted opaque id")
+    value = attributes["release_id"]
+    if (
+        not isinstance(value, str)
+        or _CANONICAL_DATABASE_ID.fullmatch(value) is None
+        or int(value) > MAX_DATABASE_ID
+    ):
+        raise ModelContractError("release_id must be a canonical decimal database id")
+    for field in (
+        "release_execution_artifact_digest",
+        "release_model_intent_manifest_digest",
+    ):
+        value = attributes[field]
+        if not isinstance(value, str) or _SHA256_HEX.fullmatch(value) is None:
+            raise ModelContractError(f"{field} must be lowercase SHA-256 hex")
+    for field in ("embed_key_livemode", "organization_first_party"):
+        if type(attributes[field]) is not bool:
+            raise ModelContractError(f"{field} must be a boolean")
+
+    expected_literals = {
+        "slot": "agent_builder",
+        "assignment_status": "bound",
+        "agent_status": "active",
+        "release_kind": "production",
+        "embed_key_mode": "live",
+        "embed_key_status": "active",
+        "organization_status": "active",
+        "plan_key": "internal",
+        "install_kind": "karta_operated",
+        "install_status": "active",
+    }
+    for field, expected in expected_literals.items():
+        if attributes[field] != expected:
+            raise ModelContractError(f"{field} must be {expected}")
+    if attributes["release_status_at_issue"] not in ("active", "superseded"):
+        raise ModelContractError("release must be executable")
+    if attributes["embed_key_livemode"] is not True:
+        raise ModelContractError("embed key must be live-mode")
+    if attributes["organization_first_party"] is not True:
+        raise ModelContractError("organization must be first-party")
+
+    organization_ids = {
+        cast(int, attributes["agent_organization_id"]),
+        cast(int, attributes["embed_key_organization_id"]),
+        cast(int, attributes["model_policy_organization_id"]),
+        cast(int, attributes["billing_organization_id"]),
+    }
+    if len(organization_ids) != 1:
+        raise ModelContractError(
+            "agent, embed key, model policy, and billing organization must match"
+        )
+    agent_ids = {
+        cast(int, attributes["agent_id"]),
+        cast(int, attributes["release_agent_id"]),
+        cast(int, attributes["embed_key_agent_id"]),
+    }
+    if len(agent_ids) != 1:
+        raise ModelContractError("agent, release, and embed key agent must match")
+
+    normalized_times = []
+    for field in ("issued_at", "expires_at"):
+        value = attributes[field]
+        if not isinstance(value, datetime) or value.tzinfo is None or value.utcoffset() is None:
+            raise ModelContractError(f"{field} must be a timezone-aware datetime")
+        normalized_times.append(value.astimezone(timezone.utc))
+    issued_at, expires_at = normalized_times
+    validity = (expires_at - issued_at).total_seconds()
+    if not 0 < validity <= MAX_VALIDITY_SECONDS:
+        raise ModelContractError(
+            "AgentBuilder surface authority validity must be greater than zero "
+            f"and at most {MAX_VALIDITY_SECONDS} seconds"
+        )
+    return issued_at, expires_at
+
+
+@dataclass(frozen=True)
+class AgentBuilderSurfaceAuthorityV1:
+    authority_public_id: str
+    slot: str
+    assignment_id: int
+    assignment_revision: int
+    assignment_authorization_revision: int
+    assignment_status: str
+    agent_id: int
+    agent_organization_id: int
+    agent_authorization_revision: int
+    agent_status: str
+    release_id: str
+    release_version: int
+    release_agent_id: int
+    release_status_at_issue: str
+    release_kind: str
+    release_execution_artifact_digest: str
+    release_model_intent_manifest_digest: str
+    embed_key_id: int
+    embed_key_agent_id: int
+    embed_key_organization_id: int
+    embed_key_authorization_revision: int
+    embed_key_mode: str
+    embed_key_status: str
+    embed_key_livemode: bool
+    model_policy_organization_id: int
+    billing_organization_id: int
+    organization_authorization_revision: int
+    organization_status: str
+    organization_first_party: bool
+    plan_id: int
+    plan_key: str
+    plan_authorization_revision: int
+    session_identity: str
+    issued_at: datetime
+    expires_at: datetime
+    session_authentication_epoch: str
+    data_plane_install_id: str
+    data_plane_install_authorization_revision: int
+    install_kind: str
+    install_status: str
+    runtime_audience: str
+
+    def __post_init__(self) -> None:
+        # The public dataclass constructor is as strict as ``from_mapping``;
+        # callers cannot create or digest an invalid authority by bypassing the
+        # wire parser.
+        issued_at, expires_at = _validate_attributes(
+            {name: getattr(self, name) for name in _ATTRIBUTE_NAMES}
+        )
+        object.__setattr__(self, "issued_at", issued_at)
+        object.__setattr__(self, "expires_at", expires_at)
+
+    @classmethod
+    def from_mapping(cls, value: object) -> "AgentBuilderSurfaceAuthorityV1":
+        if not isinstance(value, Mapping) or not all(isinstance(key, str) for key in value):
+            raise ModelContractError(
+                "AgentBuilderSurfaceAuthorityV1 payload must be an object with string keys"
+            )
+        if frozenset(value) != _FIELDS:
+            raise ModelContractError(
+                "AgentBuilderSurfaceAuthorityV1 fields do not match the V1 contract"
+            )
+        if type(value.get("schema_version")) is not int or value.get("schema_version") != 1:
+            raise ModelContractError("AgentBuilderSurfaceAuthorityV1 schema_version must be 1")
+        if value.get("authority_type") != AUTHORITY_TYPE:
+            raise ModelContractError(f"authority_type must be {AUTHORITY_TYPE}")
+
+        attributes = {name: value[name] for name in _ATTRIBUTE_NAMES}
+        issued_at = _canonical_time(attributes["issued_at"], "issued_at")
+        expires_at = _canonical_time(attributes["expires_at"], "expires_at")
+        attributes["issued_at"] = issued_at
+        attributes["expires_at"] = expires_at
+
+        return cls(**attributes)
+
+    def as_dict(self) -> dict[str, object]:
+        values: dict[str, object] = {name: getattr(self, name) for name in _ATTRIBUTE_NAMES}
+        values["issued_at"] = self.issued_at.astimezone(timezone.utc).strftime(
+            "%Y-%m-%dT%H:%M:%S.%fZ"
+        )
+        values["expires_at"] = self.expires_at.astimezone(timezone.utc).strftime(
+            "%Y-%m-%dT%H:%M:%S.%fZ"
+        )
+        return {
+            "schema_version": 1,
+            "authority_type": AUTHORITY_TYPE,
+            **values,
+        }
+
+    def contract_digest(self) -> str:
+        return hashlib.sha256(DOMAIN + canonical_typed_bytes(self.as_dict())).hexdigest()