# 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 %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://govplane.gitbook.io/docs/documentation/sdk/overview.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.