agentengine-sdk-python 0.8.2__py3-none-any.whl → 0.8.4__py3-none-any.whl

ksadk/resource_runtime/memory_provider.py

@@ -0,0 +1,318 @@
+"""Bound structured AICP MemoryProvider; asynchronous writes use a separate receipt path."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import threading
+import time
+from contextlib import contextmanager
+
+from pydantic import Field
+
+from ksadk.memory.adk.backends.sdk_ltm_backend import SdkLTMBackend
+from ksadk.memory.models import (
+    CoreMemoryRequest,
+    MemoryCapabilities,
+    MemoryDeleteRequest,
+    MemoryDeleteResult,
+    MemoryRecord,
+    MemorySearchRequest,
+    MemorySearchResult,
+    UnsupportedMemoryOperation,
+)
+from ksadk.plugins.contracts import PluginContractModel
+from ksadk.resource_runtime.contracts import InvocationIdentity, ResourceConfig
+from ksadk.resource_runtime.errors import ResourceUpstreamAuthorizationError
+
+
+class MemoryQuery(PluginContractModel):
+    query: str = Field(strict=True, max_length=16000)
+
+
+class MemoryWrite(PluginContractModel):
+    content: str = Field(strict=True, min_length=1, max_length=8192)
+
+
+class MemoryStatusQuery(PluginContractModel):
+    operation_id: str = Field(strict=True, pattern=r"^[0-9a-f]{64}$")
+
+
+class MemoryRecordSelector(PluginContractModel):
+    memory_id: str = Field(strict=True, min_length=1, max_length=256)
+
+
+class MemoryUpdate(MemoryRecordSelector, MemoryWrite):
+    pass
+
+
+class AicpMemoryProvider:
+    """An explicit activation instance. Never resolves credentials or user IDs from env.
+
+    The caller supplies an admitted backend and identity. This search adapter does
+    not turn an asynchronous submission into the synchronous upsert contract.
+    """
+
+    def __init__(
+        self, config: ResourceConfig, identity: InvocationIdentity, backend: SdkLTMBackend
+    ):
+        if config.binding.resource.kind != "memory-instance":
+            raise ValueError("MemoryProvider requires a memory-instance binding")
+        if not backend.access_key or not backend.secret_key:
+            raise ValueError("MemoryProvider requires explicit signing credentials")
+        if (
+            backend._effective_memory_collection_id() != config.binding.resource.id
+            or backend.region != config.binding.resource.region
+        ):
+            raise ValueError("Memory backend does not match the resource binding")
+        self.config = config
+        self.identity = identity
+        self.partition = identity.memory_partition(config.binding.resource)
+        self._backend = backend
+        self._lock = threading.Lock()
+        self._observed_ids: dict[str, None] = {}
+        self._upstream_forbidden = False
+
+    @contextmanager
+    def _backend_call(self):
+        """Keep observed authorization failures sticky for this activation."""
+        with self._lock:
+            if self._upstream_forbidden:
+                raise ResourceUpstreamAuthorizationError()
+            self._backend.last_http_status = None
+            try:
+                yield
+            finally:
+                if self._backend.last_http_status in {401, 403}:
+                    self._upstream_forbidden = True
+                    self._observed_ids.clear()
+                    raise ResourceUpstreamAuthorizationError() from None
+
+    def capabilities(self) -> MemoryCapabilities:
+        # The SDK exposes a query operation but no advertised search-mode or CAS
+        # guarantee. Do not invent capabilities from the presence of a method.
+        return MemoryCapabilities(
+            semantic_search=False,
+            keyword_search=False,
+            metadata_filter=False,
+            versioned_update=False,
+            hard_delete=False,
+            ttl=False,
+            max_record_chars=8192,
+        )
+
+    def search(self, request: MemorySearchRequest) -> MemorySearchResult:
+        started = time.monotonic()
+
+        def result(status, records=None, error=None, truncated=False):
+            return MemorySearchResult(
+                status=status,
+                records=records or [],
+                error_code=error,
+                provider="aicp",
+                latency_ms=int((time.monotonic() - started) * 1000),
+                accounting_accuracy="estimated",
+                truncated_by_budget=truncated,
+            )
+
+        if request.scopes != [("user", self.partition)]:
+            return result("unauthorized", error="MEMORY_SCOPE_MISMATCH")
+        if request.filters or request.as_of or request.memory_types or request.min_score != 0:
+            return result("failed", error="MEMORY_SEARCH_POLICY_UNSUPPORTED")
+        if (
+            type(request.top_k) is not int
+            or not 1 <= request.top_k <= 64
+            or type(request.max_tokens) is not int
+            or not 0 <= request.max_tokens <= 100000
+            or not isinstance(request.query, str)
+            or len(request.query) > 16000
+        ):
+            return result("failed", error="MEMORY_SEARCH_ARGUMENTS_INVALID")
+        if request.max_tokens == 0:
+            return result("ok", truncated=True)
+        try:
+            with self._backend_call():
+                records = self._backend.search_records(
+                    self.partition, request.query, request.top_k, strict=True
+                )
+            projected = []
+            remaining = request.max_tokens
+            truncated = len(records) > request.top_k
+            for item in records[: request.top_k]:
+                if (
+                    item.user_id != self.partition
+                    or item.metadata.get("AgentUserId", self.partition) != self.partition
+                    or not item.memory_id
+                    or item.score is not None
+                    and not math.isfinite(item.score)
+                ):
+                    return result("failed", error="MEMORY_SEARCH_RESPONSE_INVALID")
+                content = item.content[:8192]
+                # Byte accounting is conservative for ordinary text tokenizers;
+                # accuracy remains explicitly estimated in the public result.
+                cost = len(content.encode("utf-8"))
+                if cost > remaining:
+                    truncated = True
+                    break
+                remaining -= cost
+                truncated |= len(content) != len(item.content)
+                projected.append(
+                    MemoryRecord(
+                        memory_id=item.memory_id,
+                        tenant_id=self.identity.tenant_ref,
+                        workspace_id="",
+                        scope="user",
+                        scope_id=self.partition,
+                        memory_type="unknown",
+                        content=content,
+                        summary=content,
+                        status="active",
+                        confidence=None,
+                        importance=None,
+                        valid_from="",
+                        valid_to="",
+                        expires_at="",
+                        source_session_id=item.session_id,
+                        source_event_ids=[],
+                        source_seq_range=None,
+                        content_hash="sha256:" + hashlib.sha256(content.encode()).hexdigest(),
+                        version=None,
+                        metadata={"bindingId": self.config.binding.id, "score": item.score},
+                        created_at=item.created_at or "",
+                        updated_at=item.updated_at or "",
+                    )
+                )
+            with self._lock:
+                for record in projected:
+                    self._observed_ids[record.memory_id] = None
+                while len(self._observed_ids) > 256:
+                    del self._observed_ids[next(iter(self._observed_ids))]
+            return result("ok", projected, truncated=truncated)
+        except ResourceUpstreamAuthorizationError:
+            return result("unauthorized", error="RESOURCE_FORBIDDEN")
+        except Exception:
+            return result("failed", error="MEMORY_SEARCH_FAILED")
+
+    def get(self, memory_id: str) -> MemoryRecord | None:
+        raise UnsupportedMemoryOperation("AICP does not expose a bound get-by-ID contract")
+
+    def submit(self, arguments: dict, *, operation_id: str) -> dict:
+        """Host-approved submission; each operation has a separate extraction session.
+
+        The broker supplies the durable operation ID, never a model parameter.
+        A transport acknowledgment proves acceptance only, not indexing or IDs.
+        """
+        request = MemoryWrite.model_validate(arguments)
+        if (
+            not request.content.strip()
+            or len(operation_id) != 64
+            or any(char not in "0123456789abcdef" for char in operation_id)
+        ):
+            raise ValueError("MEMORY_WRITE_ARGUMENTS_INVALID")
+        # AICP limits SessionId to 64 characters.  The broker operation ID is
+        # already a 64-character lowercase hex digest, so use it directly.
+        # Prefixing it made every real submission 73 characters long and the
+        # service rejected the write before extraction could start.
+        session_id = operation_id
+        event = json.dumps({"role": "user", "parts": [{"text": request.content}]})
+        with self._backend_call():
+            try:
+                accepted = self._backend.save_memory(
+                    self.partition, [event], session_id=session_id, flush=True, strict=True
+                )
+            except Exception:
+                accepted = False
+        return {
+            "status": "accepted_pending" if accepted else "unknown",
+            "operationId": operation_id,
+            "searchable": False,
+            "errorCode": None if accepted else "MEMORY_WRITE_UNKNOWN",
+        }
+
+    def extraction_status(self, arguments: dict) -> dict:
+        query = MemoryStatusQuery.model_validate(arguments)
+        with self._backend_call():
+            result = self._backend.get_extraction_status(
+                user_id=self.partition,
+                session_id=query.operation_id,
+            )
+        return {
+            "operationId": query.operation_id,
+            "extractionStatus": result.status,
+            "searchable": False,
+            "errorCode": result.error_code or None,
+        }
+
+    def mutate(self, operation: str, arguments: dict, *, operation_id: str) -> dict:
+        """Post-approval management of IDs observed in this bound user partition.
+
+        IDs are not authorization tokens: upstream receives the bound user on every
+        request. Restart requires fresh search. No CAS, hard deletion, or retry is
+        implied, and an ambiguous response permanently consumes the observed ID.
+        """
+        MemoryStatusQuery(operation_id=operation_id)
+        if operation == "update_memory":
+            query = MemoryUpdate.model_validate(arguments)
+            if not query.content.strip():
+                raise ValueError("MEMORY_WRITE_ARGUMENTS_INVALID")
+        elif operation == "delete_memory":
+            query = MemoryRecordSelector.model_validate(arguments)
+        else:
+            raise ValueError("Unsupported memory mutation")
+        reply = {
+            "operationId": operation_id,
+            "memoryId": query.memory_id,
+            "newMemoryId": "",
+            "status": "unknown",
+            "errorCode": "MEMORY_MUTATION_UNKNOWN",
+        }
+        with self._backend_call():
+            if query.memory_id not in self._observed_ids:
+                return {**reply, "status": "failed", "errorCode": "MEMORY_RECORD_NOT_OBSERVED"}
+            del self._observed_ids[query.memory_id]
+            try:
+                if operation == "update_memory":
+                    outcome = self._backend.update_memory(
+                        user_id=self.partition,
+                        memory_id=query.memory_id,
+                        content=query.content,
+                        strict=True,
+                    )
+                else:
+                    outcome = self._backend.delete_memory(
+                        user_id=self.partition,
+                        memory_id=query.memory_id,
+                        strict=True,
+                    )
+                expected = (
+                    {"updated"} if operation == "update_memory" else {"deleted", "already_absent"}
+                )
+                if outcome.ok and outcome.status in expected:
+                    new_id = outcome.new_memory_id if operation == "update_memory" else ""
+                    if not isinstance(new_id, str) or len(new_id) > 256:
+                        return reply
+                    if new_id:
+                        self._observed_ids[new_id] = None
+                    return {
+                        **reply,
+                        "status": "succeeded",
+                        "newMemoryId": new_id,
+                        "errorCode": None,
+                    }
+                if outcome.status == "not_found":
+                    return {**reply, "status": "failed", "errorCode": "MEMORY_RECORD_NOT_FOUND"}
+            except Exception:
+                pass
+        return reply
+
+    def upsert(self, record: MemoryRecord, *, expected_version: int | None) -> MemoryRecord:
+        raise UnsupportedMemoryOperation(
+            "AICP writes require an approved asynchronous operation receipt"
+        )
+
+    def delete(self, request: MemoryDeleteRequest) -> MemoryDeleteResult:
+        raise UnsupportedMemoryOperation("AICP deletion requires an approved operation receipt")
+
+    def list_core(self, request: CoreMemoryRequest) -> list[MemoryRecord]:
+        raise UnsupportedMemoryOperation("AICP does not expose core-memory blocks")

ksadk/resource_runtime/memory_receipts.py

@@ -0,0 +1,34 @@
+"""Bounded memory mutation metadata; never includes the stored memory body."""
+
+from typing import Literal
+
+from pydantic import Field, model_validator
+
+from ksadk.plugins.contracts import PluginContractModel
+
+
+class MemoryMutationReceipt(PluginContractModel):
+    operation_id: str = Field(strict=True, pattern=r"^[0-9a-f]{64}$")
+    memory_id: str = Field(strict=True, min_length=1, max_length=256)
+    new_memory_id: str = Field(default="", strict=True, max_length=256)
+    status: Literal["succeeded", "failed", "unknown"]
+    error_code: (
+        Literal["MEMORY_MUTATION_UNKNOWN", "MEMORY_RECORD_NOT_OBSERVED", "MEMORY_RECORD_NOT_FOUND"]
+        | None
+    )
+
+    @model_validator(mode="after")
+    def consistent_result(self):
+        if self.status == "succeeded":
+            if self.error_code is not None:
+                raise ValueError("Successful mutation cannot carry an error")
+        elif self.new_memory_id:
+            raise ValueError("Unconfirmed mutation cannot grant a new record ID")
+        elif self.status == "unknown" and self.error_code != "MEMORY_MUTATION_UNKNOWN":
+            raise ValueError("Unknown mutation requires an unknown result code")
+        elif self.status == "failed" and self.error_code not in {
+            "MEMORY_RECORD_NOT_OBSERVED",
+            "MEMORY_RECORD_NOT_FOUND",
+        }:
+            raise ValueError("Failed mutation requires a confirmed rejection")
+        return self

ksadk/resource_runtime/operation_ledger.py

@@ -0,0 +1,211 @@
+"""Durable duplicate suppression for host-authorized resource writes.
+
+This ledger is not an approval authority. The host supplies a stable event ID
+across checkpoint recovery and an identity/binding digest after admission.
+Claiming commits before dispatch. A lost claimant leaves an unknown operation;
+opening the database never grants permission to resend it.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sqlite3
+from contextlib import contextmanager
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+from ksadk.resource_runtime.memory_receipts import MemoryMutationReceipt
+
+OperationState = Literal["unknown", "accepted_pending", "searchable", "succeeded", "failed"]
+_TRANSITIONS = {
+    "unknown": {"accepted_pending", "searchable", "succeeded", "failed"},
+    "accepted_pending": {"searchable", "failed"},
+    "searchable": set(),
+    "succeeded": set(),
+    "failed": set(),
+}
+
+
+@dataclass(frozen=True)
+class OperationReceipt:
+    operation_id: str
+    state: OperationState
+    claimed: bool
+
+
+class OperationConflict(ValueError):
+    """The same event was reused with different arguments or an invalid transition."""
+
+
+class OperationLedger:
+    """SQLite ledger in a host-owned private directory; no request bodies stored.
+
+    Each method uses its own transaction so independent runtime processes share
+    duplicate suppression. Retention must cover all recoverable checkpoints.
+    Callers may record failed only after authoritative failure, never timeout.
+    """
+
+    def __init__(self, directory: Path):
+        directory = Path(directory)
+        directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+        if directory.is_symlink() or directory.stat().st_mode & 0o077:
+            raise ValueError("Operation ledger requires a private directory")
+        self.path = directory / "resource-operations.sqlite3"
+        if self.path.is_symlink():
+            raise ValueError("Operation ledger cannot be a symbolic link")
+        with self._connect() as connection:
+            connection.execute(
+                "CREATE TABLE IF NOT EXISTS operations ("
+                "id TEXT PRIMARY KEY, request_digest TEXT NOT NULL, state TEXT NOT NULL)"
+            )
+            connection.execute(
+                "CREATE TABLE IF NOT EXISTS operation_owners ("
+                "id TEXT PRIMARY KEY, authority_digest TEXT NOT NULL, operation TEXT NOT NULL)"
+            )
+            connection.execute(
+                "CREATE TABLE IF NOT EXISTS memory_mutation_results ("
+                "id TEXT PRIMARY KEY, payload TEXT NOT NULL)"
+            )
+        self.path.chmod(0o600)
+
+    @contextmanager
+    def _connect(self):
+        connection = sqlite3.connect(self.path, timeout=10)
+        try:
+            with connection:
+                yield connection
+        finally:
+            connection.close()
+
+    @staticmethod
+    def _key(authority_digest: str, event_id: str, operation: str) -> str:
+        if not all(
+            isinstance(v, str) and 0 < len(v) <= 1024
+            for v in (authority_digest, event_id, operation)
+        ):
+            raise ValueError("Invalid operation identity")
+        payload = json.dumps(
+            ["resource-operation-v1", authority_digest, event_id, operation],
+            separators=(",", ":"),
+            ensure_ascii=True,
+        )
+        return hashlib.sha256(payload.encode()).hexdigest()
+
+    def claim(
+        self, *, authority_digest: str, event_id: str, operation: str, arguments: dict
+    ) -> OperationReceipt:
+        operation_id = self._key(authority_digest, event_id, operation)
+        encoded = json.dumps(arguments, sort_keys=True, separators=(",", ":"), allow_nan=False)
+        request_digest = hashlib.sha256(encoded.encode()).hexdigest()
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            row = connection.execute(
+                "SELECT request_digest, state FROM operations WHERE id = ?", (operation_id,)
+            ).fetchone()
+            if row is not None:
+                if row[0] != request_digest:
+                    raise OperationConflict("RESOURCE_OPERATION_ARGUMENTS_CHANGED")
+                connection.execute(
+                    "INSERT OR IGNORE INTO operation_owners VALUES (?, ?, ?)",
+                    (operation_id, authority_digest, operation),
+                )
+                return OperationReceipt(operation_id, row[1], False)
+            connection.execute(
+                "INSERT INTO operations VALUES (?, ?, 'unknown')", (operation_id, request_digest)
+            )
+            connection.execute(
+                "INSERT INTO operation_owners VALUES (?, ?, ?)",
+                (operation_id, authority_digest, operation),
+            )
+        return OperationReceipt(operation_id, "unknown", True)
+
+    def lookup(
+        self, operation_id: str, *, authority_digest: str, operation: str
+    ) -> OperationReceipt | None:
+        """Opaque IDs alone grant no access. Legacy rows without owners stay hidden."""
+        with self._connect() as connection:
+            row = connection.execute(
+                "SELECT o.state FROM operations o JOIN operation_owners p ON o.id=p.id "
+                "WHERE o.id=? AND p.authority_digest=? AND p.operation=?",
+                (operation_id, authority_digest, operation),
+            ).fetchone()
+        return None if row is None else OperationReceipt(operation_id, row[0], False)
+
+    def record(self, operation_id: str, state: OperationState) -> OperationReceipt:
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            row = connection.execute(
+                "SELECT state FROM operations WHERE id = ?", (operation_id,)
+            ).fetchone()
+            if row is None or state not in _TRANSITIONS:
+                raise OperationConflict("RESOURCE_OPERATION_UNKNOWN")
+            if state != row[0] and state not in _TRANSITIONS[row[0]]:
+                raise OperationConflict("RESOURCE_OPERATION_STATE_CONFLICT")
+            connection.execute(
+                "UPDATE operations SET state = ? WHERE id = ?", (state, operation_id)
+            )
+        return OperationReceipt(operation_id, state, False)
+
+    def record_memory_mutation(
+        self,
+        result: MemoryMutationReceipt,
+        *,
+        authority_digest: str,
+        operation: str,
+    ) -> OperationReceipt:
+        """Commit terminal state and returned record IDs in one transaction."""
+        result = MemoryMutationReceipt.model_validate(result.model_dump())
+        if operation not in {"update_memory", "delete_memory"} or result.status == "unknown":
+            raise OperationConflict("RESOURCE_OPERATION_RESULT_INVALID")
+        if operation == "delete_memory" and result.new_memory_id:
+            raise OperationConflict("RESOURCE_OPERATION_RESULT_INVALID")
+        payload = result.model_dump_json(by_alias=True)
+        with self._connect() as connection:
+            connection.execute("BEGIN IMMEDIATE")
+            row = connection.execute(
+                "SELECT o.state FROM operations o JOIN operation_owners p ON o.id=p.id "
+                "WHERE o.id=? AND p.authority_digest=? AND p.operation=?",
+                (result.operation_id, authority_digest, operation),
+            ).fetchone()
+            if row is None:
+                raise OperationConflict("RESOURCE_OPERATION_UNKNOWN")
+            if result.status != row[0] and result.status not in _TRANSITIONS[row[0]]:
+                raise OperationConflict("RESOURCE_OPERATION_STATE_CONFLICT")
+            previous = connection.execute(
+                "SELECT payload FROM memory_mutation_results WHERE id=?",
+                (result.operation_id,),
+            ).fetchone()
+            if previous is not None and previous[0] != payload:
+                raise OperationConflict("RESOURCE_OPERATION_RESULT_CONFLICT")
+            connection.execute(
+                "INSERT OR IGNORE INTO memory_mutation_results VALUES (?, ?)",
+                (result.operation_id, payload),
+            )
+            connection.execute(
+                "UPDATE operations SET state=? WHERE id=?",
+                (result.status, result.operation_id),
+            )
+        return OperationReceipt(result.operation_id, result.status, False)
+
+    def memory_mutation_result(
+        self,
+        operation_id: str,
+        *,
+        authority_digest: str,
+        operation: str,
+    ) -> dict | None:
+        with self._connect() as connection:
+            row = connection.execute(
+                "SELECT r.payload, o.state FROM memory_mutation_results r "
+                "JOIN operations o ON o.id=r.id JOIN operation_owners p ON p.id=r.id "
+                "WHERE r.id=? AND p.authority_digest=? AND p.operation=?",
+                (operation_id, authority_digest, operation),
+            ).fetchone()
+        if row is None:
+            return None
+        result = MemoryMutationReceipt.model_validate_json(row[0])
+        if result.operation_id != operation_id or result.status != row[1]:
+            raise OperationConflict("RESOURCE_OPERATION_RESULT_CONFLICT")
+        return result.model_dump(by_alias=True, mode="json")

