Log every authorization decision from the authorizer

Denials were invisible in the audit trail and evaluator explainability
(policy_id, reason) was discarded before reaching logs. Emit a structured
authz decision line on every evaluation in evaluateMultiInTx — allow,
deny, no_match, and assumption errors — using the existing authorizer
logger with opaque IDs only.

Add decision_log.go with DecisionRecord and logDecision. Surface
PolicyID and Reason on EvaluationResult for logging. Audit log
behavior is unchanged (allow-only). Document the convention in
authorization.md.

Signed-off-by: Ludovic Vielle <ludovic@probo.com>

pkg/iam/policy/evaluator.go

@@ -47,6 +47,52 @@ func (r EvaluationResult) IsAllowed() bool {
 	return r.Decision == DecisionAllow
 }
 
+func (r EvaluationResult) statementSID() string {
+	if r.MatchedStatement != nil {
+		return r.MatchedStatement.SID
+	}
+
+	return ""
+}
+
+// PolicyID returns the statement SID or matched policy ID for logging.
+func (r EvaluationResult) PolicyID() string {
+	if sid := r.statementSID(); sid != "" {
+		return sid
+	}
+
+	if r.MatchedPolicy != nil {
+		return r.MatchedPolicy.ID
+	}
+
+	return ""
+}
+
+// Reason returns a human-readable explanation for logging.
+func (r EvaluationResult) Reason(role string) string {
+	if sid := r.statementSID(); sid != "" {
+		switch r.Decision {
+		case DecisionAllow:
+			return "allowed by statement " + sid
+		case DecisionDeny:
+			return "explicit deny by statement " + sid
+		}
+	}
+
+	switch r.Decision {
+	case DecisionAllow:
+		return "allowed"
+	case DecisionDeny:
+		return "explicit deny"
+	default:
+		if role != "" {
+			return "implicit deny: no matching allow for role " + role
+		}
+
+		return "implicit deny: no matching allow"
+	}
+}
+
 // AuthorizationRequest contains all information needed to evaluate access.
 type AuthorizationRequest struct {
 	// Principal is the actor requesting access.

pkg/iam/policy/evaluator_test.go

@@ -462,3 +462,52 @@ func TestEvaluationResult_IsAllowed(t *testing.T) {
 		})
 	}
 }
+
+func TestEvaluationResult_PolicyID(t *testing.T) {
+	t.Parallel()
+
+	result := EvaluationResult{
+		Decision: DecisionAllow,
+		MatchedStatement: &Statement{
+			SID: "read-thirdParties",
+		},
+		MatchedPolicy: &Policy{
+			ID: "probo:viewer",
+		},
+	}
+
+	if got := result.PolicyID(); got != "read-thirdParties" {
+		t.Errorf("PolicyID() = %q, want read-thirdParties", got)
+	}
+}
+
+func TestEvaluationResult_Reason(t *testing.T) {
+	t.Parallel()
+
+	t.Run("implicit deny includes role", func(t *testing.T) {
+		t.Parallel()
+
+		result := EvaluationResult{Decision: DecisionNoMatch}
+		want := "implicit deny: no matching allow for role VIEWER"
+
+		if got := result.Reason("VIEWER"); got != want {
+			t.Errorf("Reason() = %q, want %q", got, want)
+		}
+	})
+
+	t.Run("explicit deny uses statement sid", func(t *testing.T) {
+		t.Parallel()
+
+		result := EvaluationResult{
+			Decision: DecisionDeny,
+			MatchedStatement: &Statement{
+				SID: "deny-delete",
+			},
+		}
+		want := "explicit deny by statement deny-delete"
+
+		if got := result.Reason("ADMIN"); got != want {
+			t.Errorf("Reason() = %q, want %q", got, want)
+		}
+	})
+}