genesis-sandbox-client-python 0.1.0__py3-none-any.whl

genesis_sandbox_client/types.py

@@ -0,0 +1,150 @@
+"""Common types and constants shared by both sync and async session helpers."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import ProtocolError
+
+SESSION_TTL: int = 300
+JOB_TIMEOUT: int = 60
+
+# 内置心跳（类 Eureka Heartbeat）默认参数：
+# RENEW_INTERVAL 必须 < 服务端 lease_timeout / 2，保证单次续期失败仍有重试余量。
+RENEW_INTERVAL: int = 30
+RENEW_EXTEND: int = 90
+
+
+@dataclass
+class SandboxOptions:
+    """Configuration for a session-backed SandboxSession helper."""
+
+    profile: str | None = None
+    hints: list[str] | None = None
+    strict: bool = False
+    description: str | None = None
+    resolution_id: str | None = None
+    workspace_id: str | None = None
+    # 默认执行环境变量：随每次 exec 请求下发（会话创建协议拒绝持久 env 字段）；
+    # 与单次 run/run_async 的 env 合并，单次调用优先。
+    env: dict[str, str] | None = None
+    metadata: dict[str, str] = field(default_factory=dict)
+    ttl_seconds: int = SESSION_TTL
+    workspace_retention: str | None = None
+    workspace_ttl_seconds: int | None = None
+    idempotency_key: str | None = None
+    heartbeat: bool = True
+    renew_interval: int = RENEW_INTERVAL
+    renew_extend: int = RENEW_EXTEND
+
+    def __post_init__(self) -> None:
+        if self.profile and self.hints:
+            raise ValueError("profile and hints are mutually exclusive")
+        if self.resolution_id and (self.profile or self.hints):
+            raise ValueError("resolution_id and environment selector are mutually exclusive")
+        if self.ttl_seconds <= 0:
+            raise ValueError("ttl_seconds must be positive")
+        if self.workspace_retention not in (None, "ttl", "explicit_delete"):
+            raise ValueError("workspace_retention must be 'ttl' or 'explicit_delete'")
+        if self.workspace_retention == "ttl" and not self.workspace_ttl_seconds:
+            raise ValueError("workspace_ttl_seconds is required for ttl retention")
+        if self.renew_interval < 0 or self.renew_extend < 0:
+            raise ValueError("heartbeat intervals cannot be negative")
+
+
+@dataclass
+class EffectiveEnvironment:
+    """Resolved environment information returned by the server.
+
+    Present in responses to CreateSession, SubmitJob, ExecSession, and Resolve.
+    Answers: what environment was selected, why, and whether it was degraded.
+    """
+
+    profile_name: str = ""
+    profile_revision: str = ""
+    selection_mode: str = ""  # "profile" or "auto"
+    selection_reason: list[str] = field(default_factory=list)
+    capabilities: list[str] = field(default_factory=list)
+    degraded: bool = False
+
+
+@dataclass
+class ExecResult:
+    """Execution result from a session or job command."""
+
+    exit_code: int
+    stdout: str
+    stderr: str
+    error_code: str = ""
+    stdout_truncated: bool = False
+    stderr_truncated: bool = False
+    effective_environment: EffectiveEnvironment | None = None
+
+    def ok(self) -> bool:
+        # 与 Go SDK 对齐：取消/超时等异常终止会置 error_code（如 EXEC_CANCELLED），
+        # 即使 exit_code 为 0 也不是成功执行。
+        return self.exit_code == 0 and not self.error_code
+
+    def __repr__(self) -> str:
+        preview = self.stdout[:60].replace("\n", "\\n")
+        ellipsis = "…" if len(self.stdout) > 60 else ""
+        return f"ExecResult(exit_code={self.exit_code}, error_code={self.error_code!r}, stdout={preview!r}{ellipsis})"
+
+
+@dataclass(frozen=True)
+class SSEEvent:
+    """One Server-Sent Event from a Job or Session exec log stream."""
+
+    id: str = ""
+    event: str = "message"
+    data: str = ""
+
+    def json(self) -> Any:
+        """Decode ``data`` as JSON."""
+        return json.loads(self.data)
+
+
+@dataclass(frozen=True)
+class CancelReceipt:
+    """取消回执：区分「接受」与「停止确认」。
+
+    服务端 :cancel 在确认停止后才返回终态 ExecRecord（5 秒内联等待，超时以错误
+    表达停止未确认）；本类型把回执映射为稳定 outcome：
+
+    - ``"accepted"``：取消已被接受，但回执仍非终态，停止未确认。
+    - ``"already_terminal"``：执行先于取消完成，以实际终态为准，迟到取消不覆盖。
+    - ``"stop_confirmed"``：取消导致 cancelled/timed_out 终态，停止已确认。
+    - ``"stop_unknown"``：终态没有明确物理停止证据；禁止回收或直接重放。
+      传输失败另外抛 ``ExecRecoveryError(phase="cancel")``，进入核对流程。
+
+    ``stop_confirmed`` 是资源回收安全门禁，只使用服务端明确布尔事实。
+    """
+
+    exec_id: str
+    outcome: str
+    status: str = ""
+    stop_confirmed: bool = False
+    record: dict[str, Any] | None = None
+
+    @classmethod
+    def from_record(cls, exec_id: str, record: dict[str, Any] | None) -> CancelReceipt:
+        """Map a :cancel ExecRecord response onto the cancel outcome taxonomy."""
+        if not isinstance(record, dict) or record.get("exec_id") != exec_id:
+            raise ProtocolError("cancel receipt original execution identity mismatch")
+        if "stop_confirmed" in record and not isinstance(record["stop_confirmed"], bool):
+            raise ProtocolError("cancel receipt physical stop evidence must be boolean")
+        status = str((record or {}).get("status") or "")
+        stopped = (record or {}).get("stop_confirmed") is True
+        if status not in {"queued", "running", "succeeded", "failed", "cancelled", "timed_out", "interrupted"}:
+            raise ProtocolError("cancel receipt status is invalid")
+        if stopped and status in {"queued", "running"}:
+            raise ProtocolError("nonterminal execution cannot confirm physical stop")
+        if status in ("cancelled", "timed_out"):
+            return cls(exec_id, "stop_confirmed" if stopped else "stop_unknown", status, stopped, record)
+        if status in ("succeeded", "failed"):
+            return cls(exec_id, "already_terminal" if stopped else "stop_unknown", status, stopped, record)
+        if status == "interrupted":
+            return cls(exec_id, "already_terminal" if stopped else "stop_unknown", status, stopped, record)
+        return cls(exec_id, "accepted", status, False, record)

genesis_sandbox_client/view_preparation.py

@@ -0,0 +1,64 @@
+"""原工作区准备回执校验；未知结果只能查询，不能隐式重放。"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from .errors import ProtocolError
+
+
+def preparation_request(operation_id: str, request_digest: str) -> dict[str, str]:
+    if not isinstance(operation_id, str) or not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._:-]{0,127}", operation_id):
+        raise ValueError("invalid preparation operation identity")
+    if not isinstance(request_digest, str) or not re.fullmatch(r"[a-f0-9]{64}", request_digest):
+        raise ValueError("invalid preparation request digest")
+    return {"operation_id": operation_id, "request_digest": request_digest}
+
+
+def preparation_receipt(value: Any, session_id: str, operation_id: str, request_digest: str) -> dict[str, Any]:
+    fields = {"operation_id", "request_digest", "status", "session_id", "workspace_id", "sandbox_id",
+              "profile_revision", "tenant_id", "principal_id", "user_id", "facts"}
+    if (not isinstance(value, dict) or set(value) - fields or fields - {"facts"} - set(value)
+            or value.get("session_id") != session_id or value.get("operation_id") != operation_id
+            or value.get("request_digest") != request_digest or value.get("status") not in {"prepared", "unknown"}):
+        raise ProtocolError("preparation receipt does not match original request")
+    if not isinstance(value["sandbox_id"], str):
+        raise ProtocolError("preparation sandbox identity must be a string")
+    for key in ("workspace_id", "tenant_id", "principal_id", "user_id", "profile_revision"):
+        if not isinstance(value.get(key), str) or not value[key]:
+            raise ProtocolError("preparation receipt lacks owner or resource identity")
+    if value["status"] == "unknown":
+        if "facts" in value:
+            raise ProtocolError("unknown preparation cannot contain confirmed facts")
+    else:
+        facts = value.get("facts")
+        fact_fields = {"session_id", "workspace_id", "profile_revision", "os", "arch", "image_digest",
+                       "runtime_versions", "runtime_executables", "mechanisms", "resource_limits",
+                       "network_mode", "view_state", "readonly_regions"}
+        if (not isinstance(value.get("sandbox_id"), str) or not value["sandbox_id"]
+                or not isinstance(value.get("profile_revision"), str) or not value["profile_revision"]
+                or not isinstance(facts, dict) or facts.get("session_id") != session_id
+                or facts.get("workspace_id") != value["workspace_id"]
+                or facts.get("profile_revision") != value["profile_revision"]
+                or set(facts) - fact_fields or facts.get("view_state") != "prepared"):
+            raise ProtocolError("confirmed preparation lacks bound runtime facts")
+        for key in ("os", "arch", "image_digest", "network_mode"):
+            if not isinstance(facts.get(key), str) or not facts[key]:
+                raise ProtocolError("preparation facts lack required runtime fields")
+        for key in ("runtime_versions", "runtime_executables"):
+            values = facts.get(key)
+            if not isinstance(values, dict) or any(not isinstance(name, str) or not name
+                    or not isinstance(item, str) or not item for name, item in values.items()):
+                raise ProtocolError("preparation runtime facts have invalid values")
+        limits = facts.get("resource_limits")
+        if not isinstance(limits, dict) or any(not isinstance(name, str) or not name
+                or type(item) is not int or not 1 <= item <= 2**53 - 1 for name, item in limits.items()):
+            raise ProtocolError("preparation resource facts have invalid values")
+        for key in ("mechanisms", "readonly_regions"):
+            if key == "readonly_regions" and key not in facts:
+                continue
+            values = facts.get(key)
+            if not isinstance(values, list) or any(not isinstance(item, str) or not item for item in values):
+                raise ProtocolError("preparation mechanism facts have invalid values")
+    return value

