openbox-temporal-sdk-python 1.0.0__py3-none-any.whl

openbox/types.py

@@ -0,0 +1,166 @@
+# openbox/types.py
+"""Data types for workflow-boundary governance."""
+
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional, Union
+from enum import Enum
+
+
+class WorkflowEventType(str, Enum):
+    """Workflow lifecycle events for governance."""
+
+    WORKFLOW_STARTED = "WorkflowStarted"
+    WORKFLOW_COMPLETED = "WorkflowCompleted"
+    WORKFLOW_FAILED = "WorkflowFailed"
+    SIGNAL_RECEIVED = "SignalReceived"
+    ACTIVITY_STARTED = "ActivityStarted"
+    ACTIVITY_COMPLETED = "ActivityCompleted"
+
+
+class Verdict(str, Enum):
+    """5-tier graduated response. Priority: HALT > BLOCK > REQUIRE_APPROVAL > CONSTRAIN > ALLOW"""
+
+    ALLOW = "allow"
+    CONSTRAIN = "constrain"
+    REQUIRE_APPROVAL = "require_approval"
+    BLOCK = "block"
+    HALT = "halt"
+
+    @classmethod
+    def from_string(cls, value: str) -> "Verdict":
+        """Parse with v1.0 compat: 'continue'→ALLOW, 'stop'→HALT, 'require-approval'→REQUIRE_APPROVAL"""
+        if value is None:
+            return cls.ALLOW
+        normalized = value.lower().replace("-", "_")
+        if normalized == "continue":
+            return cls.ALLOW
+        if normalized == "stop":
+            return cls.HALT
+        if normalized in ("require_approval", "request_approval"):
+            return cls.REQUIRE_APPROVAL
+        try:
+            return cls(normalized)
+        except ValueError:
+            return cls.ALLOW
+
+    @property
+    def priority(self) -> int:
+        """Priority for aggregation: HALT=5, BLOCK=4, REQUIRE_APPROVAL=3, CONSTRAIN=2, ALLOW=1"""
+        return {Verdict.ALLOW: 1, Verdict.CONSTRAIN: 2, Verdict.REQUIRE_APPROVAL: 3, Verdict.BLOCK: 4, Verdict.HALT: 5}[self]
+
+    @classmethod
+    def highest_priority(cls, verdicts: List["Verdict"]) -> "Verdict":
+        """Get highest priority verdict from list. Returns ALLOW if empty."""
+        return max(verdicts, key=lambda v: v.priority) if verdicts else cls.ALLOW
+
+    def should_stop(self) -> bool:
+        """True if BLOCK or HALT."""
+        return self in (Verdict.BLOCK, Verdict.HALT)
+
+    def requires_approval(self) -> bool:
+        """True if REQUIRE_APPROVAL."""
+        return self == Verdict.REQUIRE_APPROVAL
+
+
+@dataclass
+class WorkflowSpanBuffer:
+    """Buffer for spans generated during workflow execution."""
+
+    workflow_id: str
+    run_id: str
+    workflow_type: str
+    task_queue: str
+    parent_workflow_id: Optional[str] = None
+    spans: List[dict] = field(default_factory=list)
+    status: Optional[str] = None  # "completed", "failed", "cancelled", "terminated"
+    error: Optional[Dict[str, Any]] = None
+
+    # Governance verdict (set by workflow interceptor, checked by activity interceptor)
+    verdict: Optional[Verdict] = None
+    verdict_reason: Optional[str] = None
+
+    # Pending approval: True when activity is waiting for human approval
+    pending_approval: bool = False
+
+
+@dataclass
+class GuardrailsCheckResult:
+    """
+    Guardrails check result from governance API.
+
+    Contains redacted input/output that should replace the original activity data,
+    plus validation results that can block execution.
+    """
+
+    redacted_input: Any  # Redacted activity_input or activity_output (JSON-decoded)
+    input_type: str  # "activity_input" or "activity_output"
+    raw_logs: Optional[Dict[str, Any]] = None  # Raw logs from guardrails evaluation
+    validation_passed: bool = True  # If False, workflow should be stopped
+    reasons: List[Dict[str, str]] = field(default_factory=list)  # [{type, field, reason}, ...]
+
+    def get_reason_strings(self) -> List[str]:
+        """Extract just the 'reason' field from each reason object."""
+        return [r.get("reason", "") for r in self.reasons if r.get("reason")]
+
+
+@dataclass
+class GovernanceVerdictResponse:
+    """Response from governance API evaluation."""
+
+    verdict: Verdict  # v1.1: 5-tier verdict
+    reason: Optional[str] = None
+    # v1.0 fields (kept for compatibility)
+    policy_id: Optional[str] = None
+    risk_score: float = 0.0
+    metadata: Optional[Dict[str, Any]] = None
+    governance_event_id: Optional[str] = None
+    guardrails_result: Optional[GuardrailsCheckResult] = None
+    # v1.1 fields
+    trust_tier: Optional[str] = None
+    behavioral_violations: Optional[List[str]] = None
+    alignment_score: Optional[float] = None
+    approval_id: Optional[str] = None
+    constraints: Optional[List[Dict[str, Any]]] = None
+
+    @property
+    def action(self) -> str:
+        """Backward compat: return action string from verdict."""
+        if self.verdict == Verdict.ALLOW:
+            return "continue"
+        if self.verdict == Verdict.HALT:
+            return "stop"
+        if self.verdict == Verdict.REQUIRE_APPROVAL:
+            return "require-approval"
+        return self.verdict.value
+
+    @classmethod
+    def from_dict(cls, data: Dict[str, Any]) -> "GovernanceVerdictResponse":
+        """Parse governance response from JSON dict (v1.0 and v1.1 compatible)."""
+        guardrails_result = None
+        if data.get("guardrails_result"):
+            gr = data["guardrails_result"]
+            guardrails_result = GuardrailsCheckResult(
+                redacted_input=gr.get("redacted_input"),
+                input_type=gr.get("input_type", ""),
+                raw_logs=gr.get("raw_logs"),
+                validation_passed=gr.get("validation_passed", True),
+                reasons=gr.get("reasons") or [],
+            )
+
+        # Parse verdict (v1.1) or action (v1.0)
+        verdict = Verdict.from_string(data.get("verdict") or data.get("action", "continue"))
+
+        return cls(
+            verdict=verdict,
+            reason=data.get("reason"),
+            policy_id=data.get("policy_id"),
+            risk_score=data.get("risk_score", 0.0),
+            metadata=data.get("metadata"),
+            governance_event_id=data.get("governance_event_id"),
+            guardrails_result=guardrails_result,
+            trust_tier=data.get("trust_tier"),
+            behavioral_violations=data.get("behavioral_violations"),
+            alignment_score=data.get("alignment_score"),
+            approval_id=data.get("approval_id"),
+            constraints=data.get("constraints"),
+        )