ksadk/resource_runtime/plugin_config.py

@@ -0,0 +1,48 @@
+"""Data-only configuration contracts for the three official resource bundles.
+
+These reserved plugin IDs map to scoped npm packages; recognizing an ID validates
+configuration only. Installation identity and authorization still require Build
+receipts and trusted activation admission.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from ksadk.resource_runtime.contracts import ResourceConfig, validate_resource_bindings
+
+OFFICIAL_RESOURCE_PLUGINS = {
+    "kingsoftcloud.dsh-knowledge": "knowledge-base",
+    "kingsoftcloud.dsh-memory": "memory-instance",
+    "kingsoftcloud.dsh-skill-center": "skill-space",
+}
+
+
+def resource_plugin_config(
+    plugin_ref: str, ecosystem: str, config: Mapping[str, Any], *, enabled: bool
+) -> ResourceConfig | None:
+    plugin_id = plugin_ref.removeprefix("plugin://").rsplit("@", 1)[0]
+    kind = OFFICIAL_RESOURCE_PLUGINS.get(plugin_id)
+    if kind is None:
+        return None
+    if ecosystem != "dsh":
+        raise ValueError("Official platform resource plugins require the DSH ecosystem")
+    if not config and not enabled:
+        return None
+    parsed = ResourceConfig.model_validate(config)
+    if parsed.binding.resource.kind != kind:
+        raise ValueError("Resource kind does not match the official plugin")
+    return parsed
+
+
+def validate_resource_plugin_bindings(bindings: Sequence[Any]) -> None:
+    resources = []
+    for binding in bindings:
+        if binding.enabled:
+            resource = resource_plugin_config(
+                binding.plugin_ref, binding.ecosystem, binding.config, enabled=True
+            )
+            if resource is not None:
+                resources.append(resource)
+    validate_resource_bindings(tuple(resources))

ksadk/resource_runtime/policy_authorization.py

@@ -0,0 +1,54 @@
+"""Request-scoped host authorization for resource writes."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+
+from ksadk.resource_runtime.ipc import ResourceRequest
+from ksadk.resource_runtime.leases import ResourceScope
+
+_WRITES = frozenset({"save_memory", "update_memory", "delete_memory", "execute_skills"})
+
+
+class FullAccessResourceWriteAuthorizer:
+    """Authorize exact writes covered by a trusted full-access invocation.
+
+    The Studio/API ingress chooses the approval profile. Capability plugins only
+    receive this authorizer after the trusted host has resolved that profile for
+    the current activation. The returned event reference binds the decision to
+    the exact scope and arguments so OperationLedger can fence retries.
+    """
+
+    def __init__(self, *, activation_key: str) -> None:
+        if not activation_key or any(character.isspace() for character in activation_key):
+            raise ValueError("RESOURCE_APPROVAL_ACTIVATION_INVALID")
+        self._activation_key = activation_key
+
+    async def authorize(self, request: ResourceRequest, scope: ResourceScope) -> str | None:
+        if request.operation not in _WRITES or request.operation not in scope.allowed_operations:
+            return None
+        payload = {
+            "version": 1,
+            "approvalProfile": "full",
+            "activationKey": self._activation_key,
+            "identity": scope.identity.model_dump(mode="json"),
+            "build": scope.build_digest,
+            "binding": scope.binding_id,
+            "snapshot": scope.binding_snapshot_digest,
+            "operation": request.operation,
+            "arguments": request.arguments,
+        }
+        digest = hashlib.sha256(
+            json.dumps(
+                payload,
+                ensure_ascii=False,
+                sort_keys=True,
+                separators=(",", ":"),
+                allow_nan=False,
+            ).encode()
+        ).hexdigest()
+        return f"studio-full-access:{digest}"
+
+
+__all__ = ["FullAccessResourceWriteAuthorizer"]