genesis_sandbox_client/workspace_client.py

@@ -0,0 +1,180 @@
+"""工作区资源、共享存储查询和视图控制；复用 Client 的认证与传输预算。"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+from urllib.parse import quote
+
+from .errors import APIError, ProtocolError
+from .execution_governance import maintenance_proof, maintenance_query
+from .json_codec import loads as decode_response_json
+from .view_preparation import preparation_receipt, preparation_request
+from .workspace_purge import purge_receipt, session_ownership
+
+
+def _binding(payload: dict[str, Any]) -> dict[str, Any]:
+    if not isinstance(payload, dict) or set(payload) - {"mode", "storage_ref", "resource_id", "binding_version"}:
+        raise ValueError("workspace_binding contains unknown fields")
+    mode = payload.get("mode")
+    if mode == "isolated":
+        if set(payload) != {"mode"}:
+            raise ValueError("isolated binding cannot reference shared storage")
+    elif mode == "shared":
+        if set(payload) != {"mode", "storage_ref", "resource_id", "binding_version"}:
+            raise ValueError("shared binding requires resource identity and version")
+        for key in ("storage_ref", "resource_id"):
+            value = payload[key]
+            if not isinstance(value, str) or not value or len(value) > 128 or any(
+                not (char.isascii() and (char.isalnum() or char in "-_.")) for char in value
+            ) or value in {".", ".."}:
+                raise ValueError("shared binding requires opaque resource identity")
+        version = payload["binding_version"]
+        if isinstance(version, bool) or not isinstance(version, int) or not 0 < version <= 9007199254740991:
+            raise ValueError("shared binding version must be a positive safe integer")
+    else:
+        raise ValueError("invalid workspace binding mode")
+    return dict(payload)
+
+
+class WorkspaceClientMixin:
+    def query_workspace_maintenance_proof(self, workspace_id: str, *, context: dict[str, Any],
+                                          operation_id: str, source_identity: str,
+                                          claim_digest: str) -> dict[str, Any]:
+        query = maintenance_query(workspace_id, context, operation_id, source_identity, claim_digest)
+        result = self._request("POST", f"/v1/workspaces/{quote(workspace_id, safe='')}/maintenance-proof:query", query)
+        return maintenance_proof(result, query)
+
+    def stat_session_file(self, session_id: str, path: str) -> dict[str, Any]:
+        target = f"/v1/sessions/{quote(session_id, safe='')}/files:stat?path={quote(path, safe='')}"
+        return self._request("GET", target)
+
+    def mkdir_session_dir(self, session_id: str, path: str) -> dict[str, Any]:
+        target = f"/v1/sessions/{quote(session_id, safe='')}/dirs?path={quote(path, safe='')}"
+        return self._request("POST", target)
+
+    def _request(self, *args: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    def _raw_request(self, *args: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    def set_session_file_executable(self, session_id: str, path: str, executable: bool,
+                                    if_match: str | None = None, expected_executable: bool | None = None) -> dict[str,
+                                        Any]:
+        if not isinstance(executable, bool) or (
+            expected_executable is not None and not isinstance(expected_executable, bool)
+        ):
+            raise ValueError("executable permissions must be booleans")
+        payload: dict[str, Any] = {"executable": executable}
+        if expected_executable is not None:
+            payload["expected_executable"] = expected_executable
+        target = f"/v1/sessions/{quote(session_id, safe='')}/files:executable?path={quote(path, safe='')}"
+        with self._raw_request("PATCH", target, data=json.dumps(payload).encode("utf-8"),
+            content_type="application/json",
+                               extra_headers={"If-Match": if_match} if if_match else None) as response:
+            receipt = response.read(16385)
+        if len(receipt) > 16384:
+            raise ProtocolError("executable permission receipt exceeds byte budget")
+        result = decode_response_json(receipt)
+        if not isinstance(result, dict) or not isinstance(result.get("executable"), bool):
+            raise ProtocolError("executable permission receipt must contain an executable fact")
+        return result
+
+    def create_workspace(self, workspace_id: str | None = None, metadata: dict[str, str] | None = None,
+                         ttl_seconds: int | None = None, quota_mb: int | None = None,
+                         workspace_binding: dict[str, Any] | None = None,
+                         retention_mode: str | None = None) -> dict[str, Any]:
+        payload: dict[str, Any] = {}
+        if workspace_id:
+            payload["workspace_id"] = workspace_id
+        if metadata:
+            payload["metadata"] = metadata
+        if ttl_seconds:
+            payload["ttl_seconds"] = int(ttl_seconds)
+        if quota_mb:
+            payload["quota_mb"] = int(quota_mb)
+        if retention_mode is not None:
+            if retention_mode not in {"ttl", "explicit_delete"}:
+                raise ValueError("invalid workspace retention mode")
+            payload["retention_mode"] = retention_mode
+        if workspace_binding is not None:
+            payload["workspace_binding"] = _binding(workspace_binding)
+        return self._request("POST", "/v1/workspaces", payload)
+
+    def get_workspace(self, workspace_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/v1/workspaces/{quote(workspace_id, safe='')}")
+
+    def delete_workspace(self, workspace_id: str) -> dict[str, Any] | None:
+        return self._request("DELETE", f"/v1/workspaces/{quote(workspace_id, safe='')}")
+
+    def inspect_shared_storage_resource(self, storage_ref: str, resource_id: str) -> dict[str, Any]:
+        _binding({"mode": "shared", "storage_ref": storage_ref, "resource_id": resource_id, "binding_version": 1})
+        return self._request("GET", f"/v1/storage-resources/{quote(storage_ref, safe='')}/{quote(resource_id,
+            safe='')}")
+
+    def get_workspace_view(self, session_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/v1/sessions/{quote(session_id, safe='')}/workspace-view")
+
+    def get_session_history(self, session_id: str) -> dict[str, Any]:
+        return self._request("GET", f"/v1/sessions/{quote(session_id, safe='')}/history")
+
+    def get_session_ownership(self, session_id: str) -> dict[str, Any]:
+        return session_ownership(self._request("GET", f"/v1/sessions/{quote(session_id, safe='')}/ownership"),
+            session_id)
+
+    def purge_session_workspace(self, session_id: str, *, operation_id: str, request_digest: str) -> dict[str, Any]:
+        payload = preparation_request(operation_id, request_digest)
+        result = self._request("POST", f"/v1/sessions/{quote(session_id, safe='')}/workspace:purge", payload)
+        return purge_receipt(result, session_id, operation_id, request_digest)
+
+    def lookup_workspace_purge(self, session_id: str, *, operation_id: str, request_digest: str) -> dict[str,
+        Any] | None:
+        preparation_request(operation_id, request_digest)
+        target = (f"/v1/sessions/{quote(session_id, safe='')}/workspace/purges/"
+                  f"{quote(operation_id, safe='')}?request_digest={request_digest}")
+        try:
+            result = self._request("GET", target)
+        except APIError as error:
+            if error.status_code == 404:
+                return None
+            raise
+        return purge_receipt(result, session_id, operation_id, request_digest)
+
+    def lookup_storage_purge(self, workspace_id: str, *, operation_id: str, request_digest: str) -> dict[str,
+        Any] | None:
+        preparation_request(operation_id, request_digest)
+        target = (f"/v1/workspaces/{quote(workspace_id, safe='')}/purges/"
+                  f"{quote(operation_id, safe='')}?request_digest={request_digest}")
+        try:
+            result = self._request("GET", target)
+        except APIError as error:
+            if error.status_code == 404:
+                return None
+            raise
+        receipt = purge_receipt(result, None, operation_id, request_digest)
+        if receipt["workspace_id"] != workspace_id:
+            raise ProtocolError("original storage purge workspace mismatch")
+        return receipt
+
+    def prepare_workspace_view(self, session_id: str, *, operation_id: str, request_digest: str) -> dict[str, Any]:
+        payload = preparation_request(operation_id, request_digest)
+        result = self._request("POST", f"/v1/sessions/{quote(session_id, safe='')}/workspace-view?action=prepare",
+            payload)
+        return preparation_receipt(result, session_id, operation_id, request_digest)
+
+    def lookup_workspace_preparation(self, session_id: str, *, operation_id: str, request_digest: str) -> dict[str,
+        Any] | None:
+        preparation_request(operation_id, request_digest)
+        target = (f"/v1/sessions/{quote(session_id, safe='')}/workspace-view/preparations/"
+                  f"{quote(operation_id, safe='')}?request_digest={request_digest}")
+        try:
+            result = self._request("GET", target)
+        except APIError as error:
+            if error.status_code == 404:
+                return None
+            raise
+        return preparation_receipt(result, session_id, operation_id, request_digest)
+
+    def seal_workspace_view(self, session_id: str) -> dict[str, Any]:
+        return self._request("POST", f"/v1/sessions/{quote(session_id, safe='')}/workspace-view?action=seal")

genesis_sandbox_client/workspace_lifecycle.py

@@ -0,0 +1,154 @@
+"""可信父任务的持续存储保活；不续期或恢复计算实例。"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from datetime import UTC, datetime, timedelta
+from typing import Any
+from urllib.parse import quote
+
+from .errors import ProtocolError
+
+
+def _operation_id(value: str) -> str:
+    if not isinstance(value, str) or not value or len(value) > 128 or value in {".", ".."} or any(
+        not (char.isascii() and (char.isalnum() or char in "_.-")) for char in value
+    ):
+        raise ValueError("operation_id must be an opaque identifier")
+    return value
+
+
+def _integer(value: int, name: str, minimum: int, maximum: int) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or not minimum <= value <= maximum:
+        raise ValueError(f"{name} is outside the integer budget")
+    return value
+
+
+def _timestamp(value: Any) -> datetime:
+    if not isinstance(value, str) or not re.fullmatch(
+            r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,6})?(?:Z|[+-]\d{2}:\d{2})", value):
+        raise ValueError("lifecycle time must be an aware microsecond RFC3339 timestamp")
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        raise ValueError("lifecycle time must be timezone-aware")
+    return parsed.astimezone(UTC)
+
+
+def workspace_lifecycle_request_digest(payload: dict[str, Any]) -> str:
+    """固定六字段规范化摘要，供独立消费者核对原持久意图。"""
+    fields = {"expected_revision", "hold_seconds", "operation_id", "retention_seconds", "state", "terminal_at"}
+    if not isinstance(payload, dict) or set(payload) - fields or not {"expected_revision", "operation_id",
+        "state"} <= set(payload):
+        raise ValueError("invalid lifecycle request fields")
+    _operation_id(payload["operation_id"])
+    _integer(payload["expected_revision"], "expected_revision", 0, 9007199254740990)
+    hold = _integer(payload.get("hold_seconds", 0), "hold_seconds", 0, 86400)
+    retention = _integer(payload.get("retention_seconds", 0), "retention_seconds", 0, 30 * 86400)
+    terminal = payload.get("terminal_at")
+    if not isinstance(payload["state"], str):
+        raise ValueError("invalid lifecycle state")
+    if payload["state"] == "terminal":
+        if hold or not retention or terminal is None:
+            raise ValueError("invalid terminal lifecycle")
+    elif payload["state"] not in {"active", "paused"} or terminal is not None or retention:
+        raise ValueError("invalid nonterminal lifecycle")
+    if terminal is not None:
+        parsed = _timestamp(terminal)
+        terminal = parsed.astimezone(UTC).isoformat(timespec="microseconds").replace("+00:00", "Z")
+    canonical = {
+        "expected_revision": payload["expected_revision"], "hold_seconds": payload.get("hold_seconds", 0),
+        "operation_id": payload["operation_id"], "retention_seconds": payload.get("retention_seconds", 0),
+        "state": payload["state"], "terminal_at": terminal,
+    }
+    return hashlib.sha256(json.dumps(canonical, sort_keys=True, ensure_ascii=False, separators=(",",
+        ":")).encode("utf-8")).hexdigest()
+
+
+def _receipt(value: Any, workspace_id: str, operation_id: str) -> dict[str, Any]:
+    keys = {"operation_id", "workspace_id", "revision", "state", "deadline", "terminal_at", "request_digest"}
+    if not isinstance(value, dict) or set(value) - keys or not keys - {"terminal_at"} <= set(value):
+        raise ProtocolError("invalid lifecycle receipt fields")
+    if value["workspace_id"] != workspace_id or value["operation_id"] != operation_id:
+        raise ProtocolError("lifecycle receipt identity mismatch")
+    revision = value["revision"]
+    if isinstance(revision, bool) or not isinstance(revision, int) or not 1 <= revision <= 9007199254740991:
+        raise ProtocolError("invalid lifecycle revision")
+    digest = value["request_digest"]
+    if not isinstance(digest, str) or len(digest) != 64 or any(c not in "0123456789abcdef" for c in digest):
+        raise ProtocolError("invalid lifecycle request digest")
+    if not isinstance(value["state"], str) or value["state"] not in {"active", "paused", "terminal"}:
+        raise ProtocolError("invalid lifecycle state")
+    try:
+        deadline = _timestamp(value["deadline"])
+        if deadline.tzinfo is None:
+            raise ValueError
+    except (ValueError, TypeError, AttributeError) as error:
+        raise ProtocolError("invalid lifecycle deadline") from error
+    if (value["state"] == "terminal") != (value.get("terminal_at") is not None):
+        raise ProtocolError("lifecycle terminal identity mismatch")
+    if value["state"] == "terminal":
+        try:
+            terminal = _timestamp(value["terminal_at"])
+            if terminal.tzinfo is None or terminal > deadline:
+                raise ValueError
+        except (ValueError, TypeError, AttributeError) as error:
+            raise ProtocolError("invalid lifecycle terminal time") from error
+    return value
+
+
+class WorkspaceLifecycleClientMixin:
+    def _request(self, *args: Any, **kwargs: Any) -> Any:
+        raise NotImplementedError
+
+    def control_workspace_lifecycle(
+        self, workspace_id: str, operation_id: str, expected_revision: int, state: str,
+        *, hold_seconds: int = 0, terminal_at: datetime | None = None, retention_seconds: int = 0,
+    ) -> dict[str, Any]:
+        _operation_id(operation_id)
+        _integer(expected_revision, "expected_revision", 0, 9007199254740990)
+        _integer(hold_seconds, "hold_seconds", 0, 86400)
+        _integer(retention_seconds, "retention_seconds", 0, 30 * 86400)
+        payload: dict[str, Any] = {
+            "operation_id": operation_id, "expected_revision": expected_revision, "state": state,
+        }
+        if state in {"active", "paused"}:
+            if terminal_at is not None or retention_seconds:
+                raise ValueError("non-terminal lifecycle cannot carry terminal retention")
+            payload["hold_seconds"] = hold_seconds
+        elif state == "terminal":
+            if hold_seconds or retention_seconds == 0 or not isinstance(terminal_at,
+                datetime) or terminal_at.tzinfo is None:
+                raise ValueError("terminal lifecycle requires an aware terminal_at and bounded retention")
+            payload["terminal_at"] = terminal_at.astimezone(UTC).isoformat().replace("+00:00", "Z")
+            payload["retention_seconds"] = retention_seconds
+        else:
+            raise ValueError("invalid lifecycle state")
+        # 传输层变更请求仅发一次；未知副作用必须改用原 operation_id 查询。
+        result = self._request("POST", f"/v1/workspaces/{quote(workspace_id, safe='')}/lifecycle", payload)
+        result = _receipt(result, workspace_id, operation_id)
+        digest_ok = result["request_digest"] == workspace_lifecycle_request_digest(payload)
+        revision_ok = result["revision"] == expected_revision + 1
+        if not digest_ok or not revision_ok or result["state"] != state:
+            raise ProtocolError("lifecycle receipt differs from original intent")
+        if state == "terminal":
+            assert terminal_at is not None
+            if (_timestamp(result["terminal_at"]) != terminal_at
+                    or _timestamp(result["deadline"]) != terminal_at + timedelta(seconds=retention_seconds)):
+                raise ProtocolError("lifecycle receipt differs from parent terminal time or retention")
+        return result
+
+    def lookup_workspace_lifecycle(self, workspace_id: str, operation_id: str) -> dict[str, Any]:
+        _operation_id(operation_id)
+        result = self._request(
+            "GET", f"/v1/workspaces/{quote(workspace_id, safe='')}/lifecycle:lookup?operation_id={quote(operation_id,
+                safe='')}",
+        )
+        if not isinstance(result, dict) or set(result) != {"state", "receipt"}:
+            raise ProtocolError("invalid lifecycle lookup fields")
+        if result["state"] == "found":
+            _receipt(result["receipt"], workspace_id, operation_id)
+        elif result["state"] not in {"unknown", "history_expired"} or result["receipt"] is not None:
+            raise ProtocolError("invalid lifecycle lookup state")
+        return result

