commitlayer-integrations 0.1.0__py3-none-any.whl

commitlayer_openai_agents/__init__.py

@@ -0,0 +1,71 @@
+"""CommitLayer for the OpenAI Agents SDK: record function-tool calls as actions before they run.
+
+:class:`CommitLayerHooks` is a ``RunHooks`` whose ``on_tool_start`` records the mapped call. The SDK passes
+function tools a ``ToolContext`` carrying ``tool_name``, ``tool_call_id`` and the raw ``tool_arguments`` JSON,
+which is everything the recorder needs; hosted tools (web search, computer use) pass a plain context and are
+left alone. The hook never blocks the call and never reads its result.
+
+    from agents import Agent, Runner
+    from commitlayer import Client
+    from commitlayer_integrations.tools import ToolRecorder
+    from commitlayer_openai_agents import CommitLayerHooks
+
+    recorder = ToolRecorder(Client(agent_id="support-bot"), MAPPING)
+    result = await Runner.run(agent, "Refund order 10231", hooks=CommitLayerHooks(recorder))
+    recorder.wait("refund:order_10231")           # the completion gate
+
+``agents`` (the SDK) is imported lazily: when it is installed, :class:`CommitLayerHooks` subclasses its
+``RunHooks`` so the SDK's type checks pass; when it is not, the class stands alone with the same methods, so
+this module imports and tests anywhere.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from commitlayer_integrations.tools import ToolRecorder
+
+__all__ = ["CommitLayerHooks", "CHANNEL"]
+
+CHANNEL = "openai_agents"
+
+try:  # the SDK's base class when available, so the hooks object is a RunHooks to the SDK
+    from agents import RunHooks as _Base  # type: ignore[import-not-found]
+except Exception:  # noqa: BLE001 - optional dependency
+
+    class _Base:  # type: ignore[no-redef]
+        """Stand-in for ``agents.RunHooks`` when the SDK is not installed."""
+
+
+def _arguments(context: Any) -> dict[str, Any]:
+    raw = getattr(context, "tool_arguments", None)
+    if isinstance(raw, dict):
+        return raw
+    if isinstance(raw, str) and raw.strip():
+        try:
+            parsed = json.loads(raw)
+            return parsed if isinstance(parsed, dict) else {"value": parsed}
+        except ValueError:
+            return {"raw": raw}
+    return {}
+
+
+class CommitLayerHooks(_Base):  # type: ignore[misc]
+    """``RunHooks`` that records every mapped tool call through ``recorder`` before the tool runs."""
+
+    def __init__(self, recorder: ToolRecorder):
+        super().__init__()
+        self.recorder = recorder
+        if recorder.channel == "agent":
+            recorder.channel = CHANNEL
+
+    async def on_tool_start(self, context: Any, agent: Any, tool: Any) -> None:
+        name = getattr(context, "tool_name", None) or getattr(tool, "name", None)
+        if not name or not hasattr(context, "tool_arguments"):
+            return  # a hosted tool with no arguments to map
+        call_id = getattr(context, "tool_call_id", None)
+        self.recorder.record(str(name), _arguments(context), call_id=call_id)
+
+    async def on_tool_end(self, context: Any, agent: Any, tool: Any, result: Any) -> None:
+        return None  # the tool's own result is never evidence

commitlayer_pydantic_ai/__init__.py

@@ -0,0 +1,57 @@
+"""CommitLayer for Pydantic AI: record tool calls as actions before the tools run.
+
+Pydantic AI routes every tool call through a toolset's ``call_tool``; :class:`RecordingToolset` wraps any
+toolset and records the mapped calls before delegating to it. The recorder sees the validated arguments and
+the run's ``tool_call_id``; the tool's result is never sent.
+
+    from pydantic_ai import Agent, FunctionToolset
+    from commitlayer import Client
+    from commitlayer_integrations.tools import ToolRecorder
+    from commitlayer_pydantic_ai import RecordingToolset
+
+    recorder = ToolRecorder(Client(agent_id="support-bot"), MAPPING)
+    tools = FunctionToolset(tools=[refund_payment, close_ticket])
+    agent = Agent("openai:gpt-5", toolsets=[RecordingToolset(tools, recorder)])
+
+``pydantic_ai`` is imported lazily: with it installed :class:`RecordingToolset` is a real ``WrapperToolset``;
+without it the class keeps the same ``call_tool`` shape so this module imports and tests anywhere.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from commitlayer_integrations.tools import ToolRecorder
+
+__all__ = ["RecordingToolset", "CHANNEL"]
+
+CHANNEL = "pydantic_ai"
+
+try:
+    from pydantic_ai import WrapperToolset as _Base  # type: ignore[import-not-found]
+except Exception:  # noqa: BLE001 - optional dependency
+
+    class _Base:  # type: ignore[no-redef]
+        """Stand-in for ``pydantic_ai.WrapperToolset`` when Pydantic AI is not installed."""
+
+        def __init__(self, wrapped: Any):
+            self.wrapped = wrapped
+
+        async def call_tool(self, name: str, tool_args: dict[str, Any], ctx: Any, tool: Any) -> Any:
+            return await self.wrapped.call_tool(name, tool_args, ctx, tool)
+
+
+class RecordingToolset(_Base):  # type: ignore[misc]
+    """A toolset wrapper that records every mapped tool call through ``recorder``, then delegates."""
+
+    def __init__(self, wrapped: Any, recorder: ToolRecorder):
+        super().__init__(wrapped)
+        self.recorder = recorder
+        if recorder.channel == "agent":
+            recorder.channel = CHANNEL
+
+    async def call_tool(self, name: str, tool_args: dict[str, Any], ctx: Any, tool: Any) -> Any:
+        call_id = getattr(ctx, "tool_call_id", None)
+        run_id = getattr(ctx, "run_id", None)
+        self.recorder.record(name, dict(tool_args or {}), call_id=call_id, run_id=run_id)
+        return await super().call_tool(name, tool_args, ctx, tool)