openbox/worker.py

@@ -0,0 +1,257 @@
+# openbox/worker.py
+"""
+OpenBox-enabled Temporal Worker factory.
+
+Provides a simple function to create a Temporal Worker with all OpenBox
+governance components pre-configured.
+
+Usage:
+    from openbox import create_openbox_worker
+
+    worker = await create_openbox_worker(
+        client=client,
+        task_queue="my-queue",
+        workflows=[MyWorkflow],
+        activities=[my_activity],
+    )
+
+    await worker.run()
+"""
+
+from datetime import timedelta
+from typing import (
+    Any,
+    Awaitable,
+    Callable,
+    Optional,
+    Sequence,
+    Type,
+)
+from concurrent.futures import Executor, ThreadPoolExecutor
+
+from temporalio.client import Client
+from temporalio.worker import Worker, Interceptor
+
+from .config import initialize as validate_api_key, GovernanceConfig
+from .span_processor import WorkflowSpanProcessor
+
+
+def create_openbox_worker(
+    client: Client,
+    task_queue: str,
+    *,
+    workflows: Sequence[Type] = (),
+    activities: Sequence[Callable] = (),
+    # OpenBox config (required for governance)
+    openbox_url: Optional[str] = None,
+    openbox_api_key: Optional[str] = None,
+    governance_timeout: float = 30.0,
+    governance_policy: str = "fail_open",
+    send_start_event: bool = True,
+    send_activity_start_event: bool = True,
+    skip_workflow_types: Optional[set] = None,
+    skip_activity_types: Optional[set] = None,
+    skip_signals: Optional[set] = None,
+    # HITL configuration
+    hitl_enabled: bool = True,
+    # Database instrumentation
+    instrument_databases: bool = True,
+    db_libraries: Optional[set] = None,
+    # File I/O instrumentation
+    instrument_file_io: bool = False,
+    # Standard Worker options
+    activity_executor: Optional[Executor] = None,
+    workflow_task_executor: Optional[ThreadPoolExecutor] = None,
+    interceptors: Sequence[Interceptor] = (),
+    build_id: Optional[str] = None,
+    identity: Optional[str] = None,
+    max_cached_workflows: int = 1000,
+    max_concurrent_workflow_tasks: Optional[int] = None,
+    max_concurrent_activities: Optional[int] = None,
+    max_concurrent_local_activities: Optional[int] = None,
+    max_concurrent_workflow_task_polls: int = 5,
+    nonsticky_to_sticky_poll_ratio: float = 0.2,
+    max_concurrent_activity_task_polls: int = 5,
+    no_remote_activities: bool = False,
+    sticky_queue_schedule_to_start_timeout: timedelta = timedelta(seconds=10),
+    max_heartbeat_throttle_interval: timedelta = timedelta(seconds=60),
+    default_heartbeat_throttle_interval: timedelta = timedelta(seconds=30),
+    max_activities_per_second: Optional[float] = None,
+    max_task_queue_activities_per_second: Optional[float] = None,
+    graceful_shutdown_timeout: timedelta = timedelta(),
+    shared_state_manager: Any = None,
+    debug_mode: bool = False,
+    disable_eager_activity_execution: bool = False,
+    on_fatal_error: Optional[Callable[[BaseException], Awaitable[None]]] = None,
+    use_worker_versioning: bool = False,
+    disable_safe_workflow_eviction: bool = False,
+) -> Worker:
+    """
+    Create a Temporal Worker with OpenBox governance enabled.
+
+    This function:
+    1. Validates the OpenBox API key
+    2. Sets up OpenTelemetry HTTP instrumentation
+    3. Creates governance interceptors
+    4. Returns a fully configured Worker
+
+    Args:
+        client: Temporal client
+        task_queue: Task queue name
+        workflows: List of workflow classes
+        activities: List of activity functions (OpenBox activities added automatically)
+
+        # OpenBox config
+        openbox_url: OpenBox Core API URL (required for governance)
+        openbox_api_key: OpenBox API key (required for governance)
+        governance_timeout: Timeout for governance API calls (default: 30.0s)
+        governance_policy: "fail_open" or "fail_closed" (default: "fail_open")
+        send_start_event: Send WorkflowStarted events (default: True)
+        send_activity_start_event: Send ActivityStarted events (default: True)
+        skip_workflow_types: Workflow types to skip governance
+        skip_activity_types: Activity types to skip governance
+        skip_signals: Signal names to skip governance
+
+        # Database instrumentation
+        instrument_databases: Instrument database libraries (default: True)
+        db_libraries: Set of database libraries to instrument (None = all available).
+                      Valid values: "psycopg2", "asyncpg", "mysql", "pymysql",
+                      "pymongo", "redis", "sqlalchemy"
+
+        # File I/O instrumentation
+        instrument_file_io: Instrument file I/O operations (default: False)
+
+        # Standard Worker options (passed through to Worker)
+        activity_executor: Executor for activities
+        interceptors: Additional interceptors (OpenBox interceptors added automatically)
+        ... (all other standard Worker options)
+
+    Returns:
+        Configured Worker instance
+
+    Example:
+        ```python
+        from openbox import create_openbox_worker
+
+        client = await Client.connect("localhost:7233")
+
+        worker = create_openbox_worker(
+            client=client,
+            task_queue="my-queue",
+            workflows=[MyWorkflow],
+            activities=[my_activity, another_activity],
+            openbox_url="http://localhost:8086",
+            openbox_api_key="obx_test_key_1",
+            governance_policy="fail_closed",
+        )
+
+        await worker.run()
+        ```
+    """
+    # Build interceptors and activities lists
+    all_interceptors = list(interceptors)
+    all_activities = list(activities)
+
+    # Initialize OpenBox if configured
+    if openbox_url and openbox_api_key:
+        print(f"Initializing OpenBox SDK with URL: {openbox_url}")
+
+        # 1. Validate API key
+        validate_api_key(
+            api_url=openbox_url,
+            api_key=openbox_api_key,
+            governance_timeout=governance_timeout,
+        )
+
+        # 2. Create span processor
+        span_processor = WorkflowSpanProcessor(ignored_url_prefixes=[openbox_url])
+
+        # 3. Setup OTel HTTP, database, and file I/O instrumentation
+        from .otel_setup import setup_opentelemetry_for_governance
+        setup_opentelemetry_for_governance(
+            span_processor,
+            ignored_urls=[openbox_url],
+            instrument_databases=instrument_databases,
+            db_libraries=db_libraries,
+            instrument_file_io=instrument_file_io,
+        )
+
+        # 4. Create governance config
+        config = GovernanceConfig(
+            on_api_error=governance_policy,
+            api_timeout=governance_timeout,
+            send_start_event=send_start_event,
+            send_activity_start_event=send_activity_start_event,
+            skip_workflow_types=skip_workflow_types or set(),
+            skip_activity_types=skip_activity_types or {"send_governance_event"},
+            skip_signals=skip_signals or set(),
+            hitl_enabled=hitl_enabled,
+        )
+
+        # 5. Create interceptors
+        from .workflow_interceptor import GovernanceInterceptor
+        from .activity_interceptor import ActivityGovernanceInterceptor
+
+        workflow_interceptor = GovernanceInterceptor(
+            api_url=openbox_url,
+            api_key=openbox_api_key,
+            span_processor=span_processor,
+            config=config,
+        )
+
+        activity_interceptor = ActivityGovernanceInterceptor(
+            api_url=openbox_url,
+            api_key=openbox_api_key,
+            span_processor=span_processor,
+            config=config,
+        )
+
+        # 6. Get governance activities
+        from .activities import send_governance_event
+
+        # Add OpenBox components
+        all_interceptors = [workflow_interceptor, activity_interceptor, *interceptors]
+        all_activities = [*activities, send_governance_event]
+
+        print("OpenBox SDK initialized successfully")
+        print(f"  - Governance policy: {governance_policy}")
+        print(f"  - Governance timeout: {governance_timeout}s")
+        print("  - Events: WorkflowStarted, WorkflowCompleted, WorkflowFailed, SignalReceived, ActivityStarted, ActivityCompleted")
+        print(f"  - Database instrumentation: {'enabled' if instrument_databases else 'disabled'}")
+        print(f"  - File I/O instrumentation: {'enabled' if instrument_file_io else 'disabled'}")
+        print(f"  - Approval polling: {'enabled' if hitl_enabled else 'disabled'}")
+    else:
+        print("OpenBox SDK not configured (openbox_url and openbox_api_key not provided)")
+
+    # Create and return Worker
+    return Worker(
+        client,
+        task_queue=task_queue,
+        workflows=workflows,
+        activities=all_activities,
+        activity_executor=activity_executor,
+        workflow_task_executor=workflow_task_executor,
+        interceptors=all_interceptors,
+        build_id=build_id,
+        identity=identity,
+        max_cached_workflows=max_cached_workflows,
+        max_concurrent_workflow_tasks=max_concurrent_workflow_tasks,
+        max_concurrent_activities=max_concurrent_activities,
+        max_concurrent_local_activities=max_concurrent_local_activities,
+        max_concurrent_workflow_task_polls=max_concurrent_workflow_task_polls,
+        nonsticky_to_sticky_poll_ratio=nonsticky_to_sticky_poll_ratio,
+        max_concurrent_activity_task_polls=max_concurrent_activity_task_polls,
+        no_remote_activities=no_remote_activities,
+        sticky_queue_schedule_to_start_timeout=sticky_queue_schedule_to_start_timeout,
+        max_heartbeat_throttle_interval=max_heartbeat_throttle_interval,
+        default_heartbeat_throttle_interval=default_heartbeat_throttle_interval,
+        max_activities_per_second=max_activities_per_second,
+        max_task_queue_activities_per_second=max_task_queue_activities_per_second,
+        graceful_shutdown_timeout=graceful_shutdown_timeout,
+        shared_state_manager=shared_state_manager,
+        debug_mode=debug_mode,
+        disable_eager_activity_execution=disable_eager_activity_execution,
+        on_fatal_error=on_fatal_error,
+        use_worker_versioning=use_worker_versioning,
+        disable_safe_workflow_eviction=disable_safe_workflow_eviction,
+    )

