feat(cloud): add targeted task governance foundation

packages/cloud-platform/cloud/governance.py

@@ -0,0 +1,61 @@
+"""Durable Cloud-side submission and Host governance policies."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+
+
+class TaskSubmissionPolicyError(PermissionError):
+    """Raised when a human user's policy disallows a task submission."""
+
+
+@dataclass(frozen=True)
+class UserSubmissionPolicy:
+    user_id: str
+    revision: int
+    submission_enabled: bool
+    allowed_host_ids: tuple[str, ...] | None
+    allowed_device_targets: tuple[tuple[str, str], ...] | None
+    updated_at: datetime
+
+
+@dataclass(frozen=True)
+class HostGovernancePolicy:
+    host_id: str
+    revision: int
+    self_submission_enabled: bool
+    max_active_tasks: int | None
+    daily_token_budget: int | None
+    updated_at: datetime
+
+
+def enforce_user_submission_policy(
+    policy: UserSubmissionPolicy | None,
+    *,
+    target_host_id: str | None,
+    target_device_id: str | None,
+) -> None:
+    if policy is None:
+        return
+    if not policy.submission_enabled:
+        raise TaskSubmissionPolicyError("task submission is disabled for this user")
+    restricted = (
+        policy.allowed_host_ids is not None
+        or policy.allowed_device_targets is not None
+    )
+    if not restricted:
+        return
+    if target_host_id is None:
+        raise TaskSubmissionPolicyError("an explicit permitted target is required")
+    if (
+        policy.allowed_host_ids is not None
+        and target_host_id not in policy.allowed_host_ids
+    ):
+        raise TaskSubmissionPolicyError("target host is not permitted")
+    if policy.allowed_device_targets is not None:
+        if target_device_id is None or (
+            target_host_id,
+            target_device_id,
+        ) not in policy.allowed_device_targets:
+            raise TaskSubmissionPolicyError("target device is not permitted")