commitlayer_temporal/__init__.py

@@ -0,0 +1,61 @@
+"""CommitLayer for Temporal: record each mapped activity as an action, and gate completion on the verdict.
+
+Temporal makes the workflow durable. CommitLayer independently verifies the result.
+
+``temporalio`` is imported lazily: the mapping helpers work without it, the interceptor and the verifier need it
+(``pip install commitlayer-integrations[temporal]``).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .mapping import (
+    CHANNEL,
+    DEFAULT_ACTION_ID,
+    ActivityMapping,
+    MappingError,
+    TemporalRef,
+    bind_kwargs,
+    build_action_body,
+    resolve_path,
+)
+
+__all__ = [
+    "CHANNEL",
+    "DEFAULT_ACTION_ID",
+    "ACTIVITY_NAME",
+    "RECORD_FAILED",
+    "ActivityMapping",
+    "CommitLayerActivityInboundInterceptor",
+    "CommitLayerInterceptor",
+    "CommitLayerVerifier",
+    "MappingError",
+    "TemporalRef",
+    "bind_kwargs",
+    "build_action_body",
+    "resolve_path",
+]
+
+_LAZY = {
+    "CommitLayerInterceptor": "interceptor",
+    "CommitLayerActivityInboundInterceptor": "interceptor",
+    "RECORD_FAILED": "interceptor",
+    "CommitLayerVerifier": "verifier",
+    "ACTIVITY_NAME": "verifier",
+}
+
+
+def __getattr__(name: str) -> Any:
+    module = _LAZY.get(name)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    try:
+        import importlib
+
+        mod = importlib.import_module(f".{module}", __name__)
+    except ImportError as e:  # pragma: no cover - depends on the environment
+        raise ImportError(
+            f"{name} needs the Temporal SDK: pip install 'commitlayer-integrations[temporal]'"
+        ) from e
+    return getattr(mod, name)

commitlayer_temporal/interceptor.py

@@ -0,0 +1,127 @@
+"""A Temporal worker interceptor that records a CommitLayer action before a mapped activity runs.
+
+Wire it once on the worker::
+
+    from commitlayer import Client
+    from commitlayer_temporal import CommitLayerInterceptor
+
+    cl = Client()  # COMMITLAYER_API_KEY from the environment; never log it
+    worker = Worker(
+        client, task_queue="orders",
+        workflows=[RefundWorkflow], activities=[refund_payment],
+        interceptors=[CommitLayerInterceptor(cl, {
+            "refund_payment": {
+                "contract_id": "refund_workflow",
+                "subject": "kwargs.order_id",
+                "params": {"amount": "kwargs.amount", "reason": "kwargs.reason"},
+                "subject_kind": "order",
+            },
+        }, agent_id="refund-agent")],
+    )
+
+The interceptor only declares the agent's intent: contract, subject and parameters, taken from the activity's
+arguments before it executes. The activity's result is never sent. Verification reads the systems of record.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from commitlayer import Client
+from temporalio import activity
+from temporalio.exceptions import ApplicationError
+from temporalio.worker import ActivityInboundInterceptor, ExecuteActivityInput, Interceptor
+
+from .mapping import ActivityMapping, TemporalRef, bind_kwargs, build_action_body
+
+__all__ = ["CommitLayerInterceptor", "CommitLayerActivityInboundInterceptor", "RECORD_FAILED"]
+
+log = logging.getLogger("commitlayer.temporal")
+
+RECORD_FAILED = "CommitLayerRecordFailed"
+"""``ApplicationError.type`` raised when ``fail_open=False`` and the action could not be recorded."""
+
+
+class CommitLayerInterceptor(Interceptor):
+    """Record an action for every activity named in ``mapping``; leave the others alone.
+
+    ``mapping`` is ``{activity name: ActivityMapping | dict}`` (see :mod:`commitlayer_temporal.mapping`).
+    ``agent_id`` is sent on every action; ``workflow_id`` replaces the Temporal workflow id when set.
+    With ``fail_open=True`` (default) a recording failure is logged as a warning and the activity still runs;
+    with ``fail_open=False`` the activity does not run and a non-retryable ``ApplicationError`` (type
+    ``CommitLayerRecordFailed``) fails it. ``on_recorded`` receives the API response for each recorded action.
+    """
+
+    def __init__(
+        self,
+        client: Client,
+        mapping: Mapping[str, ActivityMapping | Mapping[str, Any]],
+        *,
+        agent_id: str | None = None,
+        workflow_id: str | None = None,
+        fail_open: bool = True,
+        on_recorded: Callable[[dict[str, Any]], None] | None = None,
+    ) -> None:
+        self.client = client
+        self.mapping = {name: ActivityMapping.coerce(m) for name, m in mapping.items()}
+        self.agent_id = agent_id or client.agent_id
+        self.workflow_id = workflow_id
+        self.fail_open = fail_open
+        self.on_recorded = on_recorded
+
+    def intercept_activity(self, next: ActivityInboundInterceptor) -> ActivityInboundInterceptor:
+        return CommitLayerActivityInboundInterceptor(next, self)
+
+    # ---- recording ----
+
+    def body_for(self, input: ExecuteActivityInput, info: Any) -> dict[str, Any] | None:
+        """The ``POST /v1/actions`` body for this invocation, or ``None`` when the activity is not mapped."""
+        ref = TemporalRef.from_info(info)
+        mapping = self.mapping.get(ref.activity_type)
+        if mapping is None:
+            return None
+        return build_action_body(
+            mapping,
+            ref=ref,
+            args=input.args,
+            kwargs=bind_kwargs(input.fn, input.args),
+            agent_id=self.agent_id,
+            workflow_id=self.workflow_id,
+        )
+
+    def record(self, body: dict[str, Any]) -> dict[str, Any]:
+        """``POST /v1/actions`` with the body as built (the SDK's ``_call`` so ``contract_version`` is kept)."""
+        return self.client._call("POST", "/v1/actions", body)
+
+
+class CommitLayerActivityInboundInterceptor(ActivityInboundInterceptor):
+    def __init__(self, next: ActivityInboundInterceptor, config: CommitLayerInterceptor) -> None:
+        super().__init__(next)
+        self.config = config
+
+    async def execute_activity(self, input: ExecuteActivityInput) -> Any:
+        info = activity.info()
+        try:
+            body = self.config.body_for(input, info)
+            if body is not None:
+                # urllib blocks; keep the worker's event loop free while the action is recorded.
+                rec = await asyncio.get_running_loop().run_in_executor(None, self.config.record, body)
+                if self.config.on_recorded:
+                    self.config.on_recorded(rec)
+        except Exception as e:  # noqa: BLE001 - the business activity must not depend on the verifier
+            if not self.config.fail_open:
+                raise ApplicationError(
+                    f"commitlayer: action not recorded for activity {info.activity_type}: {e}",
+                    type=RECORD_FAILED,
+                    non_retryable=True,
+                ) from e
+            log.warning(
+                "commitlayer: action not recorded for activity %s (workflow %s): %s",
+                info.activity_type,
+                info.workflow_id,
+                e,
+            )
+        return await self.next.execute_activity(input)

