execution-plane-client 0.1.5__py3-none-any.whl

execution_plane_client/__init__.py

@@ -0,0 +1 @@
+"""Shared command contracts and participant-owned handler registration."""

execution_plane_client/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.5'
+__version_tuple__ = version_tuple = (0, 1, 5)
+
+__commit_id__ = commit_id = None

execution_plane_client/catalog.py

@@ -0,0 +1,61 @@
+"""Supported command revisions and their wire payload contracts."""
+
+from dataclasses import dataclass
+
+from execution_plane_client.commands.base import CommandPayload
+from execution_plane_client.commands.clusters import ClusterDelete, ClusterProvision, ClusterRegister, ClusterUpdate
+from execution_plane_client.commands.control import CancelCommand, Completion
+from execution_plane_client.commands.credentials import CredentialResolve
+from execution_plane_client.commands.targets import TargetDelete, TargetRegister, TargetUpdate
+from execution_plane_client.commands.work import WorkExecute
+from execution_plane_client.errors import UnsupportedCommand
+from execution_plane_client.protocol import MessageEnvelope
+
+
+@dataclass(frozen=True)
+class CommandDefinition:
+    """One command type, revision and payload schema."""
+
+    command_type: str
+    revision: int
+    payload_schema: type[CommandPayload]
+
+
+class CommandCatalog:
+    """Validate known commands independently of installed handlers."""
+
+    def __init__(self) -> None:
+        """Install version-one work, resource and completion contracts."""
+        payloads = (
+            WorkExecute,
+            Completion,
+            CredentialResolve,
+            ClusterRegister,
+            ClusterProvision,
+            ClusterUpdate,
+            ClusterDelete,
+            TargetRegister,
+            TargetUpdate,
+            TargetDelete,
+            CancelCommand,
+        )
+        self._definitions = {
+            (schema.command_type, schema.command_revision): CommandDefinition(
+                schema.command_type, schema.command_revision, schema
+            )
+            for schema in payloads
+        }
+
+    def definition(self, command_type: str, revision: int) -> CommandDefinition:
+        """Return a supported revision or an explicit rejection."""
+        try:
+            return self._definitions[command_type, revision]
+        except KeyError:
+            raise UnsupportedCommand from None
+
+    def validate(self, message: MessageEnvelope) -> CommandPayload:
+        """Validate the payload and completion parent, returning the typed payload."""
+        definition = self.definition(message.command.command_type, message.command.command_revision)
+        payload = definition.payload_schema.model_validate(message.command.payload)
+        definition.payload_schema.validate_parent(message.command.parent_command_id)
+        return payload

execution_plane_client/commands/__init__.py

@@ -0,0 +1,37 @@
+"""Shared resource identities and HTTPS configuration validation."""
+
+from urllib.parse import urlsplit
+from uuid import UUID
+
+from execution_plane_client.protocol import PositiveInt, WireModel
+
+
+class ResourceIdentity(WireModel):
+    """Caller-supplied physical resource identity."""
+
+    resource_id: UUID
+
+
+class ResourceRevision(WireModel):
+    """Stable cluster integration identity and desired-state revision."""
+
+    resource_key: UUID
+    desired_revision: PositiveInt
+
+
+def validate_endpoint(value: str) -> str:
+    """Require HTTPS without embedded credentials, queries or fragments."""
+    parsed = urlsplit(value)
+    if (
+        parsed.scheme != "https"
+        or not parsed.hostname
+        or parsed.username is not None
+        or parsed.password is not None
+        or parsed.query
+        or parsed.fragment
+        or any(char.isspace() for char in value)
+    ):
+        message = "Endpoint must be an HTTPS URL without userinfo, query or fragment"
+        raise ValueError(message)
+    _ = parsed.port
+    return value

execution_plane_client/commands/base.py

