<!-- SPDX-License-Identifier: Apache-2.0 -->
**Status:** stable · **Owner:** Developer Relations · **License:** Apache-2.0

# Playbook 3 — Policy Resolver Integration

> You already have a policy engine — **Cedar**, **OPA / Rego**, **Cerbos**, or
> AWS Verified Permissions. Keep it. This playbook shows how to map its verdict
> onto the **locked KYE DecisionOutcome set** and seal the raw verdict in the
> evidence so the mapping is replay-provable.

## 1. The problem

Most teams adopting KYE have a policy engine already. KYE does **not** replace it
— KYE sits *above* it. The policy engine answers "does this rule pass?"; KYE
answers "is this action authorised, for what purpose, and can I prove it?". The
integration is a thin adapter that:

1. marshals the KYE decision request into the engine's native request shape,
2. evaluates the engine, and
3. **maps the engine's native effect back onto the locked KYE DecisionOutcome
   set**, carrying the raw verdict into the Evidence Pack.

The locked outcome set is the whole point: every engine, however it phrases its
result, collapses to the same four KYE outcomes — so an auditor reads one
vocabulary, not N.

## 2. The pattern

```
KYE decision request
        │
        ▼
  adapter.marshal()  ──▶  engine-native request
        │                 (Cedar auth request / Rego input doc / Cerbos CheckResources)
        ▼
  engine.evaluate()  ──▶  engine-native effect
        │                 (Cedar Allow/Deny · Rego result.allow · Cerbos EFFECT_ALLOW/DENY)
        ▼
  adapter.map()      ──▶  KYE DecisionOutcome  (the locked set)
        │                 + obligations carried onto the Decision Map
        ▼
  seal raw verdict in the Evidence Pack  (mapping is replay-provable)
```

### The locked DecisionOutcome set

KYE outcomes are drawn from the published `Decision` vocabulary
(`https://kyeprotocol.com/schemas/common.json#/$defs/Decision`). Engine effects
map as follows:

| Engine | Native effect | → KYE DecisionOutcome |
|---|---|---|
| Cedar | `Allow` | `allow` |
| Cedar | `Deny` | `deny` |
| OPA / Rego | `result.allow == true` | `allow` |
| OPA / Rego | `result.allow == false` | `deny` |
| Cerbos | `EFFECT_ALLOW` | `allow` |
| Cerbos | `EFFECT_DENY` | `deny` |
| any | conditional / obligated pass | `allow_with_constraints` |
| any | escalation required | `require_approval` |

`allow_with_constraints` and `require_approval` are how KYE captures
*obligations* and *step-up* that a bare boolean engine result cannot express on
its own — the adapter promotes the engine's obligation list into the
constrained/approval outcome rather than flattening it to `allow`.

> **Fail-closed.** If the engine times out or errors, the adapter maps to
> `deny` (native deny-by-default), never to `allow`. This is non-negotiable.

## 3. The public artefacts

The adapter contract is published as `kye.policy_engine_adapter.v1` with one
example per engine:

- [`public/examples/policy-engine-adapters/cedar.example.json`](../../examples/policy-engine-adapters/cedar.example.json)
- [`public/examples/policy-engine-adapters/opa.example.json`](../../examples/policy-engine-adapters/opa.example.json)
- [`public/examples/policy-engine-adapters/cerbos.example.json`](../../examples/policy-engine-adapters/cerbos.example.json)

A working reference adapter ships as
[`@kye/connector-cerbos`](../connector-cerbos/) (Apache-2.0), and the
interactive [policy-resolver demo](https://kyeprotocol.com/policy-resolver.html)
lets you paste an engine verdict and watch it map.

Each adapter example declares the same invariants you should preserve:

- `response_mapping.decision_vocab_ref` points at the **public** `Decision`
  vocabulary — never invent local outcome strings.
- `evidence_emission.records_raw_engine_verdict: true` — the raw Cedar/Rego/
  Cerbos result is sealed alongside the mapped outcome.
- `kill_switch.on_kill: "fallback-native-deny-by-default"`.
- `kye_retains_above` — purpose-permission, authority-resolution, authority-
  finality, evidence-pack, replay-proof stay KYE-side regardless of engine.

## 4. What stays KYE-side

This playbook discloses the **mapping table and the public adapter contract**.
How KYE *seals* the raw engine verdict into a replay-provable Evidence Pack, and
how obligations are ordered onto the Decision Map, are patent-track and not
disclosed here. You write the marshal/map adapter against the public contract;
KYE seals and proves.

## Next

- Playbook 4 — [agentcore-and-kye](./agentcore-and-kye.md): the same
  wrap-a-verdict pattern, applied to a cloud agent-gateway.
- Scaffold it: [`policy-resolver` template](../agent-dev-kit-templates/policy-resolver/).