commitlayer_temporal/mapping.py

@@ -0,0 +1,207 @@
+"""From a Temporal activity invocation to the body of ``POST /v1/actions``.
+
+Pure: nothing here imports ``temporalio`` or talks to the network, so the exact body an activity produces can
+be asserted in a unit test. The interceptor in :mod:`commitlayer_temporal.interceptor` calls
+:func:`build_action_body` and posts the result unchanged.
+
+Paths
+-----
+A mapping names where the subject and the parameters live in the activity's arguments:
+
+* ``args.0.order_id`` -- the first positional argument's ``order_id`` (dict key or attribute);
+* ``kwargs.order_id`` -- the argument bound to the activity function's parameter ``order_id``;
+* ``order_id`` -- shorthand for ``kwargs.order_id``.
+
+Temporal delivers activity arguments positionally; ``kwargs.<name>`` works because the integration binds the
+arguments to the activity function's signature, so a mapping can use parameter names instead of positions.
+
+Templates
+---------
+``action_id`` (and nothing else) is a template over ``{workflow_id}``, ``{workflow_run_id}``, ``{activity_id}``,
+``{attempt}``, ``{activity}``, ``{subject_id}`` and every resolved parameter by name (``{amount}``). Without a
+template the action id is ``temporal:{workflow_id}:{activity_id}``: every retry attempt of one activity
+execution records the one action, because the API is idempotent on ``action_id``.
+"""
+
+from __future__ import annotations
+
+import inspect
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any
+
+CHANNEL = "temporal"
+DEFAULT_ACTION_ID = "temporal:{workflow_id}:{activity_id}"
+
+__all__ = [
+    "CHANNEL",
+    "DEFAULT_ACTION_ID",
+    "ActivityMapping",
+    "MappingError",
+    "TemporalRef",
+    "bind_kwargs",
+    "build_action_body",
+    "resolve_path",
+]
+
+
+class MappingError(LookupError):
+    """A path or template in an activity mapping could not be resolved against the invocation."""
+
+
+@dataclass(frozen=True)
+class ActivityMapping:
+    """What to record for one activity name.
+
+    ``subject`` and every value of ``params`` and ``compensates`` are paths (see the module docstring);
+    ``action_id`` is a template. ``contract_version`` pins the version the action is recorded under.
+    """
+
+    contract_id: str
+    subject: str
+    params: Mapping[str, str] = field(default_factory=dict)
+    action_id: str | None = None
+    action_type: str | None = None
+    subject_kind: str | None = None
+    compensates: str | None = None
+    contract_version: int | None = None
+
+    @classmethod
+    def coerce(cls, value: ActivityMapping | Mapping[str, Any]) -> ActivityMapping:
+        if isinstance(value, ActivityMapping):
+            return value
+        unknown = set(value) - {f for f in cls.__dataclass_fields__}
+        if unknown:
+            raise MappingError(f"unknown mapping keys: {sorted(unknown)}")
+        return cls(**dict(value))
+
+
+@dataclass(frozen=True)
+class TemporalRef:
+    """The Temporal identifiers an action carries; ``from_info`` reads them off ``temporalio.activity.Info``."""
+
+    workflow_id: str | None
+    activity_id: str
+    attempt: int
+    activity_type: str
+    workflow_run_id: str | None = None
+
+    @classmethod
+    def from_info(cls, info: Any) -> TemporalRef:
+        return cls(
+            workflow_id=getattr(info, "workflow_id", None),
+            activity_id=str(getattr(info, "activity_id", "")),
+            attempt=int(getattr(info, "attempt", 1)),
+            activity_type=str(getattr(info, "activity_type", "")),
+            workflow_run_id=getattr(info, "workflow_run_id", None),
+        )
+
+
+def bind_kwargs(fn: Callable[..., Any], args: Sequence[Any]) -> dict[str, Any]:
+    """The activity's positional arguments by parameter name (``self`` excluded for bound methods)."""
+    try:
+        bound = inspect.signature(fn).bind_partial(*args)
+    except (TypeError, ValueError):
+        return {}
+    bound.apply_defaults()
+    return dict(bound.arguments)
+
+
+def _step(value: Any, key: str, path: str) -> Any:
+    if isinstance(value, Mapping):
+        if key in value:
+            return value[key]
+        raise MappingError(f"{path!r}: no key {key!r}")
+    if isinstance(value, Sequence) and not isinstance(value, str | bytes):
+        try:
+            return value[int(key)]
+        except (ValueError, IndexError) as e:
+            raise MappingError(f"{path!r}: no index {key!r}") from e
+    if hasattr(value, key):
+        return getattr(value, key)
+    raise MappingError(f"{path!r}: {type(value).__name__} has no attribute {key!r}")
+
+
+def resolve_path(path: str, args: Sequence[Any], kwargs: Mapping[str, Any]) -> Any:
+    """Resolve ``args.N.x.y`` / ``kwargs.x.y`` / ``x.y`` (= ``kwargs.x.y``) against an invocation."""
+    if not isinstance(path, str) or not path:
+        raise MappingError(f"path must be a non-empty string, got {path!r}")
+    parts = path.split(".")
+    root, rest = parts[0], parts[1:]
+    if root == "args":
+        value: Any = list(args)
+    elif root == "kwargs":
+        value = dict(kwargs)
+    else:
+        value, rest = dict(kwargs), parts
+    for key in rest:
+        value = _step(value, key, path)
+    return value
+
+
+class _Fields(dict):
+    def __missing__(self, key: str) -> str:
+        raise MappingError(f"action_id template: unknown placeholder {{{key}}}")
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")  # noqa: UP017 - Python 3.10
+
+
+def build_action_body(
+    mapping: ActivityMapping | Mapping[str, Any],
+    *,
+    ref: TemporalRef,
+    args: Sequence[Any] = (),
+    kwargs: Mapping[str, Any] | None = None,
+    agent_id: str | None = None,
+    workflow_id: str | None = None,
+    requested_at: str | None = None,
+) -> dict[str, Any]:
+    """The exact ``POST /v1/actions`` body for one activity invocation.
+
+    ``workflow_id`` overrides the Temporal workflow id as the action's ``workflow_id``. ``requested_at``
+    defaults to now, which is before the activity runs, so the request time precedes every effect.
+    """
+    m = ActivityMapping.coerce(mapping)
+    kw = dict(kwargs or {})
+    subject_id = resolve_path(m.subject, args, kw)
+    if subject_id is None or subject_id == "":
+        raise MappingError(f"subject path {m.subject!r} resolved to nothing")
+    params: dict[str, Any] = {name: resolve_path(path, args, kw) for name, path in m.params.items()}
+    fields = _Fields(
+        params,
+        subject_id=str(subject_id),
+        workflow_id=ref.workflow_id or "",
+        workflow_run_id=ref.workflow_run_id or "",
+        activity_id=ref.activity_id,
+        attempt=ref.attempt,
+        activity=ref.activity_type,
+    )
+    action_id = (m.action_id or DEFAULT_ACTION_ID).format_map(fields)
+    if not action_id or len(action_id) > 120:
+        raise MappingError(f"action_id {action_id!r} must be 1-120 characters")
+
+    body: dict[str, Any] = {
+        "action_id": action_id,
+        "contract_id": m.contract_id,
+        "workflow_id": workflow_id or ref.workflow_id,
+        "subject_id": str(subject_id),
+        "requested_at": requested_at or _now(),
+        "params": {**params, "temporal_activity_id": ref.activity_id, "temporal_attempt": ref.attempt},
+        "channel": CHANNEL,
+    }
+    optional = (
+        ("agent_id", agent_id),
+        ("action_type", m.action_type),
+        ("subject_kind", m.subject_kind),
+        ("compensates", resolve_path(m.compensates, args, kw) if m.compensates else None),
+        ("contract_version", m.contract_version),
+    )
+    for key, value in optional:
+        if value is not None:
+            body[key] = value
+    if body["workflow_id"] is None:
+        del body["workflow_id"]
+    return body