openbox/workflow_interceptor.py

@@ -0,0 +1,264 @@
+# openbox/workflow_interceptor.py
+"""
+Temporal workflow interceptor for workflow-boundary governance.
+
+Sends workflow lifecycle events via activity (for determinism).
+
+Events:
+- WorkflowStarted
+- WorkflowCompleted
+- WorkflowFailed
+- SignalReceived
+
+IMPORTANT: No logging inside workflow code! Python's logging module uses
+linecache -> os.stat which triggers Temporal sandbox restrictions.
+"""
+
+import json
+from dataclasses import asdict, is_dataclass
+from datetime import timedelta
+from typing import Any, Optional, Type
+
+from temporalio import workflow
+from temporalio.worker import (
+    Interceptor,
+    WorkflowInboundInterceptor,
+    WorkflowInterceptorClassInput,
+    ExecuteWorkflowInput,
+    HandleSignalInput,
+)
+
+from .types import Verdict
+
+
+def _serialize_value(value: Any) -> Any:
+    """Convert a value to JSON-serializable format for workflow result."""
+    if value is None:
+        return None
+    if isinstance(value, (str, int, float, bool)):
+        return value
+    if isinstance(value, bytes):
+        try:
+            return value.decode('utf-8')
+        except Exception:
+            import base64
+            return base64.b64encode(value).decode('ascii')
+    if is_dataclass(value) and not isinstance(value, type):
+        return asdict(value)
+    if isinstance(value, (list, tuple)):
+        return [_serialize_value(v) for v in value]
+    if isinstance(value, dict):
+        return {k: _serialize_value(v) for k, v in value.items()}
+    try:
+        return json.loads(json.dumps(value, default=str))
+    except Exception:
+        return str(value)
+
+
+class GovernanceHaltError(Exception):
+    """Raised when governance halts workflow execution."""
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+async def _send_governance_event(
+    api_url: str,
+    api_key: str,
+    payload: dict,
+    timeout: float,
+    on_api_error: str = "fail_open",
+) -> Optional[dict]:
+    """
+    Send governance event via activity.
+
+    Args:
+        on_api_error: "fail_open" (default) = continue on error
+                      "fail_closed" = halt workflow if governance API fails
+
+    The on_api_error policy is passed to the activity, which handles logging
+    (safe outside sandbox) and raises GovernanceAPIError if fail_closed.
+    This interceptor catches that and re-raises as GovernanceHaltError.
+    """
+    try:
+        result = await workflow.execute_activity(
+            "send_governance_event",
+            args=[{
+                "api_url": api_url,
+                "api_key": api_key,
+                "payload": payload,
+                "timeout": timeout,
+                "on_api_error": on_api_error,
+            }],
+            start_to_close_timeout=timedelta(seconds=timeout + 5),
+        )
+        return result
+    except Exception as e:
+        error_str = str(e)
+        error_type = type(e).__name__
+
+        # ApplicationError with type="GovernanceStop" (non-retryable, terminates workflow)
+        # This is raised when governance API returns action='stop'
+        if "ApplicationError" in error_type or "Governance blocked:" in error_str:
+            raise GovernanceHaltError(error_str)
+
+        # Activity raised GovernanceAPIError (fail_closed and API unreachable)
+        if "GovernanceAPIError" in error_type or "GovernanceAPIError" in error_str:
+            raise GovernanceHaltError(error_str)
+
+        # Other errors with fail_open: silently continue
+        return None
+
+
+class GovernanceInterceptor(Interceptor):
+    """Factory for workflow interceptor. Events sent via activity for determinism."""
+
+    def __init__(
+        self,
+        api_url: str,
+        api_key: str,
+        span_processor=None,  # Shared with activity interceptor for HTTP spans
+        config=None,  # Optional GovernanceConfig
+    ):
+        self.api_url = api_url.rstrip("/")
+        self.api_key = api_key
+        self.span_processor = span_processor
+        self.api_timeout = getattr(config, 'api_timeout', 30.0) if config else 30.0
+        self.on_api_error = getattr(config, 'on_api_error', 'fail_open') if config else 'fail_open'
+        self.send_start_event = getattr(config, 'send_start_event', True) if config else True
+        self.skip_workflow_types = getattr(config, 'skip_workflow_types', set()) if config else set()
+        self.skip_signals = getattr(config, 'skip_signals', set()) if config else set()
+
+    def workflow_interceptor_class(
+        self, input: WorkflowInterceptorClassInput
+    ) -> Optional[Type[WorkflowInboundInterceptor]]:
+        # Capture via closure
+        api_url = self.api_url
+        api_key = self.api_key
+        span_processor = self.span_processor
+        timeout = self.api_timeout
+        on_error = self.on_api_error
+        send_start = self.send_start_event
+        skip_types = self.skip_workflow_types
+        skip_sigs = self.skip_signals
+
+        class _Inbound(WorkflowInboundInterceptor):
+            async def execute_workflow(self, input: ExecuteWorkflowInput) -> Any:
+                info = workflow.info()
+
+                # Skip if configured
+                if info.workflow_type in skip_types:
+                    return await super().execute_workflow(input)
+
+                # WorkflowStarted event
+                if send_start and workflow.patched("openbox-v2-start"):
+                    await _send_governance_event(api_url, api_key, {
+                        "source": "workflow-telemetry",
+                        "event_type": "WorkflowStarted",
+                        "workflow_id": info.workflow_id,
+                        "run_id": info.run_id,
+                        "workflow_type": info.workflow_type,
+                        "task_queue": info.task_queue,
+                    }, timeout, on_error)
+
+                # Execute workflow
+                error = None
+                try:
+                    result = await super().execute_workflow(input)
+
+                    # WorkflowCompleted event (success)
+                    if workflow.patched("openbox-v2-complete"):
+                        # Serialize workflow result for governance
+                        workflow_output = None
+                        try:
+                            workflow_output = _serialize_value(result)
+                        except Exception:
+                            workflow_output = str(result) if result is not None else None
+
+                        await _send_governance_event(api_url, api_key, {
+                            "source": "workflow-telemetry",
+                            "event_type": "WorkflowCompleted",
+                            "workflow_id": info.workflow_id,
+                            "run_id": info.run_id,
+                            "workflow_type": info.workflow_type,
+                            "workflow_output": workflow_output,
+                        }, timeout, on_error)
+
+                    return result
+                except Exception as e:
+                    # Extract error details, including nested cause for ActivityError
+                    error = {
+                        "type": type(e).__name__,
+                        "message": str(e),
+                    }
+
+                    # Get cause using Temporal's .cause property or Python's __cause__/__context__
+                    cause = getattr(e, 'cause', None) or e.__cause__ or e.__context__
+
+                    if cause:
+                        error["cause"] = {
+                            "type": type(cause).__name__,
+                            "message": str(cause),
+                        }
+                        # Check for ApplicationError details (e.g., GovernanceStop)
+                        if hasattr(cause, 'type') and cause.type:
+                            error["cause"]["error_type"] = cause.type
+                        if hasattr(cause, 'non_retryable'):
+                            error["cause"]["non_retryable"] = cause.non_retryable
+
+                        # Go deeper if there's another cause
+                        deeper_cause = getattr(cause, 'cause', None) or getattr(cause, '__cause__', None)
+                        if deeper_cause:
+                            error["root_cause"] = {
+                                "type": type(deeper_cause).__name__,
+                                "message": str(deeper_cause),
+                            }
+                            if hasattr(deeper_cause, 'type') and deeper_cause.type:
+                                error["root_cause"]["error_type"] = deeper_cause.type
+
+                    # WorkflowFailed event
+                    if workflow.patched("openbox-v2-failed"):
+                        await _send_governance_event(api_url, api_key, {
+                            "source": "workflow-telemetry",
+                            "event_type": "WorkflowFailed",
+                            "workflow_id": info.workflow_id,
+                            "run_id": info.run_id,
+                            "workflow_type": info.workflow_type,
+                            "error": error,
+                        }, timeout, on_error)
+
+                    raise
+
+            async def handle_signal(self, input: HandleSignalInput) -> None:
+                info = workflow.info()
+
+                # Skip if configured
+                if input.signal in skip_sigs or info.workflow_type in skip_types:
+                    return await super().handle_signal(input)
+
+                # SignalReceived event - check verdict and store if "stop"
+                if workflow.patched("openbox-v2-signal"):
+                    result = await _send_governance_event(api_url, api_key, {
+                        "source": "workflow-telemetry",
+                        "event_type": "SignalReceived",
+                        "workflow_id": info.workflow_id,
+                        "run_id": info.run_id,
+                        "workflow_type": info.workflow_type,
+                        "task_queue": info.task_queue,
+                        "signal_name": input.signal,
+                        "signal_args": input.args,
+                    }, timeout, on_error)
+
+                    # If governance returned BLOCK/HALT, store verdict for activity interceptor
+                    # The next activity will check this and fail with GovernanceStop
+                    verdict = Verdict.from_string(result.get("verdict") or result.get("action")) if result else Verdict.ALLOW
+                    if verdict.should_stop() and span_processor:
+                        span_processor.set_verdict(
+                            info.workflow_id,
+                            verdict,
+                            result.get("reason"),
+                            info.run_id,  # Include run_id to detect stale verdicts
+                        )
+
+                await super().handle_signal(input)
+
+        return _Inbound