@highflame/policy 2.1.0 → 2.1.1

package/dist/explain.d.ts

@@ -46,6 +46,18 @@ export interface PolicyExplanation {
     /** Raw Cedar condition text if the policy uses rawCondition instead of structured conditions */
     raw_condition?: string;
 }
+/**
+ * Identifies the detector that produced a context value.
+ * Used for provenance tracking — linking policy conditions back to their source detector.
+ */
+export interface EvidenceSource {
+    /** Detector name (e.g., "injection", "secrets", "tool_validator") */
+    detector: string;
+    /** Detector execution latency in milliseconds */
+    latency_ms?: number;
+    /** Producer-specific metadata (e.g., "tier", "phase", "priority"). Treated as opaque key-value pairs. */
+    labels?: Record<string, string>;
+}
 /**
  * Result of evaluating a single condition against the request context.
  */
@@ -60,6 +72,15 @@ export interface ConditionResult {
     actual?: unknown;
     /** Whether this condition matched */
     matched: boolean;
+    /** Source detector that produced this context value (when provenance is available) */
+    source?: EvidenceSource;
+}
+/**
+ * Options for explainDecision.
+ */
+export interface ExplainOptions {
+    /** Maps context field names to the detector that produced them */
+    provenance?: Record<string, EvidenceSource>;
 }
 /** Evaluated comparison: context.field <op> value */
 export interface EvaluatedComparison {
@@ -69,6 +90,8 @@ export interface EvaluatedComparison {
     expected: string | number | boolean | string[];
     actual: unknown;
     matched: boolean;
+    /** Source detector that produced this context value (when provenance is available) */
+    source?: EvidenceSource;
 }
 /** Evaluated contains: context.field.contains(value) */
 export interface EvaluatedContains {
@@ -77,6 +100,8 @@ export interface EvaluatedContains {
     expected: string | number | boolean;
     actual: unknown;
     matched: boolean;
+    /** Source detector that produced this context value (when provenance is available) */
+    source?: EvidenceSource;
 }
 /** Evaluated like: context.field like "pattern" */
 export interface EvaluatedLike {
@@ -85,6 +110,8 @@ export interface EvaluatedLike {
     pattern: string;
     actual: unknown;
     matched: boolean;
+    /** Source detector that produced this context value (when provenance is available) */
+    source?: EvidenceSource;
 }
 /** Evaluated has: context has field */
 export interface EvaluatedHas {
@@ -142,9 +169,10 @@ export type EvaluatedExpression = EvaluatedComparison | EvaluatedContains | Eval
  * }
  * ```
  */
-export declare function explainDecision(decision: DecisionInput, rules: PolicyRule[], context: Record<string, unknown>): ExplainedDecision;
+export declare function explainDecision(decision: DecisionInput, rules: PolicyRule[], context: Record<string, unknown>, options?: ExplainOptions): ExplainedDecision;
 /**
  * Recursively evaluate a ConditionExpression tree against a context map.
  * Returns an EvaluatedExpression tree with `matched` booleans and `actual` values.
+ * The optional provenance map links context field names to their source detectors.
  */
-export declare function evaluateExpression(expr: ConditionExpression, context: Record<string, unknown>): EvaluatedExpression;
+export declare function evaluateExpression(expr: ConditionExpression, context: Record<string, unknown>, provenance?: Record<string, EvidenceSource>): EvaluatedExpression;

package/dist/explain.js

@@ -29,7 +29,8 @@
  * }
  * ```
  */
-export function explainDecision(decision, rules, context) {
+export function explainDecision(decision, rules, context, options) {
+    const provenance = options?.provenance;
     // Build lookup map: annotations.id → PolicyRule
     const ruleMap = new Map();
     for (const rule of rules) {
@@ -49,7 +50,7 @@ export function explainDecision(decision, rules, context) {
         // Recursive condition evaluation
         let evaluatedExpression;
         if (rule.conditionExpression) {
-            evaluatedExpression = evaluateExpression(rule.conditionExpression, context);
+            evaluatedExpression = evaluateExpression(rule.conditionExpression, context, provenance);
         }
         // Populate condition_results: prefer leaf extraction from expression tree,
         // fall back to flat conditions[] for backward compat with simple policies
@@ -62,7 +63,11 @@ export function explainDecision(decision, rules, context) {
             conditionResults = conditions.map(cond => {
                 const actual = context[cond.field];
                 const matched = evaluateCondition(cond.operator, actual, cond.value);
-                return { field: cond.field, operator: cond.operator, expected: cond.value, actual, matched };
+                const result = { field: cond.field, operator: cond.operator, expected: cond.value, actual, matched };
+                if (provenance?.[cond.field]) {
+                    result.source = provenance[cond.field];
+                }
+                return result;
             });
         }
         // Surface rawCondition when there are no structured conditions and no expression tree
@@ -93,19 +98,20 @@ export function explainDecision(decision, rules, context) {
 /**
  * Recursively evaluate a ConditionExpression tree against a context map.
  * Returns an EvaluatedExpression tree with `matched` booleans and `actual` values.
+ * The optional provenance map links context field names to their source detectors.
  */
-export function evaluateExpression(expr, context) {
+export function evaluateExpression(expr, context, provenance) {
     switch (expr.kind) {
         case 'and': {
-            const children = expr.children.map(c => evaluateExpression(c, context));
+            const children = expr.children.map(c => evaluateExpression(c, context, provenance));
             return { kind: 'and', children, matched: children.every(c => c.matched) };
         }
         case 'or': {
-            const children = expr.children.map(c => evaluateExpression(c, context));
+            const children = expr.children.map(c => evaluateExpression(c, context, provenance));
             return { kind: 'or', children, matched: children.some(c => c.matched) };
         }
         case 'not': {
-            const child = evaluateExpression(expr.child, context);
+            const child = evaluateExpression(expr.child, context, provenance);
             return { kind: 'not', child, matched: !child.matched };
         }
         case 'has': {
@@ -115,17 +121,26 @@ export function evaluateExpression(expr, context) {
         case 'comparison': {
             const actual = context[expr.field];
             const matched = evaluateCondition(expr.operator, actual, expr.value);
-            return { kind: 'comparison', field: expr.field, operator: expr.operator, expected: expr.value, actual, matched };
+            const result = { kind: 'comparison', field: expr.field, operator: expr.operator, expected: expr.value, actual, matched };
+            if (provenance?.[expr.field])
+                result.source = provenance[expr.field];
+            return result;
         }
         case 'contains': {
             const actual = context[expr.field];
             const matched = evaluateContains(actual, expr.value);
-            return { kind: 'contains', field: expr.field, expected: expr.value, actual, matched };
+            const result = { kind: 'contains', field: expr.field, expected: expr.value, actual, matched };
+            if (provenance?.[expr.field])
+                result.source = provenance[expr.field];
+            return result;
         }
         case 'like': {
             const actual = context[expr.field];
             const matched = evaluateLike(actual, expr.pattern);
-            return { kind: 'like', field: expr.field, pattern: expr.pattern, actual, matched };
+            const result = { kind: 'like', field: expr.field, pattern: expr.pattern, actual, matched };
+            if (provenance?.[expr.field])
+                result.source = provenance[expr.field];
+            return result;
         }
         case 'raw':
             return { kind: 'raw', text: expr.text, matched: false };
@@ -296,12 +311,24 @@ function collectLeafResults(expr) {
         case 'has':
         case 'raw':
             return [];
-        case 'comparison':
-            return [{ field: expr.field, operator: expr.operator, expected: expr.expected, actual: expr.actual, matched: expr.matched }];
-        case 'contains':
-            return [{ field: expr.field, operator: 'contains', expected: expr.expected, actual: expr.actual, matched: expr.matched }];
-        case 'like':
-            return [{ field: expr.field, operator: 'like', expected: expr.pattern, actual: expr.actual, matched: expr.matched }];
+        case 'comparison': {
+            const result = { field: expr.field, operator: expr.operator, expected: expr.expected, actual: expr.actual, matched: expr.matched };
+            if (expr.source)
+                result.source = expr.source;
+            return [result];
+        }
+        case 'contains': {
+            const result = { field: expr.field, operator: 'contains', expected: expr.expected, actual: expr.actual, matched: expr.matched };
+            if (expr.source)
+                result.source = expr.source;
+            return [result];
+        }
+        case 'like': {
+            const result = { field: expr.field, operator: 'like', expected: expr.pattern, actual: expr.actual, matched: expr.matched };
+            if (expr.source)
+                result.source = expr.source;
+            return [result];
+        }
     }
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highflame/policy",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "Highflame Cedar policy types and engine wrapper",
   "readme": "README.md",
   "main": "dist/index.js",