Add WithEffectPrecedence for deny-overrides evaluation

Introduces an optional effect precedence strategy that resolves
conflicts by highest-priority effect instead of first-match-wins.
This prevents misconfigured rule ordering from letting an ALLOW
slip past a DENY or REVIEW in custody contexts.

Author: anhthii

README.md

@@ -37,6 +37,7 @@ Key use cases include:
 ## Features
 - **Deterministic evaluations** powered by compiled expr programs
 - **Default effects** at document and policy level with a DENY-overrides-ALLOW model
+- **Effect precedence** (optional) for deny-overrides evaluation — highest-priority effect wins regardless of rule order
 - **Strict schema validation** (optional) via `WithSchemaDefinition`
 - **Friendly error reporting** that surfaces the failing rule and expression issue
 - **Zero-config loader** for JSON policy documents
@@ -215,6 +216,46 @@ func main() {
 
 Because the caller defines what each effect means, you can extend the decision space (e.g., `RATE_LIMIT`, `QUARANTINE`, `NOTIFY_COMPLIANCE`) without changing the engine.
 
+### Effect precedence (deny-overrides)
+
+By default the engine uses first-match-wins for non-deny effects. This works well when rule ordering is deliberate, but in custody and treasury contexts a priority mistake can accidentally let an `ALLOW` slip in before a `DENY` or `REVIEW`.
+
+`WithEffectPrecedence` switches to a **highest-priority-wins** strategy. You declare the hierarchy once at compile time and the engine enforces it regardless of rule or policy ordering:
+
+```go
+const EffectReview policy.Effect = "REVIEW"
+
+engine, err := policy.CompileDocument(doc,
+    policy.WithEffectPrecedence(policy.EffectDeny, EffectReview, policy.EffectAllow),
+)
+```
+
+With this configuration:
+
+| Matched effects | Result | Why |
+| --- | --- | --- |
+| `DENY` + `ALLOW` | `DENY` | DENY has higher precedence |
+| `REVIEW` + `ALLOW` | `REVIEW` | REVIEW has higher precedence than ALLOW |
+| `ALLOW` only | `ALLOW` | Single match, returned as-is |
+| Nothing matched | `DENY` | Document default kicks in |
+
+The engine still short-circuits when the highest-priority effect (first in the list) is matched — there is no point evaluating further once a `DENY` is found. All other matches are collected and the winner is selected at the end, so `Evaluated` on the decision always reflects the full rule count.
+
+Effects not listed in the precedence order are treated as lowest priority. They can still win when they are the only match, but any effect that *is* in the list will beat them.
+
+```go
+decision := engine.Evaluate(context.Background(), input)
+
+switch decision.Effect {
+case policy.EffectDeny:
+    fmt.Println("blocked:", decision.Message)
+case EffectReview:
+    fmt.Println("flagged for manual review")
+case policy.EffectAllow:
+    fmt.Println("approved")
+}
+```
+
 ### Mapping snake_case JSON to expr fields
 
 Use the `expr` struct tag to expose snake_case JSON fields with the same name inside expressions:

policy/engine.go

@@ -12,18 +12,20 @@ import (
 
 // Engine evaluates compiled policies against an input context.
 type Engine struct {
-	defaultEffect Effect
-	policies      []*compiledPolicy
+	defaultEffect    Effect
+	policies         []*compiledPolicy
+	effectPrecedence map[Effect]int // lower index = higher priority
 }
 
 // EngineOption configures compilation behaviour.
 type EngineOption func(*engineConfig)
 
 type engineConfig struct {
-	exprOptions   []expr.Option
-	defaultEffect Effect
-	env           any
-	strictTypes   bool
+	exprOptions      []expr.Option
+	defaultEffect    Effect
+	env              any
+	strictTypes      bool
+	effectPrecedence []Effect
 }
 
 // WithExprOptions passes expr compilation options for every rule.
@@ -51,6 +53,19 @@ func WithDefaultEffect(effect Effect) EngineOption {
 	}
 }
 
+// WithEffectPrecedence defines the priority order of effects for conflict resolution.
+// Effects listed first have higher priority. When multiple rules match, the effect
+// with the highest priority wins regardless of rule or policy ordering.
+// Any matched effect not in the list is treated as lowest priority (first-match-wins among them).
+//
+// Example for custody: WithEffectPrecedence(EffectDeny, EffectReview, EffectAllow)
+// This means DENY beats REVIEW beats ALLOW, regardless of rule order.
+func WithEffectPrecedence(effects ...Effect) EngineOption {
+	return func(cfg *engineConfig) {
+		cfg.effectPrecedence = effects
+	}
+}
+
 // CompileDocument converts a policy document into an executable engine.
 func CompileDocument(doc Document, opts ...EngineOption) (*Engine, error) {
 	cfg := engineConfig{
@@ -65,6 +80,13 @@ func CompileDocument(doc Document, opts ...EngineOption) (*Engine, error) {
 		defaultEffect: cfg.defaultEffect,
 	}
 
+	if len(cfg.effectPrecedence) > 0 {
+		engine.effectPrecedence = make(map[Effect]int, len(cfg.effectPrecedence))
+		for i, e := range cfg.effectPrecedence {
+			engine.effectPrecedence[e] = i
+		}
+	}
+
 	if doc.DefaultEffect != nil {
 		engine.defaultEffect = *doc.DefaultEffect
 	}
@@ -96,6 +118,10 @@ func CompilePolicies(policies []Policy, opts ...EngineOption) (*Engine, error) {
 
 // Evaluate runs all compiled policies against the provided context value.
 // The final decision honours DENY over ALLOW, with a configurable default fallback.
+//
+// When WithEffectPrecedence is configured, all matching rules are evaluated and
+// the decision with the highest-priority effect wins. Otherwise, DENY short-circuits
+// and the first non-deny match wins.
 func (e *Engine) Evaluate(_ context.Context, input any) Decision {
 	decision := Decision{
 		Effect:  e.defaultEffect,
@@ -107,6 +133,15 @@ func (e *Engine) Evaluate(_ context.Context, input any) Decision {
 		return decision
 	}
 
+	if e.effectPrecedence != nil {
+		return e.evaluateWithPrecedence(input, decision)
+	}
+	return e.evaluateFirstMatch(input, decision)
+}
+
+// evaluateFirstMatch is the default evaluation strategy: DENY short-circuits,
+// first non-deny match wins.
+func (e *Engine) evaluateFirstMatch(input any, decision Decision) Decision {
 	var matchedDecision Decision
 	var hasMatchedDecision bool
 	evaluated := 0
@@ -184,6 +219,122 @@ func (e *Engine) Evaluate(_ context.Context, input any) Decision {
 	return decision
 }
 
+// matchSource records where a winning match came from so we can build
+// the Decision once after all rules have been evaluated.
+type matchSource struct {
+	effect     Effect
+	policyName string
+	ruleID     string
+	message    string
+	isDefault  bool // true when the match came from a policy default
+}
+
+// evaluateWithPrecedence evaluates all rules and returns the decision with the
+// highest-priority effect according to the configured precedence order.
+// The Decision is built once at the end so that Evaluated and Error reflect
+// the full evaluation run.
+func (e *Engine) evaluateWithPrecedence(input any, decision Decision) Decision {
+	var best *matchSource
+	bestPriority := -1 // -1 = no known priority
+	evaluated := 0
+
+	policyErrors := make([][]error, len(e.policies))
+
+	for idx, pol := range e.policies {
+		policyMatched := false
+
+		for _, rule := range pol.rules {
+			evaluated++
+
+			ok, err := rule.evaluate(input)
+			if err != nil {
+				policyErrors[idx] = append(policyErrors[idx], err)
+				continue
+			}
+
+			if !ok {
+				continue
+			}
+
+			policyMatched = true
+
+			priority, known := e.effectPrecedence[rule.rule.Effect]
+			if best == nil {
+				best = &matchSource{
+					effect:     rule.rule.Effect,
+					policyName: pol.policy.Name,
+					ruleID:     rule.rule.ID,
+					message:    rule.rule.Description,
+				}
+				if known {
+					bestPriority = priority
+				}
+			} else if known && (bestPriority == -1 || priority < bestPriority) {
+				best.effect = rule.rule.Effect
+				best.policyName = pol.policy.Name
+				best.ruleID = rule.rule.ID
+				best.message = rule.rule.Description
+				best.isDefault = false
+				bestPriority = priority
+			}
+
+			// Short-circuit: matched the highest-priority effect
+			if known && priority == 0 {
+				return e.buildDecision(best, evaluated, policyErrors)
+			}
+		}
+
+		if !policyMatched && pol.hasLocalDefault {
+			priority, known := e.effectPrecedence[pol.defaultEffect]
+			if best == nil {
+				best = &matchSource{
+					effect:     pol.defaultEffect,
+					policyName: pol.policy.Name,
+					message:    "policy default effect applied",
+					isDefault:  true,
+				}
+				if known {
+					bestPriority = priority
+				}
+			} else if known && (bestPriority == -1 || priority < bestPriority) {
+				best.effect = pol.defaultEffect
+				best.policyName = pol.policy.Name
+				best.ruleID = ""
+				best.message = "policy default effect applied"
+				best.isDefault = true
+				bestPriority = priority
+			}
+
+			if known && priority == 0 {
+				return e.buildDecision(best, evaluated, policyErrors)
+			}
+		}
+	}
+
+	if best != nil {
+		return e.buildDecision(best, evaluated, policyErrors)
+	}
+
+	decision.Evaluated = evaluated
+	decision.Error = joinErrors(flattenErrors(policyErrors))
+	decision.ErrorMessage = cleanErrorMessage(decision.Error)
+	return decision
+}
+
+func (e *Engine) buildDecision(src *matchSource, evaluated int, policyErrors [][]error) Decision {
+	allErrors := joinErrors(flattenErrors(policyErrors))
+	return Decision{
+		Effect:       src.effect,
+		Policy:       src.policyName,
+		Rule:         src.ruleID,
+		Message:      src.message,
+		Matched:      true,
+		Evaluated:    evaluated,
+		Error:        allErrors,
+		ErrorMessage: cleanErrorMessage(allErrors),
+	}
+}
+
 type compiledPolicy struct {
 	policy          Policy
 	rules           []*compiledRule