hebbrix 2.4.0__tar.gz → 2.5.0__tar.gz

{hebbrix-2.4.0 → hebbrix-2.5.0}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 2.5.0 — 2026-09-07
+
+- Add matching synchronous and asynchronous Evidence Loop methods: owner-managed verifiers, durable episodes, actual-execution claims, protected outcome delivery and evidence assessments.
+- Preserve scope, replay, incomplete-outcome and permission receipts without converting recommendations into execution authority or falling back to caller-reported outcomes.
+- Reject malformed, ambiguous or unknown evidence contracts before exposing unsupported synthesis; retain valid degraded evidence with its abstention signal.
+- Protected ledger methods require the connected Evidence Loop backend. Separate verifier credentials and an independent execution/outcome check remain required; these methods do not execute actions.
+
+## 2.4.1 — 2026-08-27
+
+- Make every async and sync readiness deadline preserve the original durable
+  receipt and raise top-level `IndexingTimeoutError`, including single writes,
+  batches, inference jobs, and direct updates.
+- Normalize memory/job/status/request/outbox/idempotency recovery metadata and
+  preserve transport-only `Location`, request, retry, event, and replay headers.
+
 ## 2.4.0 — 2026-08-27
 
 - Reconcile every exported advanced method with the canonical public OpenAPI,

{hebbrix-2.4.0/hebbrix.egg-info → hebbrix-2.5.0}/PKG-INFO

@@ -1,13 +1,35 @@
 Metadata-Version: 2.4
 Name: hebbrix
-Version: 2.4.0
+Version: 2.5.0
 Summary: Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs
 Author-email: Hebbrix Team <support@hebbrix.com>
 Maintainer-email: Hebbrix Team <support@hebbrix.com>
-License-Expression: MIT
+License: MIT License
+        
+        Copyright (c) 2025 Hebbrix
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
 Project-URL: Homepage, https://hebbrix.com
 Project-URL: Documentation, https://docs.hebbrix.com
-Project-URL: Source, https://pypi.org/project/hebbrix/#files
+Project-URL: Source, https://github.com/Hebbrix/hebbrix-python
+Project-URL: Issues, https://github.com/Hebbrix/hebbrix-python/issues
 Project-URL: Support, https://www.hebbrix.com/contact
 Project-URL: API Reference, https://api.hebbrix.com/docs
 Keywords: ai,memory,agents,llm,chatbot,assistant,ml,reinforcement-learning,knowledge-graph,vector-search,rag,temporal,procedural-memory,working-memory
@@ -46,7 +68,7 @@ Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs.
 ## Install
 
 ```bash
-pip install hebbrix==2.4.0
+pip install hebbrix==2.5.0
 ```
 
 Python 3.8+ is supported. `MemoryClient` is asynchronous. `SyncMemoryClient`
@@ -87,8 +109,37 @@ converging; it is not a failure and does not justify a duplicate write.
 When `wait_for_index=True`, the SDK accepts that receipt and polls the documented
 status URL. It returns only after `searchable=true`. If the caller's deadline
 expires, it raises `IndexingTimeoutError`; the exception retains the original
-receipt, durable memory IDs, and status URL. Reuse the same idempotency key with
-the same body to recover the same logical resources.
+receipt plus normalized `memory_ids`, `job_id`, `status_url`, `request_id`,
+`outbox_event_id`, retry timing, and idempotency replay metadata when available.
+The synchronous and asynchronous single, batch, inference-job, and update
+readiness paths share this behavior. The SDK never repeats the write while it
+polls.
+
+Catch the typed deadline without discarding the durable acceptance:
+
+```python
+from hebbrix import IndexingTimeoutError
+
+try:
+    created = await client.memories.create(
+        content="Customer prefers concise replies",
+        wait_for_index=True,
+        idempotency_key="customer-42-preference-v1",
+        index_timeout=5,
+    )
+except IndexingTimeoutError as exc:
+    # Resume observation; do not submit an unrelated second write.
+    if exc.memory_ids:
+        created = await client.memories.wait_until_searchable(exc.memory_ids[0])
+    elif exc.job_id:
+        created = await client.memory_jobs.wait(exc.job_id)
+```
+
+For a timed-out batch, pass `exc.receipt` to
+`memories.wait_batch_until_searchable(...)`. Alternatively, replay the exact
+same body with `exc.idempotency_key`; a changed body with the same key is
+rejected by the API rather than creating a second logical write. For an update,
+resume polling `exc.memory_ids[0]` because the relational edit already committed.
 
 For an asynchronous batch receipt:
 

