From 2da2ce88f50d59c93fbaaa1d6e4e28c8a6bf2db3 Mon Sep 17 00:00:00 2001
From: kjdev <kjclev@gmail.com>
Date: Wed, 10 Jun 2026 08:30:18 +0900
Subject: [PATCH 1/2] docs: clarify required vs optional keys in request shape

---
 README.md | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index c73900c..d278e19 100644
--- a/README.md
+++ b/README.md
@@ -222,12 +222,12 @@ Both methods accept the same keys as the corresponding AVP API:
 
 ```php
 [
-    'policyStoreId' => string,                 // must equal $store->id()
-    'principal' => ['entityType' => ..., 'entityId' => ...],   // isAuthorized only
-    'action'    => ['actionType' => ..., 'actionId' => ...],
-    'resource'  => ['entityType' => ..., 'entityId' => ...],
-    'context'   => ['contextMap' => [name => AttributeValue, ...]],
-    'entities'  => ['entityList' => [
+    'policyStoreId' => string,                 // required, must equal $store->id()
+    'principal' => ['entityType' => ..., 'entityId' => ...],   // required (isAuthorized only)
+    'action'    => ['actionType' => ..., 'actionId' => ...],   // required
+    'resource'  => ['entityType' => ..., 'entityId' => ...],   // required
+    'context'   => ['contextMap' => [name => AttributeValue, ...]],   // optional
+    'entities'  => ['entityList' => [                                 // optional
         [
             'identifier' => ['entityType' => ..., 'entityId' => ...],
             'attributes' => [name => AttributeValue, ...],
@@ -241,6 +241,11 @@ Both methods accept the same keys as the corresponding AVP API:
 ]
 ```
 
+`policyStoreId`, `principal` (for `isAuthorized()`), `action`, and
+`resource` are required; `context` and `entities` are optional and may be
+omitted entirely when the policies do not reference them. A request with
+only the required keys is valid and evaluates normally.
+
 `AttributeValue` is the same single-key union AVP uses:
 
 ```php

From 4b9a241d84b3e9572b42d141c9681debcadb434e Mon Sep 17 00:00:00 2001
From: kjdev <kjclev@gmail.com>
Date: Wed, 10 Jun 2026 08:30:18 +0900
Subject: [PATCH 2/2] docs: document evaluation conformance inherited from
 nxe-cedar

---
 README.md | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/README.md b/README.md
index d278e19..0c0fc0d 100644
--- a/README.md
+++ b/README.md
@@ -296,6 +296,21 @@ class, not as one of the Cedar exceptions.
 | Response keys | `decision / determiningPolicies / errors` match exactly. `Aws\Result`'s `ArrayAccess` methods (`->get(...)`) are **not** available — the response is a plain array. |
 | `isAuthorizedWithToken()` | API-shape compatible (`policyStoreId / identityToken / accessToken / action / resource / context / entities`, response includes the derived `principal`), but **the token is expected to be a verified claims array, not a raw JWT string**. See [Token verification](#token-verification-is-callers-responsibility). |
 
+Beyond matching the request / response *shape*, what makes this extension
+substitutable for AVP is that **the same request yields the same
+`decision`**. The evaluation engine is kept logically identical to its
+upstream nxe-cedar snapshot (see
+[`src/cedar/UPSTREAM.md`](src/cedar/UPSTREAM.md)), so it inherits
+nxe-cedar's behavioral conformance: the C implementation is
+differential-tested against the upstream `cedar-policy` reference crate,
+with **100% C-vs-reference parity** reported over the official Cedar
+integration-test corpus (see
+[nxe-cedar's conformance notes](https://github.com/kjdev/nxe-cedar/blob/main/tests/conformance/README.md)).
+This parity guarantee covers only the **supported subset**: the
+[unsupported features](#unsupported-features) (entity tags, policy
+templates, schema validation, dynamic identity sources) lie outside the
+conformance corpus and are not part of the claim.
+
 For a worked example of swapping AVP and this extension behind a single
 interface, see
 [Drop-in replacement for AWS Verified Permissions](#drop-in-replacement-for-aws-verified-permissions).