openbox-temporal-sdk-python 1.1.1__tar.gz → 1.2.0__tar.gz

{openbox_temporal_sdk_python-1.1.1 → openbox_temporal_sdk_python-1.2.0}/.gitignore

@@ -40,3 +40,4 @@ AGENTS.md
 .claude/
 CLAUDE.md
 plans/
+_notes/

openbox_temporal_sdk_python-1.2.0/CHANGELOG.md

@@ -0,0 +1,238 @@
+# Changelog
+
+All notable changes to OpenBox SDK for Temporal Workflows.
+
+## [Unreleased]
+
+## [1.2.0] - 2026-07-20
+
+### Changed
+
+- **Depends on `openbox-sdk-python>=0.2.0`** (import package `openbox_core`) — the shared
+  base SDK owning contracts, the always-strict gate, identity/signing, the evaluate
+  client, context runtime, Core `SpanData` wire serialization, generic instrumentation,
+  and the conformance kit. The `0.2.0` floor adds Redis/MongoDB/urllib3/urllib
+  instrumentation in the base runtime so no hook coverage is lost in the flip.
+- **Hook governance is now owned entirely by the base runtime.** The worker/plugin
+  build and own an `openbox_core` runtime and call `install_instrumentation()`;
+  HTTP/DB/file/function hooks, payload shape, evaluation, and enforcement all live in
+  `openbox_core`. LangGraph and Temporal now emit one identical flat hook interface.
+- `request_signing` now shims over `openbox_core.identity`. Signed request bytes are
+  UNCHANGED — gated byte-for-byte by a golden fixture generated from the pre-migration
+  signer (`tests/test_base_sdk_signing_parity.py`).
+- `Verdict`, `GuardrailsCheckResult`, and `WorkflowEventType` re-export the shared
+  contracts; `GovernanceVerdictResponse` subclasses the shared `EvaluationResult`
+  (same public surface, plus `fallback_used`/`diagnostics`/`raw`/`approval_expiration_time`).
+- Workflow lifecycle events route through shared `EventEnvelope` factories
+  (sandbox-safe pure contracts; wire payloads unchanged).
+- Activity execution binds the shared `ActivityContext` with a guaranteed
+  try/finally reset — governance context can no longer leak when an activity raises.
+
+### Behavior changes (regression-gated)
+
+- **Approval decision precedence:** approval poll responses parse via the shared
+  `ApprovalResult`; `action` now outranks `verdict` when both are present
+  (previously verdict-first), and a response with NEITHER field stays PENDING
+  (previously implicit ALLOW). Pinned by `tests/test_approval_action_precedence.py`.
+
+### Known behavior differences in the core runtime
+
+- **Completed-hook semantics:** core completed hooks never raise to the caller —
+  stop verdicts mark FUTURE execution blocked (abort/halt flags). Some legacy
+  completed hooks could raise after the operation ran (HTTP response hook, file
+  close); raising post-hoc cannot undo the operation, so the core model drops it
+  by design.
+- **Fail-closed shaping:** core maps started-hook evaluation failures under
+  `on_api_error="fail_closed"` (and started-hook contract errors, always) to a
+  non-retryable `GovernanceHalt` via the adapter — same terminal effect as
+  legacy's HALT-shaped `GovernanceBlockedError`, different exception chain.
+- **Redaction point for `activity_input`:** the core `ActivityContext` receives
+  the post-redaction input (what actually ran); the legacy buffer stored the
+  pre-redaction value. Core hook payloads therefore never leak redacted fields.
+
+### Added
+
+- `openbox.governance_state.TemporalGovernanceState` — run-scoped state carrying the
+  Temporal effects that must survive past a base hook callback: signal BLOCK/HALT
+  verdicts that fail the next activity, HITL pending-approval retry markers, and the
+  completed-hook stop bridge (completed BLOCK skips the duplicate completed event;
+  completed HALT reaches the terminate path). Consumed on every activity exit path.
+- `openbox.core_adapter` — `TemporalFrameworkAdapter` (maps base-SDK verdicts to
+  native `ApplicationError` types and the retry-based HITL loop; REQUIRE_APPROVAL marks
+  the pending-approval retry marker and degrades to a non-retryable block when HITL is
+  disabled/skipped; completed BLOCK/HALT records run-scoped stop state with the resolved
+  `ActivityContext`), and `create_core_runtime(...)` which builds and owns the base
+  runtime the worker/plugin install. `core_activity_scope` is the sole hook-context
+  bridge (guaranteed try/finally reset + trace registration).
+- Redis, MongoDB, urllib3, and urllib governance now flow through the base runtime.
+- Gates: workflow-sandbox import-safety, base-SDK conformance suite driven by the
+  Temporal adapter, public-API compatibility suite, and a deterministic
+  `llm_completion` hook-parity test (flat interface via the Temporal runtime, no live
+  OpenAI credentials).
+
+### Removed
+
+- `WorkflowSpanProcessor`, `WorkflowSpanBuffer`, and the `setup_opentelemetry_for_governance`
+  entry point (public exports). Governance instrumentation is installed by the base
+  runtime; there is no Temporal-local OpenTelemetry setup to call.
+- Temporal-local hook modules `otel_setup`, `hook_governance`, `http_governance_hooks`,
+  `db_governance_hooks`, `file_governance_hooks`, `span_processor`, and the dead
+  `context_propagation` helper (its ContextVar-to-executor propagation lives in the base
+  runtime). Their payload-shape/instrumentation coverage moved to the base SDK suite.
+- `openbox.tracing.traced` now wraps `openbox_core.instrumentation.function.governed`;
+  `create_span` remains a plain span helper.
+
+### Fixed (legacy file instrumentation — pre-existing upstream)
+
+- **Runtime RecursionError under file instrumentation:** governance evaluation
+  itself opens files (httpx/ssl, package-metadata scans via importlib_metadata/
+  zipp) — governing those opens re-evaluated recursively until RecursionError.
+  traced_open now (1) passes through any open performed on a thread already
+  inside file-governance work (re-entrancy guard) and (2) bypasses
+  interpreter-owned trees (venv, stdlib, site-packages — sys.prefix/base_prefix
+  + sysconfig paths): those reads are Python machinery, not application data
+  access. Application paths (./.env, data files, temp files) remain governed.
+  Same guard mirrored in the base SDK's file instrumentation.
+
+### Fixed (HTTP hook payloads — pre-existing upstream)
+
+- **Mangled method on httpx spans:** OTel's httpx instrumentation passes the
+  method as BYTES; `str(b"POST")` shipped `http_method: "b'POST'"` on every
+  httpx started span. Methods now decode bytes-safely at all client paths.
+- **Credential leak in governance payloads:** raw request/response headers
+  (`authorization`, `cookie`, `set-cookie`, `x-api-key`, …) were sent to Core
+  verbatim — live API keys landed in Core logs. All header dicts are now
+  redacted at the span-data builder choke point. Same redaction added to the
+  base SDK instrumentation. **Rotate any API keys that appeared in payloads.**
+
+### Migration notes
+
+- Base-runtime instrumentation is the sole hook governance path
+  and the legacy in-repo hook stack is removed. Approval-retry, signal BLOCK/HALT, and
+  completed-hook BLOCK/HALT behavior are preserved (run-scoped, cleaned after use).
+- Dropped coverage vs the legacy stack: direct raw-driver DB queries (psycopg2/mysql/
+  pymysql/sqlite3 used WITHOUT SQLAlchemy). The base runtime governs SQLAlchemy (all
+  backends), asyncpg, Redis, and MongoDB; activating raw dbapi driver instrumentors
+  interferes with SQLAlchemy's own dialect queries, so raw-driver-only governance is a
+  base-SDK follow-up.
+
+## [1.1.2] - 2026-04-22
+
+### Security
+
+- **API key no longer flows through workflow history.** `send_governance_event` refactored into a `GovernanceActivities` class that holds credentials on `self`; activity inputs carry only `payload`, `timeout`, and `on_api_error`. Before this change, anyone with Describe permissions on the namespace could read the API key from the recorded activity input.
+
+### Added
+
+- W3C trace propagation through Temporal headers, on by default via `enable_trace_propagation=True` on `OpenBoxPlugin` and `create_openbox_worker()`. Uses `temporalio.contrib.opentelemetry.TracingInterceptor` so spans started by the caller stitch to workflow/activity spans on the worker side.
+- `ApplicationError` type constants in `errors.py` (`GOVERNANCE_HALT_ERROR_TYPE`, `GOVERNANCE_BLOCK_ERROR_TYPE`, `GOVERNANCE_API_ERROR_TYPE`, `GOVERNANCE_STOP_ERROR_TYPE`) — single source of truth for governance error routing.
+- `openbox.activities.GovernanceActivities` class + `build_governance_activities()` factory.
+
+### Fixed
+
+- **Workflow exception shadowing** — `WorkflowFailed` event send is now wrapped in `try/except`, so a `GovernanceHaltError` from `fail_closed + API down` no longer replaces the real workflow error.
+- **String-matching on exception types** — `workflow_interceptor` now inspects `ApplicationError.type` via the exception chain instead of `"GovernanceHalt" in str(e)`. Eliminates false positives when a user workflow happens to emit an error message containing a governance keyword.
+- **Race creating governance HTTP client** — `hook_governance._get_sync_client` / `_get_async_client` now use double-checked locking. Previously two concurrent activities could each create a client, with the losing instance getting garbage-collected while its connection pool leaked.
+- **Replayer plugin coverage** — `test_plugin_integration.py` now passes `plugins=[plugin]` to `Replayer`, so replay tests validate interceptor determinism, not just user workflow code.
+- Version-pin mismatch — comments in `openbox/__init__.py` said `temporalio >= 1.24.0` but pyproject/README pin `1.23.0`. Corrected to `1.23.0`.
+
+### Changed
+
+- `plugin.py` / `worker.py` now use `logging.getLogger(__name__)` for initialization status messages instead of `print()`.
+
+## [1.1.1] - 2026-04-07
+
+### Added
+
+- **OpenBoxPlugin** — drop-in `SimplePlugin` integration for Temporal Workers. Single-line setup: `plugins=[OpenBoxPlugin(openbox_url=..., openbox_api_key=...)]`. Auto-registers interceptors, OTel instrumentation, sandbox passthrough, and `send_governance_event` activity
+- Plugin integration guide for Temporal AI Partner Ecosystem (`docs/temporal-plugin-integration-guide.md`)
+- HTTP body truncation tests (`tests/test_http_body_truncation.py`)
+- Plugin unit tests (`tests/test_plugin.py`) and integration/replay tests (`tests/test_plugin_integration.py`)
+
+### Fixed
+
+- **HTTP body truncation** — enforce `max_body_size` (default 64KB) on request/response bodies in governance spans
+- **File I/O spans** — remove raw file content from governance payloads; only `bytes_read`/`bytes_written` metadata sent
+- **error_type sanitization** — prevent serialized error objects from being sent as `error.cause.error_type` string in WorkflowFailed payloads
+- Remove useless f-strings, redundant `(ImportError, Exception)` clauses, merge nested if statements
+- Prefix unused `span` param in urllib hook
+
+### Changed
+
+- `temporalio>=1.23.0` (from 1.8.0) for SimplePlugin support
+- `GovernanceConfig.max_body_size` default changed from `None` (unlimited) to `65536` (64KB)
+- `\w` regex shorthand in API key pattern
+
+### Refactored
+
+- Reduce cognitive complexity across 7 modules: `activity_interceptor.py` (126→split), `workflow_interceptor.py` (40→split), `activities.py` (20→split), `db_governance_hooks.py` (34→split), `otel_setup.py` (51→split), `tracing.py` (85→split), `verdict_handler.py` (16→15)
+- Extract shared helpers: `_run_governed_query_sync/async`, `_build_error_dict`, `_extract_dbapi_context`, `_instrument_sqlalchemy`
+
+### Dependencies
+
+- Bump Pygments 2.19.2 → 2.20.0 (ReDoS fix, CVSS 1.9)
+
+## [1.1.0] - 2026-03-09
+
+### Added
+
+- **Hook-level governance** — real-time, per-operation governance evaluation during activity execution
+  - Every HTTP request, database query, file operation, and traced function call is evaluated at `started` (before, can block) and `completed` (after, informational) stages
+  - Same `POST /api/v1/governance/evaluate` endpoint with new `hook_trigger` field in payload
+  - Automatically enabled when using `create_openbox_worker()`
+- **Database query governance** — per-query started/completed evaluations for psycopg2, pymysql, mysql-connector, asyncpg, pymongo, redis, sqlalchemy
+- **File I/O governance** — per-operation evaluations for open, read, write, readline, readlines, writelines, close (opt-in via `instrument_file_io=True`)
+- **`@traced` decorator** (`openbox.tracing`) — function-level governance with OTel spans; zero overhead when governance not configured
+- **`GovernanceBlockedError`** — new exception type for hook-level blocking with verdict, reason, and resource identifier
+- **Abort propagation** — once one hook blocks, all subsequent hooks for the same activity short-circuit immediately
+- **HALT workflow termination** from hook-level governance via `client.terminate()`
+- **REQUIRE_APPROVAL** from hook-level governance enters the same HITL approval polling flow as activity-level approvals
+- **`duration_ns`** computed for all hook span types (HTTP, file, function — DB already had it)
+
+### Changed
+
+- **`hook_trigger` simplified to boolean** — was a dict with type/stage/data, now just `true`. All data moved to span root fields
+- **Span data consolidation** — all type-specific fields at span root (`hook_type`, `http_method`, `db_system`, `file_path`, `function`, etc.)
+- **`attributes` is OTel-original only** — no custom `openbox.*`, `http.request.*`, `db.result.*` fields injected
+- Hook governance payloads send only the current span per evaluation (not accumulated history)
+- Event-level payloads (ActivityStarted/Completed, Workflow events) no longer include spans
+- Simplified `WorkflowSpanProcessor` — removed span buffering, governed span tracking, body data merging; `on_end()` now only forwards to fallback exporters
+
+### Fixed
+
+- HALT verdict from hooks now correctly terminates the workflow (previously only stopped the activity like BLOCK)
+- REQUIRE_APPROVAL from hooks now enters the approval polling flow (previously raised unhandled error)
+- Stale buffer/verdict from previous workflow run no longer carries over when workflow_id is reused
+- Subsequent hooks no longer fire after the first hook blocks an activity
+
+## [1.0.21] - 2026-03-04
+
+### Added
+
+- Human-in-the-loop approval with expiration handling
+- Approval polling via `POST /api/v1/governance/approval`
+- Guardrails: input/output validation and redaction
+- `GovernanceVerdictResponse.from_dict()` with guardrails_result parsing
+- Output redaction for activity results
+- `_deep_update_dataclass()` for in-place dataclass field updates from redacted dicts
+
+### Fixed
+
+- Temporal Payload objects no longer slip through as non-serializable in governance payloads
+- Stale buffer detection via run_id comparison
+
+## [1.0.0] - 2026-02-15
+
+### Added
+
+- Initial release
+- 6 event types: WorkflowStarted, WorkflowCompleted, WorkflowFailed, SignalReceived, ActivityStarted, ActivityCompleted
+- 5-tier verdict system: ALLOW, CONSTRAIN, REQUIRE_APPROVAL, BLOCK, HALT
+- HTTP instrumentation via OpenTelemetry (httpx, requests, urllib3, urllib)
+- Database instrumentation (psycopg2, pymysql, asyncpg, pymongo, redis, sqlalchemy)
+- File I/O instrumentation (opt-in)
+- Zero-code setup via `create_openbox_worker()` factory
+- Workflow and activity interceptors for governance
+- Span buffering and activity context tracking
+- `fail_open` / `fail_closed` error policies
+- v1.0 backward compatibility for legacy verdict strings

