# Overview

The Govplane Runtime SDK is a **local policy engine** that evaluates governance decisions inside your process. It fetches precompiled policy bundles from the Govplane Control Plane and evaluates every decision in-memory, with no per-request network call.

***

### How it works

```
┌──────────────────────────────────────────────────────────────┐
│                       Your Application                       │
│                                                              │
│  client.evaluate(target, context)                            │
│          │                                                   │
│          ▼                                                   │
│  ┌───────────────┐   bundle cache   ┌──────────────────────┐ │
│  │ Policy Engine │◄─────────────────│   Runtime Client     │ │
│  │ (in-process)  │                  │   (background poll)  │ │
│  └───────┬───────┘                  └──────────┬───────────┘ │
│          │ Decision                            │ HTTPS       │
│          ▼                                     ▼             │
│   allow / deny /                  Govplane Control Plane     │
│   throttle / kill_switch /        (bundle endpoint only)     │
│   custom                                                     │
└──────────────────────────────────────────────────────────────┘
```

| Property           | Details                                                       |
| ------------------ | ------------------------------------------------------------- |
| Decision latency   | < 1 ms — evaluation is fully in-process                       |
| Network dependency | Bundle fetch only — each evaluation is offline-safe           |
| PII in traces      | None — request context is never included in trace events      |
| Fail-safe          | Deny-by-default when no bundle is loaded or no rule matches   |
| Bundle delivery    | Server-compiled JSON bundle; no policy logic runs server-side |

***

### Available SDKs

Select the SDK for your platform to get started:

| Platform    | Package                       | Minimum runtime | Status    |
| ----------- | ----------------------------- | --------------- | --------- |
| **Node.js** | `@govplane/runtime-sdk`       | Node.js 18 +    | Available |
| **Java**    | `com.govplane:gp-runtime-sdk` | Java 21 +       | Available |
| **Python**  | `GitHub Repo`                 | Python 3.9 +    | Available |
| **PHP**     | `GitHub Repo`                 | PHP 8.2 +       | Available |

***

### Core capabilities

All SDK implementations share the same feature set:

**Client lifecycle**

* `start()` — initialise a background poller that keeps the local bundle up to date
* `warmStart()` — block startup until the first bundle has been received
* `stop()` — shut down the poller gracefully

**Policy evaluation**

* `evaluate(target, context)` — returns an immediate in-process `Decision`
* `evaluateWithTrace(target, context)` — returns the decision together with a full rule-level trace
* Fixed effect precedence: `kill_switch → deny → throttle → allow → custom → deny-by-default`
* Deterministic rule ordering by `priority`, then `policyKey`, then `ruleId`

**Decision effects**

* `Allow` — request is permitted; carries matched `policyKey` and `ruleId`
* `Deny` — request is blocked; carries a `reason` string
* `KillSwitch` — hard stop independent of any other rule
* `Throttle` — most-restrictive matching throttle rule is selected
* `Custom` — arbitrary structured payload defined by the policy author

**Bundle polling**

* HEAD-first polling using `ETag` / `If-None-Match` to minimise bandwidth
* Configurable poll interval and burst mode for incident response
* Exponential back-off with jitter on errors; automatic degraded-state reporting

**Context safety**

* Explicit `allowedKeys` allowlist — unknown keys are rejected immediately
* Heuristic PII key blocking
* Configurable limits on string and array length

**Decision tracing**

* Four trace levels: `off`, `errors`, `sampled`, `full`
* Sampling rate and per-window budget controls
* `force` flag to bypass sampling for debugging
* Synchronous and asynchronous trace sinks with configurable drop strategies
* `flushTraces()` for graceful drain on shutdown

***

### Quickstarts

***

### Authentication

All SDKs authenticate with a **Runtime Key** (`gprk_…`  Store the key as an environment variable and never commit it to source control.

| Environment variable | Purpose                                  |
| -------------------- | ---------------------------------------- |
| `GP_BASE_URL`        | Base URL of the Govplane Control Plane   |
| `GP_RUNTIME_KEY`     | Runtime Key used to fetch policy bundles |

{% hint style="warning" %}
Runtime Keys grant access to your compiled policy bundles. Treat them with the same care as database credentials.
{% endhint %}