{hebbrix-2.4.0 → hebbrix-2.5.0}/README.md

@@ -5,7 +5,7 @@ Typed Python client for Hebbrix memory, retrieval, and outcome-learning APIs.
 ## Install
 
 ```bash
-pip install hebbrix==2.4.0
+pip install hebbrix==2.5.0
 ```
 
 Python 3.8+ is supported. `MemoryClient` is asynchronous. `SyncMemoryClient`
@@ -46,8 +46,37 @@ converging; it is not a failure and does not justify a duplicate write.
 When `wait_for_index=True`, the SDK accepts that receipt and polls the documented
 status URL. It returns only after `searchable=true`. If the caller's deadline
 expires, it raises `IndexingTimeoutError`; the exception retains the original
-receipt, durable memory IDs, and status URL. Reuse the same idempotency key with
-the same body to recover the same logical resources.
+receipt plus normalized `memory_ids`, `job_id`, `status_url`, `request_id`,
+`outbox_event_id`, retry timing, and idempotency replay metadata when available.
+The synchronous and asynchronous single, batch, inference-job, and update
+readiness paths share this behavior. The SDK never repeats the write while it
+polls.
+
+Catch the typed deadline without discarding the durable acceptance:
+
+```python
+from hebbrix import IndexingTimeoutError
+
+try:
+    created = await client.memories.create(
+        content="Customer prefers concise replies",
+        wait_for_index=True,
+        idempotency_key="customer-42-preference-v1",
+        index_timeout=5,
+    )
+except IndexingTimeoutError as exc:
+    # Resume observation; do not submit an unrelated second write.
+    if exc.memory_ids:
+        created = await client.memories.wait_until_searchable(exc.memory_ids[0])
+    elif exc.job_id:
+        created = await client.memory_jobs.wait(exc.job_id)
+```
+
+For a timed-out batch, pass `exc.receipt` to
+`memories.wait_batch_until_searchable(...)`. Alternatively, replay the exact
+same body with `exc.idempotency_key`; a changed body with the same key is
+rejected by the API rather than creating a second logical write. For an update,
+resume polling `exc.memory_ids[0]` because the relational edit already committed.
 
 For an asynchronous batch receipt:
 

{hebbrix-2.4.0 → hebbrix-2.5.0}/hebbrix/__init__.py

