(pkg-v2-runtime)=
# OpenRath v2.0.0 API Reference

The Stable `2.0.0` release adds public packages for workflow definition,
durable execution, governed adapters, artifacts, deployment revisions,
evaluation, observability, security, and the Agent Server. Stability
classifications and compatibility commitments are governed by the
[v2 API policy](api-policy.md).

## Package map

| Package | Primary contracts |
| --- | --- |
| `rath.definition` | `step`, `router`, `WorkflowCompiler`, `ExecutionPlan`, `EffectClass`, `RetryPolicy` |
| `rath.context` | `RunContext`, `TraceContext`, deadline propagation |
| `rath.errors` | Stable `ErrorCode` values and serializable `RathError` |
| `rath.events` | Immutable `Event`, `EventKind`, `ProducerRef`, and `SessionEventLog` |
| `rath.adapters` | Governed Provider, Tool, Sandbox, and Memory executors and resource specifications |
| `rath.artifacts` | Tenant-scoped `LocalArtifactStore` and `S3ArtifactStore` |
| `rath.deployment` | Content-identified `Revision`, `DeploymentManifest`, and revision stores |
| `rath.eval` | Versioned datasets, evaluators, experiments, persistence, and regression gates |
| `rath.observability` | Telemetry spans/counters, OpenTelemetry bridge, structured logs, and redaction |
| `rath.runtime` | `LocalRuntime`, Run/Event/Checkpoint/Interrupt models, SQLite/PostgreSQL stores, effect ledgers, Redis signals |
| `rath.security` | Principal and tenant context, policies, authorization, secret references, structured audit |
| `rath.server` | `AgentServer`, authentication, Assistant/Session resource stores, HTTP/SSE application |
| `rath.client` | Synchronous `RemoteClient` and native-async `AsyncRemoteClient` |

The retained v1-compatible packages remain documented in the general
[API Reference](../reference/index.md).

## Definition and plan compilation

| Surface | Contract |
| --- | --- |
| `@step(entry=..., successors=..., effects=..., retry=..., timeout_seconds=...)` | Marks a checkpointable execution method. |
| `@router(successors=..., entry=...)` | Marks a pure router with an explicit successor allowlist. |
| `Workflow.compile_plan(revision_id=...)` | Compiles explicit v2 nodes into an `ExecutionPlan`. |
| `WorkflowCompiler.compile(...)` | Validates entrypoint, successors, schemas, effect declarations, and durable compatibility. |
| `EffectClass` | Classifies no-effect, read-only, idempotent, or non-idempotent work for retry and reconciliation. |
| `ResourceManifestV2` | Declares the Provider, Tool, Sandbox, and Memory resources required by a plan. |

Non-idempotent retries require an explicit idempotency key. For
timeout-controlled execution, use an async handler or isolated executor.

## Request context

| Surface | Contract |
| --- | --- |
| `SecurityContext` | Principal, tenant, optional project, action grants, and trusted attributes. |
| `RunContext` | Security, revision, request, trace, and optional deadline identity propagated through a Run. |
| `TraceContext.new(...)` | Creates W3C-compatible trace and span identifiers. |
| `RunContext.remaining_seconds(...)` | Returns the bounded time remaining for a deadline. |
| `RunContext.ensure_active(...)` | Raises `DeadlineExceededError` after the deadline. |

## Durable runtime

| Method | Behavior |
| --- | --- |
| `LocalRuntime.register(workflow, revision_id=...)` | Compiles and registers the executable plan for a revision. |
| `LocalRuntime.submit(...)` | Creates a durable queued Run with session, context, state, priority, and optional idempotency key. |
| `LocalRuntime.work_once(worker_id=..., lease_seconds=..., max_steps=...)` | Claims one Run under a lease/fencing token and advances it from the latest committed checkpoint. |
| `SQLiteRunStore(path)` | Persists local Run state, events, checkpoints, interrupts, and leases. |
| `PostgresRunStore(dsn, ..., auto_migrate=False)` | Provides the production durable store; migrations are a separate operator action. |
| `SQLiteEffectLedger` / `PostgresEffectLedger` | Records dispatch and outcome state for external side effects. |
| `InMemorySignalBus` / `RedisSignalBus` | Carries wake, cancel, and fanout signals without replacing durable Run state. |
| `reconcile_stale_effects(...)` | Classifies stale Tool invocations for retry, failure, or operator review. |