{openbox_temporal_sdk_python-1.1.1 → openbox_temporal_sdk_python-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbox-temporal-sdk-python
-Version: 1.1.1
+Version: 1.2.0
 Summary: OpenBox SDK - Governance and observability for Temporal workflows
 Project-URL: Homepage, https://github.com/OpenBox-AI/temporal-sdk-python
 Project-URL: Documentation, https://github.com/OpenBox-AI/temporal-sdk-python#readme
@@ -24,6 +24,7 @@ Requires-Python: >=3.11
 Requires-Dist: asyncpg>=0.29.0
 Requires-Dist: httpx<1,>=0.28.0
 Requires-Dist: mysql-connector-python>=8.0.0
+Requires-Dist: openbox-sdk-python>=0.2.0
 Requires-Dist: opentelemetry-api<1.40.0,>=1.38.0
 Requires-Dist: opentelemetry-instrumentation-asyncpg<0.61b0,>=0.59b0
 Requires-Dist: opentelemetry-instrumentation-httpx<0.61b0,>=0.59b0
@@ -51,7 +52,8 @@ Description-Content-Type: text/markdown
 OpenBox SDK provides **governance and observability** for Temporal workflows by capturing workflow/activity lifecycle events, HTTP telemetry, database queries, and file operations, then sending them to OpenBox Core for policy evaluation.
 
 **Key Features:**
-- 6 event types (WorkflowStarted, WorkflowCompleted, WorkflowFailed, SignalReceived, ActivityStarted, ActivityCompleted)
+- 7 event types (WorkflowStarted, WorkflowCompleted, WorkflowFailed, SignalReceived, ActivityStarted, ActivityCompleted, Handoff)
+- Multi-agent sessions — propagate a shared `multi_agent_session_id` across workflow + activity events
 - 5-tier verdict system (ALLOW, CONSTRAIN, REQUIRE_APPROVAL, BLOCK, HALT)
 - **Hook-level governance** — per-operation evaluation (HTTP requests, file I/O, database queries, function tracing) with started/completed stages
 - HTTP/Database/File I/O instrumentation via OpenTelemetry
@@ -100,7 +102,15 @@ await worker.run()
 ```
 
 The plugin automatically configures governance interceptors, OTel instrumentation,
-sandbox passthrough, and the `send_governance_event` activity.
+sandbox passthrough, W3C trace propagation through Temporal headers (via
+`temporalio.contrib.opentelemetry.TracingInterceptor`), and the
+`send_governance_event` activity.
+
+**Credentials never leave the plugin.** `openbox_api_key` is captured on the
+governance activity instance itself — it does **not** flow through activity
+inputs, so it is never written to workflow history. To opt out of trace
+propagation (e.g., if you already wire `OpenTelemetryPlugin`), pass
+`enable_trace_propagation=False`.
 
 ### Composing with Other Plugins
 
@@ -148,8 +158,10 @@ The factory automatically:
 1. Validates the API key
 2. Creates span processor
 3. Sets up OpenTelemetry instrumentation
-4. Creates governance interceptors
-5. Adds `send_governance_event` activity
+4. Creates governance interceptors (incl. W3C trace propagation)
+5. Builds the `GovernanceActivities` instance with credentials captured on
+   `self` and registers its `send_governance_event` method — the API key is
+   never passed through activity inputs / workflow history
 6. Returns fully configured Worker
 
 ---
@@ -189,12 +201,15 @@ worker = create_openbox_worker(
 
     # Database instrumentation
     instrument_databases=True,
-    db_libraries={"psycopg2", "sqlalchemy"},  # None = all available
-    sqlalchemy_engine=engine,  # pass pre-existing engine for query capture
 
     # File I/O instrumentation
     instrument_file_io=False,  # disabled by default
 
+    # Header-based W3C trace propagation (client → workflow → activities).
+    # Default True. Set False if you already wire OpenTelemetryPlugin or a
+    # custom propagator.
+    enable_trace_propagation=True,
+
     # Standard Worker options (all supported)
     activity_executor=my_executor,
     max_concurrent_activities=10,
@@ -232,6 +247,48 @@ OpenBox Core returns a verdict indicating what action the SDK should take.
 | SignalReceived | Signal received | workflow_id, signal_name, signal_args |
 | ActivityStarted | Activity begins | activity_id, activity_type, activity_input |
 | ActivityCompleted | Activity ends | activity_id, activity_type, activity_input, activity_output, spans, status, duration |
+| Handoff | Agent hands off to another agent | from_agent_did, multi_agent_session_id |
+
+When a workflow runs as part of a multi-agent session (see below), every event
+above also carries `multi_agent_session_id`. The field is omitted when no
+session id is supplied.
+
+---
+
+## Multi-Agent Sessions
+
+Group the work of several agents under one shared `multi_agent_session_id`. The
+SDK only **propagates** the id you supply — it never invents one, and it owns no
+routing, session minting, or agent registry (those stay in your application).
+
+**Supply the id** via the Temporal workflow memo at start time:
+
+```python
+await client.start_workflow(
+    MyWorkflow.run,
+    arg,
+    id="order-123",
+    task_queue="my-queue",
+    memo={"openbox_multi_agent_session_id": session_id},
+)
+```
+
+The SDK then tags every governance event (workflow, activity, and hook events)
+with that id, propagating it from the workflow to its activities automatically.
+
+**Emit an explicit handoff** from inside workflow code:
+
+```python
+from openbox import emit_handoff
+
+await emit_handoff(
+    multi_agent_session_id=session_id,
+    from_agent_did="did:aip:...",   # the sending agent
+)
+```
+
+The receiving agent is derived server-side from the signed identity and is never
+sent. `emit_handoff` validates its arguments locally before any network call.
 
 ---
 
@@ -264,7 +321,7 @@ OpenBox Core can validate and redact sensitive data before/after activity execut
 
 ## Error Handling
 
-Configure error policy via `on_api_error` (constants available as `hook_governance.FAIL_OPEN` / `FAIL_CLOSED`):
+Configure error policy via the `governance_policy` parameter (`"fail_open"` / `"fail_closed"`):
 
 | Policy | Behavior |
 |--------|----------|
@@ -292,15 +349,12 @@ Configure error policy via `on_api_error` (constants available as `hook_governan
 - `redis` — native OTel `request_hook`/`response_hook`
 - `sqlalchemy` — `before/after_cursor_execute` event listeners
 
-**SQLAlchemy Note:** If your SQLAlchemy engine is created before `create_openbox_worker()` runs (e.g., at module import time), you must pass it via the `sqlalchemy_engine` parameter. Without this, `SQLAlchemyInstrumentor` only patches future `create_engine()` calls and won't capture queries on pre-existing engines.
+**SQLAlchemy Note:** Query-level governance works on pre-existing engines automatically — even engines created before `create_openbox_worker()` runs (e.g., at module import time) — because the base runtime governs SQLAlchemy via a global `Engine` event listener. No engine handle needs to be passed in. The `db_libraries` and `sqlalchemy_engine` parameters are still accepted for backward compatibility but are no longer required and have no effect: the base runtime installs every available database instrumentor best-effort.
 
 ```python
-from db.engine import engine
-
 worker = create_openbox_worker(
     ...,
-    db_libraries={"psycopg2", "sqlalchemy"},
-    sqlalchemy_engine=engine,
+    instrument_databases=True,  # default; installs all available DB instrumentors
 )
 ```
 
@@ -396,7 +450,7 @@ Every database operation is evaluated at `started` (pre-query, can block) and `c
 
 ### Function Tracing
 
-Functions decorated with `@traced` are automatically governed when `hook_governance` is configured:
+Functions decorated with `@traced` are automatically governed when a worker (or plugin) has installed the base runtime. `@traced` wraps the base SDK's `governed()` decorator:
 
 | Stage | Trigger | Data Available |
 |-------|---------|----------------|
@@ -405,15 +459,13 @@ Functions decorated with `@traced` are automatically governed when `hook_governa
 
 **How it works (Function Tracing):**
 
-1. `@traced` decorator wrapper starts OTel span
-2. → SDK sends `started` governance evaluation with function name and module
-3. If verdict is BLOCK/HALT → `GovernanceBlockedError` raised, function never executes
+1. `@traced` delegates to the base SDK's `governed()` decorator
+2. → the base runtime sends a `started` FUNCTION_CALL evaluation with function name and module
+3. If verdict is BLOCK/HALT → the call is blocked and the function never executes
 4. Function executes normally
-5. → SDK sends `completed` governance evaluation with result or error info
-6. If verdict is BLOCK/HALT → `GovernanceBlockedError` raised after execution
-7. When `hook_governance` is not configured → zero overhead, no governance calls
-
-**Governed span tracking:** When hook-level governance is active, the SDK marks HTTP spans as "governed" so the OTel `on_end` processor skips buffering them — preventing duplicate spans.
+5. → the base runtime sends a `completed` FUNCTION_CALL evaluation with result or error info
+6. If verdict is BLOCK/HALT → the block is surfaced after execution
+7. When no base runtime is installed → transparent passthrough, zero governance calls
 
 ---
 
@@ -424,104 +476,87 @@ See [System Architecture](./docs/system-architecture.md) for detailed component
 **High-Level Flow:**
 
 ```
-Workflow/Activity → Interceptors → Span Processor → OpenBox Core API
-                                                    ↓
-                                            Returns Verdict
-                                                    ↓
-                                    (ALLOW, BLOCK, HALT, etc.)
-
-Hook-Level (per HTTP request):
-Activity HTTP Call → OTel Hook → hook_governance → API (started) → Allow/Block
-                   → Response  → hook_governance → API (completed) → Allow/Block
-
-Hook-Level (per file operation):
-Activity open()       → hook_governance → API (started)   → Allow/Block
-Activity read/write() → hook_governance → API (started)   → Allow/Block
-                      → hook_governance → API (completed) → Allow/Block
-Activity close()      → hook_governance → API (completed) → Allow/Block
-
-Hook-Level (per DB query):
-Activity DB Call → db_governance_hooks → hook_governance → API (started) → Allow/Block
-                → Query executes     → hook_governance → API (completed)
-
-Hook-Level (per @traced function):
-@traced call    → hook_governance → API (started) → Allow/Block
-                → Function runs  → hook_governance → API (completed)
+Workflow / Activity lifecycle → Temporal SDK interceptors → OpenBox Core API
+                                                            ↓
+                                                    Returns Verdict
+                                                            ↓
+                                            (ALLOW, BLOCK, HALT, REQUIRE_APPROVAL)
+
+Hook-Level (per HTTP request / DB query / file op / @traced fn):
+Operation → base-SDK instrumentation → OpenBox Core API (started)   → Allow/Block
+          → Operation runs           → OpenBox Core API (completed) → Allow/Block
 ```
 
-**Module responsibilities:**
-- `otel_setup.py` — OTel instrumentation, hooks, TracedFile wrapper
-- `hook_governance.py` — Shared governance evaluator (payload building, API calls, verdict handling)
-- `db_governance_hooks.py` — Per-library DB governance wrappers (wrapt, OTel hooks, SQLAlchemy events)
-- `span_processor.py` — Span buffering, activity context tracking
-- `activity_interceptor.py` — Activity lifecycle governance events
+The Temporal worker/plugin builds and owns an `openbox_core` runtime that installs
+all hook instrumentation. Hook payload building, evaluation, and enforcement are
+owned entirely by the base SDK; the Temporal SDK maps the resulting verdicts onto
+Temporal-native effects.
 
----
+**Responsibility split:**
 
-## Advanced Usage
+Base SDK (`openbox_core`):
+- HTTP / DB / file / function hook instrumentation
+- Hook payload shape, evaluation, and enforcement
 
-For manual control, import individual components:
+Temporal SDK (this package):
+- `workflow_interceptor.py` / `activity_interceptor.py` — workflow/activity/signal lifecycle governance events (via workflow-safe activities)
+- `governance_state.py` — `TemporalGovernanceState`: signal-verdict bridging, HITL pending-approval markers, completed-hook stop/halt propagation
+- `core_adapter.py` — builds the base runtime (`create_core_runtime`) and maps base verdicts to Temporal effects (`TemporalFrameworkAdapter`)
 
-```python
-from openbox import (
-    initialize,
-    WorkflowSpanProcessor,
-    GovernanceInterceptor,
-    GovernanceConfig,
-)
-from openbox.otel_setup import setup_opentelemetry_for_governance
-from openbox.activity_interceptor import ActivityGovernanceInterceptor
-from openbox.activities import send_governance_event
-from openbox.hook_governance import FAIL_OPEN, FAIL_CLOSED  # error policy constants
+---
 
-# 1. Initialize SDK
-initialize(api_url="http://localhost:8086", api_key="obx_test_key_1")
+## Advanced Usage
 
-# 2. Create span processor
-span_processor = WorkflowSpanProcessor(
-    ignored_url_prefixes=["http://localhost:8086"]
-)
+The supported integration is a single call. Both `create_openbox_worker(...)` and
+`OpenBoxPlugin(...)` build and own the base `openbox_core` runtime, install all
+hook instrumentation, register the governance interceptors, and wire the
+`send_governance_event` activity for you — there is no manual OpenTelemetry or
+span-processor setup to perform.
 
-# 3. Setup OTel instrumentation (governance always enabled)
-setup_opentelemetry_for_governance(
-    span_processor,
-    api_url="http://localhost:8086",
-    api_key="obx_test_key_1",
-    sqlalchemy_engine=engine,  # optional: instrument pre-existing engine
-)
+Worker factory:
 
-# 4. Create governance config
-config = GovernanceConfig(
-    on_api_error="fail_closed",
-    api_timeout=30.0,
-)
+```python
+import os
+from openbox import create_openbox_worker
 
-# 5. Create interceptors
-workflow_interceptor = GovernanceInterceptor(
-    api_url="http://localhost:8086",
-    api_key="obx_test_key_1",
-    span_processor=span_processor,
-    config=config,
+worker = create_openbox_worker(
+    client=client,
+    task_queue="my-task-queue",
+    workflows=[MyWorkflow],
+    activities=[my_activity],
+    openbox_url=os.getenv("OPENBOX_URL"),
+    openbox_api_key=os.getenv("OPENBOX_API_KEY"),
+    governance_policy="fail_closed",
+    governance_timeout=30.0,
+    instrument_databases=True,
+    instrument_file_io=True,
 )
 
-activity_interceptor = ActivityGovernanceInterceptor(
-    api_url="http://localhost:8086",
-    api_key="obx_test_key_1",
-    span_processor=span_processor,
-    config=config,
-)
+await worker.run()
+```
+
+Plugin (Temporal >= 1.23.0) — attach to a plain `Worker`:
 
-# 6. Create worker
+```python
 from temporalio.worker import Worker
+from openbox.plugin import OpenBoxPlugin
+
 worker = Worker(
-    client=client,
+    client,
     task_queue="my-task-queue",
     workflows=[MyWorkflow],
-    activities=[my_activity, send_governance_event],
-    interceptors=[workflow_interceptor, activity_interceptor],
+    activities=[my_activity],
+    plugins=[OpenBoxPlugin(
+        openbox_url=os.getenv("OPENBOX_URL"),
+        openbox_api_key=os.getenv("OPENBOX_API_KEY"),
+        governance_policy="fail_closed",
+    )],
 )
 ```
 
+Both entry points accept the same governance, HITL, signing, and instrumentation
+options (see [Configuration](./docs/configuration.md)).
+
 ---
 
 ## Documentation
@@ -536,13 +571,17 @@ worker = Worker(
 
 ## Testing
 
-The SDK includes comprehensive test coverage with 15 test files:
+The SDK includes comprehensive test coverage under `tests/`:
 
 ```bash
 pytest tests/
 ```
 
-Test files: `test_activities.py`, `test_activity_interceptor.py`, `test_config.py`, `test_db_governance_hooks.py`, `test_file_governance_hooks.py`, `test_otel_hook_pause.py`, `test_otel_hook_pause_db.py`, `test_otel_setup.py`, `test_plugin.py`, `test_plugin_integration.py`, `test_span_processor.py`, `test_tracing.py`, `test_types.py`, `test_worker.py`, `test_workflow_interceptor.py`
+Coverage spans the worker factory and plugin, workflow/activity/signal
+interceptors, HITL approval flow, request signing, public-API compatibility, and
+parity with the base SDK's hook governance (`test_temporal_hook_parity.py`,
+`test_core_conformance_suite.py`). Hook instrumentation internals (HTTP/DB/file
+payload shape) are verified in the base SDK's own conformance suite.
 
 ---