@@ -5,7 +5,7 @@ production OpenAPI and ``GET /v1/users/me/capabilities``. The experimental
 World Model is intentionally absent from this release.
 """
 
-__version__ = "2.4.0"
+__version__ = "2.5.0"
 __author__ = "Hebbrix Team"
 __license__ = "MIT"
 

{hebbrix-2.4.0 → hebbrix-2.5.0}/hebbrix/client.py

@@ -90,7 +90,7 @@ class MemoryClient:
         """Get request headers."""
         headers = {
             "Content-Type": "application/json",
-            "User-Agent": "hebbrix-python/2.4.0",
+            "User-Agent": "hebbrix-python/2.5.0",
         }
 
         if self.api_key:
@@ -200,7 +200,24 @@ class MemoryClient:
         if response.status_code >= 400:
             self._handle_error(response)
 
-        return response.json() if response.text else {}
+        payload = response.json() if response.text else {}
+        if isinstance(payload, dict):
+            # Preserve transport-only recovery identifiers on durable 202
+            # receipts.  The resource layer needs these values if its local
+            # readiness deadline expires after the write has committed.
+            recovery_headers = {
+                "request_id": response.headers.get("X-Request-ID"),
+                "status_url": response.headers.get("Location"),
+                "outbox_event_id": response.headers.get("X-Hebbrix-Index-Event"),
+                "retry_after": response.headers.get("Retry-After"),
+            }
+            for key, value in recovery_headers.items():
+                if value and not payload.get(key):
+                    payload[key] = value
+            replay = response.headers.get("X-Idempotent-Replay")
+            if replay is not None and "idempotency_replay" not in payload:
+                payload["idempotency_replay"] = replay.casefold() == "true"
+        return payload
 
     async def get(self, path: str, **kwargs) -> Dict[str, Any]:
         """Make a GET request."""

hebbrix-2.5.0/hebbrix/exceptions.py

@@ -0,0 +1,135 @@
+"""
+Hebbrix SDK Exceptions
+"""
+
+
+class HebbrixError(Exception):
+    """Base exception for Hebbrix SDK."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: int = None,
+        *,
+        code: str = None,
+        request_id: str = None,
+        details: dict = None,
+    ):
+        self.message = message
+        self.status_code = status_code
+        self.code = code
+        self.request_id = request_id
+        self.details = details or {}
+        super().__init__(self.message)
+
+
+class EntitlementError(HebbrixError):
+    """The authenticated account lacks the plan or role for an operation."""
+
+    def __init__(self, message: str, *, status_code: int, **kwargs):
+        super().__init__(message, status_code=status_code, **kwargs)
+
+
+class IndexingTimeoutError(TimeoutError):
+    """A durable write did not become searchable before the client deadline.
+
+    The write has already committed when this exception is raised.  Recovery
+    metadata therefore lives on the exception so callers can resume polling or
+    safely replay the *same* request with the same idempotency key instead of
+    issuing an uncorrelated duplicate write.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        receipt: dict,
+        *,
+        idempotency_key: str = None,
+    ):
+        self.receipt = dict(receipt or {})
+
+        candidates = [
+            *(self.receipt.get("memory_ids") or []),
+            self.receipt.get("memory_id"),
+            self.receipt.get("id"),
+            *(
+                item.get("memory_id") or item.get("id")
+                for item in (self.receipt.get("results") or [])
+                if isinstance(item, dict)
+            ),
+        ]
+        self.memory_ids = list(
+            dict.fromkeys(str(value) for value in candidates if value)
+        )
+        self.job_id = self.receipt.get("job_id")
+        self.status_url = self.receipt.get("status_url")
+        if not self.status_url and self.memory_ids:
+            self.status_url = f"/v1/memories/{self.memory_ids[0]}"
+        if not self.status_url and self.job_id:
+            self.status_url = f"/v1/memory-jobs/{self.job_id}"
+
+        self.request_id = self.receipt.get("request_id")
+        self.outbox_event_id = self.receipt.get("outbox_event_id")
+        self.indexing_event_id = (
+            self.receipt.get("indexing_event_id") or self.outbox_event_id
+        )
+        self.event_id = self.receipt.get("event_id") or self.indexing_event_id
+        self.idempotency_key = idempotency_key or self.receipt.get("idempotency_key")
+        self.idempotency_replay = self.receipt.get(
+            "idempotency_replay",
+            self.receipt.get("idempotency_replayed"),
+        )
+        self.retry_after = self.receipt.get("retry_after")
+        self.recovery = {
+            key: value
+            for key, value in {
+                "memory_ids": list(self.memory_ids),
+                "job_id": self.job_id,
+                "status_url": self.status_url,
+                "request_id": self.request_id,
+                "outbox_event_id": self.outbox_event_id,
+                "indexing_event_id": self.indexing_event_id,
+                "event_id": self.event_id,
+                "idempotency_key": self.idempotency_key,
+                "idempotency_replay": self.idempotency_replay,
+                "retry_after": self.retry_after,
+            }.items()
+            if value not in (None, "", [])
+        }
+        super().__init__(message)
+
+
+class AuthenticationError(HebbrixError):
+    """Raised when authentication fails."""
+
+    def __init__(self, message: str = "Authentication failed", **kwargs):
+        super().__init__(message, status_code=401, **kwargs)
+
+
+class ValidationError(HebbrixError):
+    """Raised when request validation fails."""
+
+    def __init__(self, message: str, errors: list = None, **kwargs):
+        self.errors = errors or []
+        super().__init__(message, status_code=422, **kwargs)
+
+
+class NotFoundError(HebbrixError):
+    """Raised when a resource is not found."""
+
+    def __init__(self, message: str = "Resource not found", **kwargs):
+        super().__init__(message, status_code=404, **kwargs)
+
+
+class RateLimitError(HebbrixError):
+    """Raised when rate limit is exceeded."""
+
+    def __init__(self, message: str = "Rate limit exceeded", **kwargs):
+        super().__init__(message, status_code=429, **kwargs)
+
+
+class ServerError(HebbrixError):
+    """Raised when server returns 5xx error."""
+
+    def __init__(self, message: str = "Internal server error", **kwargs):
+        super().__init__(message, status_code=500, **kwargs)

{hebbrix-2.4.0 → hebbrix-2.5.0}/hebbrix/resources.py

@@ -9,6 +9,7 @@ import json
 import time
 import uuid
 from typing import TYPE_CHECKING, Any, AsyncIterator, Dict, List, Optional
+from urllib.parse import quote
 
 from hebbrix.exceptions import IndexingTimeoutError
 from hebbrix.models import SearchSafetyEnvelope
@@ -97,9 +98,9 @@ def _canonical_search_envelope(
 ) -> Dict[str, Any]:
     """Validate API-owned evidence metadata and fail closed on contract drift."""
 
-    data = dict(response or {})
-    rows = data.get(rows_key)
-    rows = rows if isinstance(rows, list) else []
+    data = dict(response) if isinstance(response, dict) else {}
+    raw_rows = data.get(rows_key)
+    rows = raw_rows if isinstance(raw_rows, list) else []
     missing = sorted(_SEARCH_SAFETY_FIELDS.difference(data))
     reason: Optional[str] = None
     confidence = data.get("query_confidence")
@@ -117,6 +118,27 @@ def _canonical_search_envelope(
         reason = "invalid_grounding_receipt"
     elif not isinstance(data.get("evidence_ids"), list):
         reason = "invalid_evidence_ids"
+    elif data.get("safety_contract_version") != "search-safety-v1":
+        reason = "unsupported_safety_contract_version"
+    elif not isinstance(raw_rows, list):
+        reason = "invalid_evidence_rows"
+    elif any(
+        not isinstance(value, str) or not value.strip()
+        for value in data["evidence_ids"]
+    ):
+        reason = "invalid_evidence_ids"
+    elif len(set(data["evidence_ids"])) != len(data["evidence_ids"]):
+        reason = "duplicate_evidence_ids"
+    elif any(
+        not isinstance(row, dict)
+        or not isinstance(row.get("memory_id", row.get("id")), str)
+        or not row.get("memory_id", row.get("id", "")).strip()
+        or ("memory_id" in row and "id" in row and row["memory_id"] != row["id"])
+        for row in rows
+    ):
+        reason = "invalid_evidence_row_identity"
+    elif not rows and data.get("no_match") is False:
+        reason = "no_evidence_rows"
     else:
         row_ids = {
             str(row.get("memory_id") or row.get("id"))
@@ -143,6 +165,9 @@ def _canonical_search_envelope(
         data["query_confidence"] = 0.0
         data["evidence_ids"] = []
         data["evidence_claims"] = []
+        if rows_key == "sources":
+            data["answer"] = None
+            data["citations"] = []
         if reason:
             data["sdk_safety_reason"] = reason
             data["grounding"] = {
@@ -457,6 +482,7 @@ class MemoriesResource(BaseResource):
                 receipt,
                 timeout=index_timeout,
                 poll_interval=index_poll_interval,
+                idempotency_key=idempotency_key,
             )
         return receipt
 
@@ -505,11 +531,15 @@ class MemoriesResource(BaseResource):
         if idempotency_key:
             kwargs["headers"] = {"Idempotency-Key": idempotency_key}
         receipt = await self.client.post("/v1/memories/batch", **kwargs)
-        if wait_for_index and not receipt.get("searchable"):
+        if wait_for_index and not (
+            receipt.get("searchable") is True
+            and str(receipt.get("processing_status") or "").casefold() == "completed"
+        ):
             receipt = await self.wait_batch_until_searchable(
                 receipt,
                 timeout=index_timeout,
                 poll_interval=index_poll_interval,
+                idempotency_key=idempotency_key,
             )
         return receipt
 
@@ -519,6 +549,7 @@ class MemoriesResource(BaseResource):
         *,
         timeout: float = 60.0,
         poll_interval: float = 0.5,
+        idempotency_key: Optional[str] = None,
     ) -> Dict[str, Any]:
         """Poll every item in an asynchronous batch receipt to one terminal state.
 