The durable state model includes `Run`, `RunEvent`, `Checkpoint`, `Interrupt`,
`ResourceLease`, `ToolInvocation`, and their explicit status enums.

## Governed adapters

| Surface | Contract |
| --- | --- |
| `AdapterRequestContext` | Reduced Run, security, trace, deadline, and policy context supplied to an adapter call. |
| `ProviderExecutor` | Applies policy and schema constraints around Provider calls. |
| `ToolExecutor` | Applies approval, output-size, policy, and schema checks around Tool calls. |
| `SandboxExecutor` | Applies isolation and policy constraints around Sandbox calls. |
| `MemoryExecutor` | Applies namespace and policy constraints around Memory operations. |
| `ProviderSpec` / `ToolSpec` / `SandboxSpec` / `MemoryNamespace` | Explicit resource declarations for governed calls. |
| `ApprovalGrant` / `ApprovalValidator` | Carries and validates an approval before controlled work. |

Adapter handlers receive only the context and resource specification needed for
their operation. See the [threat model](threat-model.md) for the corresponding
trust boundaries.

## Supporting runtime planes

| Package | Contract |
| --- | --- |
| `rath.artifacts` | Content-addressed, tenant-scoped payload storage with bounded reads and SHA-256 verification. |
| `rath.deployment` | Immutable revision identity derived from code and a canonical deployment manifest. |
| `rath.eval` | Offline dataset execution, per-evaluator results, revision-bound experiments, and regression decisions. |
| `rath.observability` | Trace-correlated spans, counters, redacted structured logs, and an OpenTelemetry SDK bridge. |

See [Evaluation, Observability, and Artifacts](evaluation-observability-artifacts.md)
for executable examples.

## Security

| Surface | Contract |
| --- | --- |
| `PolicyEngine` / `authorize(...)` | Makes explicit allow, deny, or approval decisions over actions and resources. |
| `SecretRef` / `SecretResolver` | References credentials without persisting raw secrets in Run state. |
| `AuditSink` | Receives redacted, correlated security and control-plane events. |
| `StructuredAuditSink` | Emits redacted newline-delimited JSON audit records. |
| `LocalTrustedPolicy` | Allows explicitly trusted embedded workflows. |
| `DenyAllPolicy` | Provides a fail-closed policy default. |

Authentication alone grants no action. Service tokens need explicit grants,
and object access is filtered by tenant and project scope.

## Agent Server and clients

| Surface | Contract |
| --- | --- |
| `AgentServer(...)` | Creates the tenant-scoped HTTP/SSE service over a `RunStore` and `LocalRuntime`. |
| `AgentServer.register_assistant(...)` | Registers a workflow template under an immutable revision ID. |
| `StaticTokenAuth` | Reference bearer-token authentication for self-hosted deployments and tests. |
| `AuthProvider` | Async authentication protocol for integrated identity systems. |
| `RemoteClient` | Synchronous Session, Assistant, Run, Interrupt, Feedback, Event, and Memory operations. |
| `AsyncRemoteClient` | Native-async form of the same client surface. |

`RemoteClient` and `AsyncRemoteClient` expose:

| Operation group | Methods |
| --- | --- |
| Assistants | `create_assistant(...)`, `list_assistants()` |
| Sessions | `create_session()` |
| Runs | `create_run(...)`, `get_run(...)`, `list_runs(...)`, `cancel_run(...)`, `resume_run(...)` |
| Events | `events(...)` |
| Interrupts | `list_interrupts(...)`, `decide_interrupt(...)` |
| Feedback | `create_feedback(...)` |
| Governed Memory | `store("put" | "search" | "delete", ...)` |
| Lifecycle | `close()` or `aclose()` |