@@ -0,0 +1,64 @@
+"""Construct transport-neutral messages from typed command payloads."""
+
+from datetime import UTC, datetime
+from typing import ClassVar
+from uuid import UUID, uuid4
+
+from execution_plane_client.errors import ProtocolConflict
+from execution_plane_client.protocol import Command, CommandScope, MessageEnvelope, WireModel
+
+
+class CommandPayload(WireModel):
+    """A typed command knows its wire identity and builds its delivery envelope."""
+
+    command_type: ClassVar[str]
+    command_revision: ClassVar[int] = 1
+    requires_parent: ClassVar[bool] = False
+
+    @classmethod
+    def validate_parent(cls, parent_command_id: UUID | None) -> None:
+        """Require correlation for commands that report another command's outcome."""
+        if cls.requires_parent and parent_command_id is None:
+            raise ProtocolConflict
+
+    def _message_payload(self) -> dict[str, object]:
+        return self.model_dump(mode="json")
+
+    def to_message(
+        self,
+        *,
+        source_id: str,
+        destination_id: str,
+        client_id: str,
+        command_id: UUID | None = None,
+        parent_command_id: UUID | None = None,
+        occurred_at: datetime | None = None,
+        message_id: UUID | None = None,
+        sequence: int = 0,
+    ) -> MessageEnvelope:
+        """Build a validated message, generating a command UUID and UTC time if omitted.
+
+        The message ID defaults to the command ID. Retain the returned message for
+        retries, or supply the original IDs and timestamp when reconstructing it.
+        Routing, authentication, HTTP delivery and persistence belong to the caller.
+        """
+        self.validate_parent(parent_command_id)
+        payload = self._message_payload()
+        type(self).model_validate(payload)
+        identity = uuid4() if command_id is None else command_id
+        return MessageEnvelope(
+            message_id=identity if message_id is None else message_id,
+            command_id=identity,
+            source_id=source_id,
+            destination_id=destination_id,
+            scope=CommandScope(client_id=client_id),
+            sequence=sequence,
+            command=Command(
+                command_id=identity,
+                parent_command_id=parent_command_id,
+                command_type=self.command_type,
+                command_revision=self.command_revision,
+                payload=payload,
+                occurred_at=datetime.now(UTC) if occurred_at is None else occurred_at,
+            ),
+        )

execution_plane_client/commands/clusters.py