@@ -537,11 +568,20 @@ class MemoriesResource(BaseResource):
             )
             for row in rows:
                 state = str(row.get("processing_status") or "").casefold()
+                if state == "completed" and row.get("searchable") is not True:
+                    raise RuntimeError(
+                        f"memory {row.get('id')} reported completed without "
+                        "searchable=true"
+                    )
                 if state in {"failed", "cancelled", "canceled"}:
                     raise RuntimeError(
                         f"memory {row.get('id')} indexing reached terminal state {state}"
                     )
-            if all(row.get("searchable") is True for row in rows):
+            if all(
+                row.get("searchable") is True
+                and str(row.get("processing_status") or "").casefold() == "completed"
+                for row in rows
+            ):
                 return {
                     **receipt,
                     "processing_status": "completed",
@@ -556,10 +596,14 @@ class MemoriesResource(BaseResource):
                     ],
                 }
             if time.monotonic() >= deadline:
-                raise IndexingTimeoutError(
+                timeout_error = TimeoutError(
                     f"batch was not searchable within {timeout}s; the write is durable",
-                    receipt,
                 )
+                raise IndexingTimeoutError(
+                    str(timeout_error),
+                    receipt,
+                    idempotency_key=idempotency_key,
+                ) from timeout_error
             await asyncio.sleep(max(0.05, poll_interval))
 
     async def wait_until_searchable(
@@ -597,6 +641,7 @@ class MemoriesResource(BaseResource):
         *,
         timeout: float,
         poll_interval: float,
+        idempotency_key: Optional[str] = None,
     ) -> Dict[str, Any]:
         if (
             receipt.get("searchable") is True
@@ -619,9 +664,14 @@ class MemoriesResource(BaseResource):
                         f"memory job {job_id} reached terminal state {state}"
                     )
                 if time.monotonic() >= deadline:
-                    raise TimeoutError(
+                    timeout_error = TimeoutError(
                         f"memory job {job_id} did not become searchable within {timeout}s"
                     )
+                    raise IndexingTimeoutError(
+                        f"{timeout_error}; the write is durable",
+                        receipt,
+                        idempotency_key=idempotency_key,
+                    ) from timeout_error
                 await asyncio.sleep(max(0.05, poll_interval))
 
         candidates = [
@@ -637,11 +687,19 @@ class MemoriesResource(BaseResource):
             raise RuntimeError(
                 "wait_for_index response contained neither a memory id nor a job id"
             )
-        ready = await self.wait_until_searchable(
-            memory_id,
-            timeout=timeout,
-            poll_interval=poll_interval,
-        )
+        try:
+            ready = await self.wait_until_searchable(
+                memory_id,
+                timeout=timeout,
+                poll_interval=poll_interval,
+            )
+        except TimeoutError as exc:
+            raise IndexingTimeoutError(
+                f"memory {memory_id} was not searchable within {timeout}s; "
+                "the write is durable",
+                receipt,
+                idempotency_key=idempotency_key,
+            ) from exc
         receipt["searchable"] = True
         receipt["processing_status"] = "completed"
         receipt["status_url"] = ready.get("status_url") or f"/v1/memories/{memory_id}"
@@ -793,6 +851,8 @@ class MemoriesResource(BaseResource):
         importance: Optional[float] = None,
         metadata: Optional[Dict[str, Any]] = None,
         wait_for_index: Optional[bool] = None,
+        index_timeout: float = 60.0,
+        index_poll_interval: float = 0.5,
     ) -> Dict[str, Any]:
         """
         Update a memory.
@@ -816,7 +876,15 @@ class MemoriesResource(BaseResource):
         if wait_for_index is not None:
             data["wait_for_index"] = wait_for_index
 
-        return await self.client.patch(f"/v1/memories/{memory_id}", json=data)
+        receipt = await self.client.patch(f"/v1/memories/{memory_id}", json=data)
+        if wait_for_index is True:
+            receipt = {**receipt, "id": receipt.get("id") or memory_id}
+            receipt = await self._ensure_searchable_receipt(
+                receipt,
+                timeout=index_timeout,
+                poll_interval=index_poll_interval,
+            )
+        return receipt
 
     async def delete(self, memory_id: str) -> None:
         """
@@ -1113,6 +1181,133 @@ class ProofLoopResource(BaseResource):
             body["proof_context_token"] = token
         return await self.client.post("/v1/learning/decisions", json=body)
 
+    async def register_verifier(
+        self,
+        *,
+        policy_key: str,
+        api_key_id: str,
+        source_system: str,
+        metric_keys: List[str],
+        collection_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Owner-session administration; the agent cannot register its own verifier."""
+        return await self.client.post(
+            "/v1/learning/verifiers",
+            json={
+                "policy_key": policy_key,
+                "api_key_id": api_key_id,
+                "source_system": source_system,
+                "metric_keys": metric_keys,
+                "collection_id": collection_id,
+                "user_id": user_id,
+            },
+        )
+
+    async def revoke_verifier(self, verifier_id: str) -> Dict[str, Any]:
+        """Revoke one source without deleting historical evidence."""
+        return await self.client.post(
+            f"/v1/learning/verifiers/{quote(verifier_id, safe='')}/revoke", json={}
+        )
+
+    async def create_episode(
+        self,
+        *,
+        policy_key: str,
+        verifier_id: str,
+        idempotency_key: str,
+        collection_id: Optional[str] = None,
+        user_id: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Create a scoped durable episode; never grants execution permission."""
+        return await self.client.post(
+            "/v1/learning/episodes",
+            json={
+                "policy_key": policy_key,
+                "verifier_id": verifier_id,
+                "idempotency_key": idempotency_key,
+                "collection_id": collection_id,
+                "user_id": user_id,
+            },
+        )
+
+    async def get_episode(self, episode_id: str, *, offset: int = 0) -> Dict[str, Any]:
+        return await self.client.get(
+            f"/v1/learning/episodes/{quote(episode_id, safe='')}",
+            params={"offset": offset},
+        )
+
+    async def close_episode(self, episode_id: str, *, status: str) -> Dict[str, Any]:
+        return await self.client.post(
+            f"/v1/learning/episodes/{quote(episode_id, safe='')}/close",
+            json={"status": status},
+        )
+
+    async def record_execution(
+        self,
+        decision_id: str,
+        *,
+        attempt_id: str,
+        status: str,
+        actual_action_key: str,
+        arguments_digest: str,
+        evidence_digest: Optional[str] = None,
+        occurred_at: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """Record an execution claim, not an instruction to execute."""
+        body = {
+            "attempt_id": attempt_id,
+            "status": status,
+            "actual_action_key": actual_action_key,
+            "arguments_digest": arguments_digest,
+        }
+        if evidence_digest is not None:
+            body["evidence_digest"] = evidence_digest
+        if occurred_at is not None:
+            body["occurred_at"] = occurred_at
+        return await self.client.post(
+            f"/v1/learning/decisions/{quote(decision_id, safe='')}/executions",
+            json=body,
+        )
+
+    async def assessment(
+        self, decision_id: str, *, evidence_offset: int = 0
+    ) -> Dict[str, Any]:
+        return await self.client.get(
+            f"/v1/learning/decisions/{quote(decision_id, safe='')}/assessment",
+            params={"evidence_offset": evidence_offset},
+        )
+
+    async def verifier_evidence(
+        self, verifier_id: str, decision_id: str
+    ) -> Dict[str, Any]:
+        """Call with the dedicated verifier client, never the actor's credential."""
+        return await self.client.get(
+            f"/v1/learning/verifiers/{quote(verifier_id, safe='')}/decisions/{quote(decision_id, safe='')}"
+        )
+
+    async def deliver_verified_outcomes(
+        self,
+        verifier_id: str,
+        *,
+        decision_id: str,
+        source_event_id: str,
+        evidence_digest: str,
+        execution_digest: str,
+        observations: List[Dict[str, Any]],
+    ) -> Dict[str, Any]:
+        """Deliver independently checked observations using the registered source key."""
+        return await self.client.post(
+            f"/v1/learning/verifiers/{quote(verifier_id, safe='')}/events",
+            json={
+                "decision_id": decision_id,
+                "source_event_id": source_event_id,
+                "evidence_digest": evidence_digest,
+                "execution_digest": execution_digest,
+                "observations": observations,
+            },
+        )
+
     async def get_decision(self, decision_id: str) -> Dict[str, Any]:
         return await self.client.get(f"/v1/learning/decisions/{decision_id}")