Add rule PDP adapter boundary

docs/rule-pdp-adapter-boundary.md

@@ -0,0 +1,103 @@
+# 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.