# Rule PDP Adapter Boundary

Status: implemented for FLEX-WP-0004 P4.3.

## Role

The rule PDP adapter is the common boundary for OPA/Rego, Cedar-style
policy services, and other engines that evaluate a policy language over
a structured request. It is separate from the relationship-PDP boundary:
relationship backends answer tuple reachability questions, while rule
backends evaluate policy logic over subject, action, resource, context,
and CARING metadata.

## Canonical Input

All rule backends receive the same canonical input shape:

```text
input.subject
input.action
input.resource
input.context
input.caring_context
input.policy.package
input.policy.version
```

OPA/Rego can consume this shape directly. Cedar adapters translate the
same fields into principal/action/resource/context entities at the
backend boundary. Protected systems do not see backend-native input
syntax.

## Policy Artifacts

`PolicyArtifactFromPackage` converts a validated Rego-in-Markdown
package into a delegated artifact:

- `language=rego`
- package id and version from frontmatter
- extracted Rego module unchanged
- test blocks and fixtures preserved
- CARING policy metadata preserved

Cedar and other rule engines use the same `PolicyArtifact` envelope,
but may reject unsupported artifacts with `rule_policy_unsupported`.

## Fixtures

`EvaluateFixtures` runs `api.PolicyFixture` values through the delegated
adapter and compares the returned effect, reason, and obligations. This
keeps delegated backends honest against the same fixtures used by the
standalone evaluator.

## Obligations And Diagnostics

Rule backends can return obligations such as masking, audit, or approval
requirements. The adapter copies them into the canonical
`DecisionEnvelope`. Backend diagnostics are preserved and supplemented
with:

- `adapter=rule`
- backend name
- delegated mode
- language
- policy package and version
- fail-closed reason when present

## Versioning

The envelope records backend policy version in
`matched_policy_version` and `provenance.policy_version`. A backend may
return a newer concrete revision than the request asked for; the adapter
records what actually matched.

## Failure Behavior

The adapter fails closed for:

- backend unavailable: `rule_backend_unavailable`
- stale policy: `rule_policy_stale`
- partial result: `rule_partial_result`
- invalid input: `rule_request_incomplete`
- unsupported policy artifact: `rule_policy_unsupported`

Each failure returns a deny envelope with `diagnostics.rule_failure` and
a CARING conformance finding.

## CARING Preservation

Rule engines vary in how much of CARING they can represent natively.
flex-auth keeps CARING outside the backend-specific language contract:

- request descriptor wins;
- backend result descriptor is next;
- policy frontmatter supplies profile and expected dimensions;
- gaps become `RULE-CARING-METADATA-GAP` or
  `RULE-CARING-DESCRIPTOR-MISSING` findings.

The decision envelope preserves descriptor, scope, planes,
capabilities, exposure modes, restrictions, derived capabilities,
conformance findings, exposure-event hooks, obligations, and diagnostics.
Backend-native policy names should never replace canonical CARING roles
in protected-system responses.