See [Agent Server and Remote Client](agent-server.md) for a complete executable
path and the
[OpenAPI document](https://github.com/Rath-Team/OpenRath/blob/v2.0.0/deploy/docs/openapi-v2.json)
for HTTP request and response schemas.

## Events

OpenRath exposes two related event contracts:

| Surface | Purpose |
| --- | --- |
| `rath.runtime.RunEvent` | Durable, monotonically sequenced events attached to one Run and replayed by the Agent Server. |
| `rath.events.Event` | Deeply immutable Session/lineage event with producer, trust, provenance, and trace identity. |
| `rath.events.SessionEventLog` | Immutable ordered Session event view with parent Session identities. |

## Machine-readable errors

`RathError` carries a stable code, message, retryable flag, and JSON-safe
details. `RathError.to_dict()` returns the transport representation.

| `ErrorCode` value | Meaning |
| --- | --- |
| `request.invalid_argument` | A request or argument failed validation. |
| `security.unauthenticated` | Authentication did not produce a principal. |
| `security.forbidden` | The principal lacks the required action or scope. |
| `security.approval_required` | The policy requires an explicit approval. |
| `security.policy_error` | Policy evaluation failed. |
| `resource.conflict` | The requested state change conflicts with durable state. |
| `resource.not_found` | The scoped resource is not visible or does not exist. |
| `runtime.deadline_exceeded` | The Run or operation exceeded its deadline. |
| `runtime.cancelled` | The operation was cancelled. |
| `runtime.unavailable` | A required runtime dependency is unavailable. |
| `internal.error` | An unexpected internal error occurred. |

The Agent Server can additionally return `resource.exhausted` with HTTP `429`
when a configured tenant queue or request bound is reached. The OpenAPI
document is the contract source for endpoint response codes.

## Command-line entry points

| Command | Arguments and environment |
| --- | --- |
| `openrath-server` | `--app`, `--host`, `--port`, `--workers`; corresponding `OPENRATH_APP`, `OPENRATH_HOST`, `OPENRATH_PORT`, and `OPENRATH_WEB_WORKERS`. |
| `openrath-worker` | `--app`, `--worker-id`, `--lease-seconds`; corresponding `OPENRATH_APP`, `OPENRATH_WORKER_ID`, and `OPENRATH_WORKER_LEASE_SECONDS`. |
| `openrath-migrate` | `--dsn`, `--schema`, `--check`; corresponding `OPENRATH_POSTGRES_DSN` and `OPENRATH_DB_SCHEMA`. |

`openrath-server` uses one process worker; service deployments scale through
container or pod replicas. `openrath-worker` resolves its application
reference to an `AgentServer`. `openrath-migrate --check` verifies the schema
without applying changes.

## Source

| Module | Source |
| --- | --- |
| `rath.definition` | `src/rath/definition/` |
| `rath.context` | `src/rath/context.py` |
| `rath.errors` | `src/rath/errors.py` |
| `rath.events` | `src/rath/events.py` |
| `rath.adapters` | `src/rath/adapters/` |
| `rath.artifacts` | `src/rath/artifacts/` |
| `rath.deployment` | `src/rath/deployment/` |
| `rath.eval` | `src/rath/eval/` |
| `rath.observability` | `src/rath/observability/` |
| `rath.runtime` | `src/rath/runtime/` |
| `rath.security` | `src/rath/security/` |
| `rath.server` | `src/rath/server/` |
| `rath.client` | `src/rath/client/` |

## Autodoc

```{eval-rst}
.. automodule:: rath.definition
   :members:
   :imported-members:
   :undoc-members:

.. automodule:: rath.context
   :members:
   :imported-members:
   :undoc-members:

.. automodule:: rath.errors
   :members:
   :imported-members:
   :undoc-members:

.. automodule:: rath.events
   :members:
   :imported-members:
   :undoc-members:

.. automodule:: rath.adapters
   :members:
   :imported-members:
   :undoc-members:

.. automodule:: rath.artifacts
   :members:
   :imported-members:
   :undoc-members:

.. automodule:: rath.deployment
   :members:
   :imported-members:
   :undoc-members:

.. automodule:: rath.eval
   :members:
   :imported-members:
   :undoc-members:

.. automodule:: rath.observability
   :members:
   :imported-members:
   :undoc-members:

.. automodule:: rath.runtime
   :members:
   :imported-members:
   :undoc-members:

.. automodule:: rath.security
   :members:
   :imported-members:
   :undoc-members:

.. automodule:: rath.server
   :members:
   :imported-members:
   :undoc-members:

.. automodule:: rath.client
   :members:
   :imported-members:
   :undoc-members:
```

[← OpenRath v2.0.0 overview](index.md)