@highflame/policy 2.1.3 → 2.1.5

package/README.md

@@ -168,6 +168,47 @@ result.unstructured.forEach(policy => {
 });
 ```
 
+## Condition Groups (Visual Builder Support)
+
+Bidirectional conversion between recursive `ConditionExpression` ASTs and flat `ConditionGroup` arrays for visual condition builder UIs.
+
+```typescript
+import {
+  expressionToGroups,
+  groupsToExpression,
+  expressionToCedar,
+  extractContextFields,
+} from '@highflame/policy/types';
+
+// Parse Cedar → edit in UI → generate Cedar
+const result = parseCedarToRules(cedarText);
+const rule = result.rules[0];
+
+if (rule.conditionExpression) {
+  // Convert AST to flat groups for visual builder
+  const groups = expressionToGroups(rule.conditionExpression);
+
+  // User edits groups in UI...
+
+  // Convert back to AST
+  const expr = groupsToExpression(groups);
+
+  // Render to Cedar text
+  const cedarCondition = expressionToCedar(expr);
+}
+```
+
+### Why Top-Level AND Between Groups?
+
+Groups are always combined with **AND** at the top level. This reflects Cedar's authorization model:
+
+- **Cedar provides OR between policies for free** — if ANY `forbid` matches, the request is denied
+- **AND within a rule**: "block if injection > 70 AND jailbreak > 65" → conditions in one AND group
+- **OR within a rule**: "block if violence > 70 OR hate > 70" → conditions in one OR group
+- **OR between rules**: separate `forbid` rules — Cedar ORs them automatically
+
+This means `(A && B) || (C && D)` is expressed as two separate rules, which is cleaner, more auditable, and idiomatic Cedar.
+
 ## Available Constants
 
 - **17 Entity Types**: `EntityType.User`, `Scanner`, `Artifact`, `Tool`, etc.