genesis_sandbox_client/workspace_purge.py

@@ -0,0 +1,26 @@
+"""原删除回执只承认完整身份，不把 404 或目录缺失当作成功。"""
+
+from typing import Any
+
+from .errors import ProtocolError
+
+
+def session_ownership(value: Any, session_id: str) -> dict[str, Any]:
+    fields = {"session_id", "workspace_id", "tenant_id", "principal_id", "user_id", "profile_revision"}
+    if (not isinstance(value, dict) or set(value) != fields
+            or any(not isinstance(value[key], str) or not value[key] for key in fields)
+            or value["session_id"] != session_id):
+        raise ProtocolError("original session ownership identity mismatch")
+    return value
+
+
+def purge_receipt(value: Any, session_id: str | None, operation_id: str, request_digest: str) -> dict[str, Any]:
+    fields = {"operation_id", "request_digest", "status", "session_id", "workspace_id",
+              "profile_revision", "tenant_id", "principal_id", "user_id"}
+    if (not isinstance(value, dict) or set(value) != fields
+            or any(not isinstance(value[key], str) or not value[key] for key in fields)
+            or value["status"] not in {"unknown", "purged"}
+            or (session_id is not None and value["session_id"] != session_id) or value["operation_id"] != operation_id
+            or value["request_digest"] != request_digest):
+        raise ProtocolError("original workspace purge receipt does not match the request")
+    return value