commitlayer_temporal/verifier.py

@@ -0,0 +1,108 @@
+"""The workflow completion gate: an activity that waits for a CommitLayer verdict to settle.
+
+Each poll goes through the API's completion gate (``GET /v1/actions/{ref}/wait``), which holds the request for up
+to ``poll_seconds`` and returns the moment the verdict settles; the loop around it lives in
+:func:`commitlayer_integrations.verdict.poll_until_settled` and this module wraps it as a Temporal activity::
+
+    verifier = CommitLayerVerifier(Client())
+    Worker(..., activities=[refund_payment, verifier.commitlayer_verify], activity_executor=ThreadPoolExecutor(8))
+
+and, in the workflow, after the activities whose actions were recorded::
+
+    verdict = await workflow.execute_activity(
+        CommitLayerVerifier.commitlayer_verify,
+        args=["temporal:" + workflow.info().workflow_id + ":refund", 900],
+        start_to_close_timeout=timedelta(minutes=20),
+        heartbeat_timeout=timedelta(minutes=1),
+    )
+    if verdict["passed"]:
+        ...  # only now tell the customer it is done
+    elif verdict["status"] == "settled":
+        ...  # FAIL: run the compensation activity (its action should carry compensates=<this action id>)
+    else:
+        ...  # timed out while pending: the workflow decides (wait longer, escalate, or hold the confirmation)
+
+The activity is synchronous (the SDK's transport is ``urllib``), so the worker needs an ``activity_executor``.
+It heartbeats after every poll. A cancellation reaches a sync activity as ``CancelledError`` raised in its
+thread (Temporal's default); between polls the loop also checks ``activity.is_cancelled()`` and raises it.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+from commitlayer import Client
+from commitlayer_integrations.verdict import Verdict, fetch_verification, poll_until_settled
+from temporalio import activity
+from temporalio.exceptions import CancelledError
+
+__all__ = ["CommitLayerVerifier", "ACTIVITY_NAME"]
+
+log = logging.getLogger("commitlayer.temporal")
+
+ACTIVITY_NAME = "commitlayer_verify"
+
+
+class CommitLayerVerifier:
+    """Holds the client; ``commitlayer_verify`` is the activity to register on the worker.
+
+    ``default_timeout_seconds`` and ``poll_seconds`` apply when the workflow does not pass its own.
+    ``sleep`` and ``clock`` exist for tests.
+    """
+
+    def __init__(
+        self,
+        client: Client,
+        *,
+        default_timeout_seconds: float = 900.0,
+        poll_seconds: float = 5.0,
+        sleep: Callable[[float], None] | None = None,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        # The gate holds each poll server-side, so no local sleep is needed between polls; tests inject one.
+        self.client = client
+        self.default_timeout_seconds = default_timeout_seconds
+        self.poll_seconds = poll_seconds
+        self._sleep = sleep or (lambda s: None)
+        self._clock = clock
+
+    @activity.defn(name=ACTIVITY_NAME)
+    def commitlayer_verify(
+        self,
+        action_ref: str,
+        timeout_seconds: float | None = None,
+        poll_seconds: float | None = None,
+    ) -> dict[str, Any]:
+        """Wait on the completion gate (``GET /v1/actions/{action_ref}/wait``) until the verification settles
+        or the timeout passes; each call to the gate is held for at most ``poll_seconds`` and a heartbeat follows.
+
+        Returns a :class:`commitlayer_integrations.verdict.Verdict`: ``passed`` is true only for a settled PASS
+        under both lenses; ``timed_out`` is true when the deadline passed while the verdict was still
+        ``pending`` (or never verified). Both are JSON, so the workflow can branch on them and Temporal can
+        store them in history.
+        """
+        timeout = self.default_timeout_seconds if timeout_seconds is None else float(timeout_seconds)
+        poll = self.poll_seconds if poll_seconds is None else float(poll_seconds)
+
+        def heartbeat(v: Verdict) -> None:
+            activity.heartbeat({"status": v["status"], "outcome": v["outcome"], "policy": v["policy"]})
+
+        verdict = poll_until_settled(
+            lambda: fetch_verification(self.client, action_ref, poll),
+            timeout_seconds=timeout,
+            poll_seconds=poll,
+            sleep=self._sleep,
+            clock=self._clock,
+            on_poll=heartbeat,
+            should_stop=activity.is_cancelled,
+        )
+        if verdict["timed_out"] and activity.is_cancelled():
+            raise CancelledError(f"commitlayer_verify cancelled while {action_ref} was {verdict['status']}")
+        if verdict["timed_out"]:
+            log.warning(
+                "commitlayer: verdict for %s still %s after %.0fs", action_ref, verdict["status"], timeout
+            )
+        return dict(verdict)