@@ -0,0 +1,96 @@
+"""Cluster-binding desired state, independent of EP persistence models."""
+
+import ssl
+from typing import Annotated, ClassVar, Self
+from uuid import UUID
+
+from pydantic import Field, StrictBool, StrictStr, field_validator, model_validator
+
+from execution_plane_client.commands import ResourceRevision, validate_endpoint
+from execution_plane_client.commands.base import CommandPayload
+from execution_plane_client.protocol import WireModel
+
+
+class ClusterConfigBase(WireModel):
+    """Registration configuration fields used by handlers to copy and compare bindings."""
+
+    name: Annotated[StrictStr, Field(min_length=1, max_length=255)]
+    endpoint: Annotated[StrictStr, Field(max_length=2048)]
+    namespace: Annotated[StrictStr, Field(min_length=1, max_length=63, pattern=r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")]
+    credential_ref: UUID
+    ca_certificate: Annotated[StrictStr, Field(max_length=65536)] | None = Field(default=None, repr=False)
+    project_ids: list[UUID] | None = None
+    labels: dict[str, str] = Field(default_factory=dict)
+    enabled: StrictBool = True
+    is_default: StrictBool = False
+
+
+class ClusterRegister(ClusterConfigBase, ResourceRevision, CommandPayload):
+    """Create or replace the complete desired configuration of a binding."""
+
+    command_type: ClassVar[str] = "cluster.register"
+
+    @field_validator("endpoint")
+    @classmethod
+    def check_endpoint(cls, value: str) -> str:
+        """Protect the management credential in transit."""
+        return validate_endpoint(value)
+
+    @field_validator("ca_certificate")
+    @classmethod
+    def check_ca(cls, value: str | None) -> str | None:
+        """Reject invalid PEM before accepting desired state."""
+        if value is not None:
+            try:
+                ssl.create_default_context().load_verify_locations(cadata=value)
+            except ssl.SSLError as exc:
+                message = "CA certificate must contain valid PEM"
+                raise ValueError(message) from exc
+        return value
+
+    @model_validator(mode="after")
+    def check_credential_ref(self) -> Self:
+        """Require a resolvable credential reference for enabled bindings."""
+        if self.enabled and self.credential_ref == UUID(int=0):
+            message = "Enabled cluster bindings require a credential_ref"
+            raise ValueError(message)
+        return self
+
+
+class ClusterProvision(ClusterRegister):
+    """Provision through the same binding and default-target reconciler."""
+
+    command_type: ClassVar[str] = "cluster.provision"
+
+
+class ClusterDelete(ResourceRevision, CommandPayload):
+    """Disable an existing binding at the requested desired-state revision."""
+
+    command_type: ClassVar[str] = "cluster.delete"
+
+
+class ClusterUpdate(ResourceRevision, CommandPayload):
+    """Patch a binding; only CA and project grants support explicit null."""
+
+    command_type: ClassVar[str] = "cluster.update"
+
+    name: StrictStr | None = None
+    endpoint: StrictStr | None = None
+    namespace: StrictStr | None = None
+    credential_ref: UUID | None = None
+    ca_certificate: StrictStr | None = Field(default=None, repr=False)
+    project_ids: list[UUID] | None = None
+    labels: dict[str, str] | None = None
+    enabled: StrictBool | None = None
+    is_default: StrictBool | None = None
+
+    def _message_payload(self) -> dict[str, object]:
+        return self.model_dump(mode="json", exclude_unset=True)
+
+    @model_validator(mode="after")
+    def check_nulls(self) -> Self:
+        """Preserve omitted values but reject clearing required fields."""
+        if any(getattr(self, key) is None for key in self.model_fields_set - {"ca_certificate", "project_ids"}):
+            message = "Required binding fields cannot be null"
+            raise ValueError(message)
+        return self

execution_plane_client/commands/control.py

@@ -0,0 +1,35 @@
+"""Cancellation requests and work completion commands."""
+
+from typing import ClassVar, Literal
+from uuid import UUID
+
+from pydantic import Field, field_validator
+
+from execution_plane_client.commands.base import CommandPayload
+from execution_plane_client.protocol import ResourceReference, validate_json
+
+
+class CancelCommand(CommandPayload):
+    """Cancel an existing work command, whose UUID is its work-item UUID."""
+
+    command_type: ClassVar[str] = "command.cancel"
+
+    target_command_id: UUID
+
+
+class Completion(CommandPayload):
+    """Terminal or uncertain work outcome delivered to the initiating client."""
+
+    command_type: ClassVar[str] = "work.execute.completed"
+    requires_parent: ClassVar[bool] = True
+
+    status: Literal["succeeded", "failed", "cancelled", "outcome_unknown"]
+    result: dict[str, object] = Field(default_factory=dict, repr=False)
+    resource: ResourceReference | None = None
+    error_code: str | None = None
+
+    @field_validator("result", mode="before")
+    @classmethod
+    def check_result(cls, value: object) -> object:
+        """Require finite JSON; work output limits are set by the invocation."""
+        return validate_json(value, max_bytes=None)

execution_plane_client/commands/credentials.py

@@ -0,0 +1,25 @@
+"""Credential-reference resolution commands and responses."""
+
+from __future__ import annotations
+
+from typing import Annotated, ClassVar
+from uuid import UUID  # noqa: TC003 - Pydantic evaluates fields.
+
+from pydantic import Field, StrictStr
+
+from execution_plane_client.commands.base import CommandPayload
+from execution_plane_client.protocol import WireModel
+
+
+class CredentialResolve(CommandPayload):
+    """Resolve an opaque credential reference into a short-lived value."""
+
+    command_type: ClassVar[str] = "credential.resolve"
+    credential_ref: UUID
+
+
+class CredentialResolution(WireModel):
+    """The resolved credential value for one submitted command."""
+
+    message_id: UUID
+    credential: Annotated[StrictStr, Field(min_length=1, max_length=65536, repr=False)]

execution_plane_client/commands/targets.py

@@ -0,0 +1,151 @@
+"""Execution-target configuration and independent registration commands."""
+
+from __future__ import annotations
+
+import re
+from typing import Annotated, ClassVar, Literal, Self
+from uuid import UUID  # noqa: TC003 - Pydantic evaluates fields.
+
+from pydantic import Field, StrictBool, StrictStr, field_validator, model_validator
+
+from execution_plane_client.commands import ResourceIdentity, validate_endpoint
+from execution_plane_client.commands.base import CommandPayload
+from execution_plane_client.protocol import WireModel
+
+_LABEL_NAME = re.compile(r"^[A-Za-z0-9]([A-Za-z0-9_.-]*[A-Za-z0-9])?$")
+_DNS_LABEL = re.compile(r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")
+_LABEL_LIMIT = 63
+_DOMAIN_LIMIT = 253
+
+
+def _label_key(value: str) -> bool:
+    prefix, separator, name = value.partition("/")
+    if separator:
+        if (
+            not prefix
+            or len(prefix) > _DOMAIN_LIMIT
+            or any(len(part) > _LABEL_LIMIT or not _DNS_LABEL.fullmatch(part) for part in prefix.split("."))
+        ):
+            return False
+    else:
+        name = prefix
+    return len(name) <= _LABEL_LIMIT and bool(_LABEL_NAME.fullmatch(name))
+
+
+def _label_value(value: str) -> bool:
+    return len(value) <= _LABEL_LIMIT and (value == "" or bool(_LABEL_NAME.fullmatch(value)))
+
+
+class KubernetesPlacement(WireModel):
+    """Kubernetes placement contract, independent of Kubernetes libraries."""
+
+    type: Literal["kubernetes"] = "kubernetes"
+    namespace: Annotated[StrictStr, Field(min_length=1, max_length=63, pattern=r"^[a-z0-9]([-a-z0-9]*[a-z0-9])?$")]
+    node_selectors: list[str] = Field(default_factory=list)
+    tolerations: list[str] = Field(default_factory=list)
+
+    @field_validator("node_selectors")
+    @classmethod
+    def check_selectors(cls, values: list[str]) -> list[str]:
+        """Accept only Kubernetes key=value selectors."""
+        for value in values:
+            key, separator, label = value.partition("=")
+            if not separator or not _label_key(key) or not _label_value(label):
+                message = "Invalid Kubernetes node selector"
+                raise ValueError(message)
+        return values
+
+    @field_validator("tolerations")
+    @classmethod
+    def check_tolerations(cls, values: list[str]) -> list[str]:
+        """Accept compact tolerations with supported scheduling effects."""
+        for value in values:
+            key_value, separator, effect = value.rpartition(":")
+            if not separator:
+                key_value, effect = value, ""
+            key, equals, label = key_value.partition("=")
+            valid_key = bool(key) and _label_key(key) if equals else not key or _label_key(key)
+            if (
+                not valid_key
+                or not _label_value(label)
+                or effect not in {"", "NoSchedule", "PreferNoSchedule", "NoExecute"}
+            ):
+                message = "Invalid Kubernetes toleration"
+                raise ValueError(message)
+        return values
+
+
+class RHELPlacement(WireModel):
+    """Placement for a supported RHEL backend."""
+
+    type: Literal["rhel"] = "rhel"
+
+
+Placement = Annotated[KubernetesPlacement | RHELPlacement, Field(discriminator="type")]
+
+
+class TargetDefinition(WireModel):
+    """Desired execution-target configuration."""
+
+    name: Annotated[StrictStr, Field(min_length=1, max_length=255)]
+    backend_type: Literal["vanilla_k8s", "openshell"]
+    placement: Placement
+    endpoint: Annotated[StrictStr, Field(min_length=1, max_length=2048)]
+    credential_ref: UUID
+    labels: dict[str, str] = Field(default_factory=dict)
+
+    @field_validator("endpoint")
+    @classmethod
+    def check_endpoint(cls, value: str) -> str:
+        """Preserve verified HTTPS for provider management credentials."""
+        return validate_endpoint(value)
+
+    @model_validator(mode="after")
+    def check_backend(self) -> Self:
+        """Reject backend/placement pairs unsupported by the provider adapters."""
+        if (self.backend_type == "vanilla_k8s") != isinstance(self.placement, KubernetesPlacement):
+            message = "Backend does not support this placement"
+            raise ValueError(message)
+        return self
+
+
+class TargetRegister(TargetDefinition, ResourceIdentity, CommandPayload):
+    """Register an independently identified target on an existing cluster."""
+
+    command_type: ClassVar[str] = "execution_target.register"
+
+    cluster_id: UUID
+    is_default: StrictBool = False
+
+
+class TargetDelete(ResourceIdentity, CommandPayload):
+    """Request draining of an independently managed execution target."""
+
+    command_type: ClassVar[str] = "execution_target.delete"
+
+
+class TargetUpdate(ResourceIdentity, CommandPayload):
+    """Mutable target fields; `is_default=true` promotes this target."""
+
+    command_type: ClassVar[str] = "execution_target.update"
+
+    name: Annotated[StrictStr, Field(min_length=1, max_length=255)] | None = None
+    endpoint: Annotated[StrictStr, Field(min_length=1, max_length=2048)] | None = None
+    placement: Placement | None = None
+    credential_ref: UUID | None = None
+    labels: dict[str, str] | None = None
+    is_default: StrictBool | None = None
+
+    def _message_payload(self) -> dict[str, object]:
+        payload = self.model_dump(mode="json", exclude_unset=True)
+        if self.placement is not None:
+            payload["placement"] = self.placement.model_dump(
+                mode="json", include=self.placement.model_fields_set | {"type"}
+            )
+        return payload
+
+    @field_validator("endpoint")
+    @classmethod
+    def check_endpoint(cls, value: str | None) -> str | None:
+        """Validate explicit endpoint updates before applying them."""
+        return None if value is None else validate_endpoint(value)

execution_plane_client/commands/work.py

@@ -0,0 +1,39 @@
+"""Versioned work invocation values without node-provider imports."""
+
+from typing import Annotated, ClassVar, Literal
+
+from pydantic import Field, StrictStr, field_validator
+
+from execution_plane_client.commands.base import CommandPayload
+from execution_plane_client.protocol import PositiveInt, WireModel, validate_json
+
+
+class NodeInvocation(WireModel):
+    """Version-one invocation consumed by the existing node protocol."""
+
+    version: Literal[1] = 1
+    operation: Literal["execute"] = "execute"
+    inputs: dict[str, object]
+    credentials: dict[str, object] = Field(repr=False)
+    workflow_context: dict[str, object]
+    settings: dict[str, object]
+    timeout_seconds: PositiveInt
+    max_output_bytes: PositiveInt
+
+    @field_validator("inputs", "credentials", "workflow_context", "settings", mode="before")
+    @classmethod
+    def check_json(cls, value: object) -> object:
+        """Keep all nested invocation data portable and bounded."""
+        return validate_json(value)
+
+
+class WorkExecute(CommandPayload):
+    """Script command with stable caller correlation and provider-neutral input."""
+
+    command_type: ClassVar[str] = "work.execute"
+
+    image: Annotated[StrictStr, Field(min_length=1, max_length=2048)]
+    selectors: dict[StrictStr, StrictStr] = Field(default_factory=dict)
+    invocation: NodeInvocation = Field(repr=False)
+    output_config: dict[str, str] | None = None
+    workload_type: Literal["script"] = "script"

execution_plane_client/errors.py

@@ -0,0 +1,11 @@
+"""Safe protocol errors, without request bodies or infrastructure details."""
+
+# ruff: noqa: N818
+
+
+class ProtocolConflict(Exception):
+    """Duplicate registration or conflicting resource state."""
+
+
+class UnsupportedCommand(Exception):
+    """The command type or revision is unsupported by this participant."""

execution_plane_client/handlers.py

@@ -0,0 +1,22 @@
+"""Participant-owned command handling, without database or HTTP dependencies."""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from execution_plane_client.commands.base import CommandPayload
+from execution_plane_client.protocol import MessageEnvelope, ResourceReference
+
+
+@dataclass(frozen=True)
+class HandlingResult:
+    """Optional resource created or affected by a command."""
+
+    resource: ResourceReference | None = None
+
+
+class CommandHandler[ContextT](Protocol):
+    """A participant supplies its own authenticated execution context."""
+
+    async def handle(self, message: MessageEnvelope, payload: CommandPayload, context: ContextT) -> HandlingResult:
+        """Apply domain effects using the catalog's validated payload and original envelope."""
+        ...

execution_plane_client/protocol.py

@@ -0,0 +1,133 @@
+"""Strict, versioned command envelopes and receipt contracts."""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from typing import Annotated, Literal, Self
+from uuid import UUID  # noqa: TC003 - Pydantic resolves these model fields at runtime.
+
+from pydantic import BaseModel, Field, StrictInt, StrictStr, ValidationInfo, field_validator, model_validator
+
+MAX_PAYLOAD_BYTES = 512 * 1024
+Identifier = Annotated[StrictStr, Field(min_length=1, max_length=255, pattern=r"^[A-Za-z0-9_.:@/-]+$")]
+PositiveInt = Annotated[StrictInt, Field(gt=0)]
+Sequence = Annotated[StrictInt, Field(ge=0)]
+
+
+class WireModel(BaseModel):
+    """Forbid silent field loss and freeze top-level wire values."""
+
+    model_config = {"extra": "forbid", "frozen": True, "validate_default": True}
+
+
+def validate_json(value: object, *, max_bytes: int | None = MAX_PAYLOAD_BYTES) -> object:
+    """Reject coercions and non-finite JSON, optionally bounding its encoded size."""
+    try:
+        encoded = json.dumps(value, ensure_ascii=False, allow_nan=False, separators=(",", ":")).encode("utf-8")
+    except (TypeError, ValueError, UnicodeError, RecursionError) as exc:
+        message = "Payload is not finite UTF-8 JSON"
+        raise ValueError(message) from exc
+    if max_bytes is not None and len(encoded) > max_bytes:
+        message = f"Payload exceeds {max_bytes // 1024} KiB"
+        raise ValueError(message)
+    pending = [value]
+    while pending:
+        item = pending.pop()
+        if type(item) is dict:
+            if any(not isinstance(key, str) for key in item):
+                message = "JSON object keys must be strings"
+                raise ValueError(message)
+            pending.extend(item.values())
+        elif type(item) is list:
+            pending.extend(item)
+        elif item is not None and type(item) not in (str, bool, int, float):
+            message = "Payload must contain JSON values only"
+            raise ValueError(message)
+    return value
+
+
+class CommandScope(WireModel):
+    """Initiating service client; project authorization belongs to the caller."""
+
+    client_id: Identifier
+
+
+class Command(WireModel):
+    """One versioned operation; participants persist only its domain effects."""
+
+    command_id: UUID
+    parent_command_id: UUID | None = None
+    command_type: Annotated[StrictStr, Field(pattern=r"^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$")]
+    command_revision: PositiveInt
+    payload: dict[str, object] = Field(repr=False)
+    occurred_at: datetime
+
+    @field_validator("payload", mode="before")
+    @classmethod
+    def check_payload(cls, value: object, info: ValidationInfo) -> object:
+        """Preserve the payload's JSON types and enforce its size limit."""
+        limit = None if info.data.get("command_type") == "work.execute.completed" else MAX_PAYLOAD_BYTES
+        return validate_json(value, max_bytes=limit)
+
+    @field_validator("occurred_at")
+    @classmethod
+    def check_time(cls, value: datetime) -> datetime:
+        """Require an explicit timezone and serialize instants in UTC."""
+        if value.tzinfo is None or value.utcoffset() is None:
+            message = "occurred_at requires a timezone"
+            raise ValueError(message)
+        return value.astimezone(UTC)
+
+    @model_validator(mode="after")
+    def check_parent(self) -> Self:
+        """Reject a command naming itself as its parent."""
+        if self.parent_command_id == self.command_id:
+            message = "A command cannot be its own parent"
+            raise ValueError(message)
+        return self
+
+
+class MessageEnvelope(WireModel):
+    """Participant identity around one logical command."""
+
+    message_id: UUID
+    message_type: Literal["command.submit"] = "command.submit"
+    command_id: UUID
+    sequence: Sequence = 0
+    source_id: Identifier
+    destination_id: Identifier
+    scope: CommandScope
+    command: Command
+
+    @model_validator(mode="after")
+    def check_identity(self) -> Self:
+        """Keep the envelope and nested command identity consistent."""
+        if self.command_id != self.command.command_id:
+            message = "Envelope command_id must match command.command_id"
+            raise ValueError(message)
+        return self
+
+
+class ResourceReference(WireModel):
+    """Safe reference from a command to a participant-owned resource."""
+
+    kind: Identifier
+    resource_id: UUID
+    resource_key: UUID | None = None
+    revision: PositiveInt | None = None
+
+
+class CapabilitiesRead(WireModel):
+    """Command revisions installed by this participant."""
+
+    protocol_revision: Literal[1] = 1
+    commands: dict[str, list[int]]
+
+
+class TransportReceipt(WireModel):
+    """Receipt of a handled request, without a persisted command record."""
+
+    received: Literal[True] = True
+    message_id: UUID
+    resource: ResourceReference | None = None

execution_plane_client/registry.py

@@ -0,0 +1,35 @@
+"""In-memory registration of participant-owned handlers."""
+
+from execution_plane_client.catalog import CommandDefinition
+from execution_plane_client.errors import ProtocolConflict, UnsupportedCommand
+from execution_plane_client.handlers import CommandHandler
+from execution_plane_client.protocol import CapabilitiesRead
+
+
+class CommandRegistry[ContextT]:
+    """Map installed command revisions to exactly one handler."""
+
+    def __init__(self) -> None:
+        """Start without handlers or advertised capabilities."""
+        self._handlers: dict[tuple[str, int], CommandHandler[ContextT]] = {}
+
+    def register(self, definition: CommandDefinition, handler: CommandHandler[ContextT]) -> None:
+        """Reject duplicate registrations."""
+        key = (definition.command_type, definition.revision)
+        if key in self._handlers:
+            raise ProtocolConflict
+        self._handlers[key] = handler
+
+    def get(self, command_type: str, revision: int) -> CommandHandler[ContextT]:
+        """Reject commands the participant cannot handle."""
+        try:
+            return self._handlers[command_type, revision]
+        except KeyError:
+            raise UnsupportedCommand from None
+
+    def capabilities(self) -> CapabilitiesRead:
+        """Advertise only installed revisions."""
+        commands: dict[str, list[int]] = {}
+        for name, revision in sorted(self._handlers):
+            commands.setdefault(name, []).append(revision)
+        return CapabilitiesRead(commands=commands)

execution_plane_client-0.1.5.dist-info/METADATA

@@ -0,0 +1,79 @@
+Metadata-Version: 2.5
+Name: execution-plane-client
+Version: 0.1.5
+Summary: Shared execution-plane command contracts and handler registry
+License-Expression: Apache-2.0
+License-File: LICENSE
+Requires-Python: <3.15,>=3.12
+Requires-Dist: pydantic>=2.0.0
+Description-Content-Type: text/markdown
+
+# Execution Plane Client
+
+Shared Pydantic command contracts, command catalog, in-memory handler registry
+and a generic handler protocol. No HTTP router, network client, persistence,
+authentication implementation or EP imports are included.
+
+Participants register their own handlers. EP implements command submission and
+resource queries; the caller handles `work.execute.completed` using this same
+protocol. Commands have no persisted status or child history. A receipt confirms
+that the domain handler returned, not that asynchronous resource work is complete.
+
+## Constructing messages
+
+Instantiate a typed command and call `to_message()`; the command supplies its
+wire type and revision and builds the envelope:
+
+```python
+from uuid import uuid4
+
+from execution_plane_client.commands.clusters import ClusterRegister
+
+message = ClusterRegister(
+    resource_key=uuid4(),
+    desired_revision=1,
+    name="workers",
+    endpoint="https://cluster.example",
+    namespace="execution-plane",
+    credential_ref=uuid4(),
+).to_message(
+    source_id="syntara-orchestration",
+    destination_id="execution-plane",
+    client_id="syntara-orchestration",
+)
+
+body = message.model_dump(mode="json")  # Send using your application's HTTP client.
+```
+
+Every concrete command supports this method, including `ClusterDelete` and
+`TargetDelete`. Partial updates serialize only supplied fields, retaining explicit
+nulls and placement discriminators without resetting omitted configuration.
+
+By default, each call generates a command UUID and UTC timestamp; `message_id`
+defaults to that command UUID. Keep the returned message for retries. To rebuild
+it from existing domain state, pass `command_id` and `occurred_at` explicitly,
+plus `message_id` if it differs. `parent_command_id` and `sequence` are optional;
+`Completion` requires a parent work command UUID. Source, destination and client
+scope are always supplied by the caller; the helper does not authenticate them.
+
+## Handling messages
+
+After parsing a `MessageEnvelope`, validate it through the catalog and pass the
+returned typed payload to the registered handler:
+
+```python
+payload = catalog.validate(message)
+handler = registry.get(message.command.command_type, message.command.command_revision)
+result = await handler.handle(message, payload, context)
+```
+
+Handlers implement `handle(message, payload, context)`. The catalog selects the
+payload model by command type and revision, validates it and checks required
+parent correlation. Handlers narrow the payload to their supported command
+types without parsing the raw dictionary again. The original envelope remains
+available for identity and correlation; partial-update payloads retain which
+fields were supplied. Authentication, authorization and domain-state validation
+(including validation after merging a patch) remain participant responsibilities.
+
+Build with `uv build src/execution_plane_client`. See the service's integration
+documentation for command examples and the current HTTP authentication contract.

execution_plane_client-0.1.5.dist-info/RECORD

@@ -0,0 +1,19 @@
+execution_plane_client/__init__.py,sha256=B_1B86MgamC9arJ1IjoZ_pdMg6oRU-1dyqmOtlQUrGY,75
+execution_plane_client/_version.py,sha256=MYViowQy3gBKIlctXQ6CgExkQCBPcL8ycJEVEexVzdI,520
+execution_plane_client/catalog.py,sha256=xVWRTDHtykjqWfDvhA-cDZgxPZQPBA9doynn0G0Wazg,2420
+execution_plane_client/errors.py,sha256=FQrlqkbWuWUYyIYM6x3Y-PPOuuVW8nq-v6ZQ6tBSils,313
+execution_plane_client/handlers.py,sha256=mHSzEdbDzy8JnUM4SqM0zYR9cen1pWEwFSJ_MKOHAOI,788
+execution_plane_client/protocol.py,sha256=XQf_REdMj_V2tRt4Q_lJ40vCkjz_Apc_pW30tVZ27Nw,4847
+execution_plane_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+execution_plane_client/registry.py,sha256=qJbHm1Y9bdCAsc_XODHXmJahHX-X6SlFzW-LjBcIdDw,1503
+execution_plane_client/commands/__init__.py,sha256=NgNbTP525RcOy7WKS0CBXNc3Ym1zpbJ3U2ooxYev0vY,1041
+execution_plane_client/commands/base.py,sha256=daf83pxxWWuFz7mRwj0xodldALaqBRJVvWe54Los6yw,2486
+execution_plane_client/commands/clusters.py,sha256=B_wSi6vG2pco_gx9vhXsZjl-nQxZaE-Q2vNQYD9qOJU,3784
+execution_plane_client/commands/control.py,sha256=oO5d6TCCXoZs6xRq9GA6IDr8wYbwL8auMXslQu2laYg,1199
+execution_plane_client/commands/credentials.py,sha256=KsBkOKgRndZ-E7fZ5FQzHhp0ulwzJeoesgvtJ1EjTzs,779
+execution_plane_client/commands/targets.py,sha256=Q2zoQWwkDsERxsUM4i6WrIlJXFaCLm3WJFRNMjQ1j8c,5733
+execution_plane_client/commands/work.py,sha256=21939Oe2jCuQ60JgrGZcg6S-GMZ_ipFc_mmx5PQN7ds,1455
+execution_plane_client-0.1.5.dist-info/METADATA,sha256=JrmtdfOWrGYUrA34XmTKu5LHWPzAtEeYOJ0InhuzAvE,3310
+execution_plane_client-0.1.5.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+execution_plane_client-0.1.5.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+execution_plane_client-0.1.5.dist-info/RECORD,,

execution_plane_client-0.1.5.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

execution_plane_client-0.1.5.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.