feat: evidence composition — compile-time reference resolution for evidence sub-rules

An evidence may now reference another derived evidence as a sub-rule
(WHEN can_read(user, doc) where can_read is itself an evidence). Resolution
is a compile-time linker pass: after every evidence config is generated, each
direct reference to an evidence is inlined with that evidence's own (resolved)
config, so the engine evaluates a fully-resolved, acyclic config tree.

- resolveEvidenceReferences(): post-generation pass over evidence configs,
  recursing into logical/defeasible containers (when/unless/never/always/
  requires/union/intersection), always.direct nests, and comparator operands.
- Forward references resolve (all configs exist before the pass runs).
- Cycles and self-references are compile-time errors.
- _subjectAsObject scoping is preserved through inlining.
- dependsOn is recomputed after resolution, so partial-graph requirements
  reach transitively through composed evidence.
- buildDirectRule/buildPredicateRule now apply subject-scoping to top-level
  PredicateCall evidence bodies (latent gap, previously missed).
- validation: reject relation names shared across facts/sources/evidence/
  measures (a collision silently overwrote configs and read as a false cycle).

Tests: EvidenceComposition (9), DSLRuntime transitive requiredFacts, oracle
campaign composition construct, illegal-mutations cycle + cross-kind cases.

src/generator/RuleGenerator.js

@@ -10,6 +10,7 @@ export class RuleGenerator {
     this.generatedRules = new Map();
     this.errors = [];
     this.dependencyIndex = new Map();
+    this.evidenceNames = new Set();
   }
 
   /**
@@ -38,6 +39,14 @@ export class RuleGenerator {
         this.generateFactConfig(fact);
       });
 
+      // Resolve evidence composition: a rule that references another derived
+      // evidence (WHEN can_read(user, doc) where can_read is an evidence) is
+      // lowered in place to that evidence's own config — compile-time inlining
+      // (a linker pass), so the engine evaluates a fully-resolved config tree
+      // and never needs a sub-query traversal mechanism. Forward references are
+      // handled because every evidence config is built before this pass runs.
+      this.resolveEvidenceReferences();
+
       // Apply generated rules to arbiter
       this.applyRulesToArbiter();
 
@@ -62,6 +71,7 @@ export class RuleGenerator {
    */
   generateEvidenceRules(evidence) {
     const relationName = evidence.name;
+    this.evidenceNames.add(relationName);
     const ruleConfig = this.buildRuleConfig(evidence);
     
     if (ruleConfig) {
@@ -162,6 +172,7 @@ export class RuleGenerator {
           for (const child of ruleList) collect(child, targetSet);
         }
         if (node?.rule) collect(node.rule, targetSet);
+        if (node?.direct) collect(node.direct, targetSet);
       }
     };
 
@@ -274,7 +285,7 @@ export class RuleGenerator {
   buildSingleStatementRule(statement, evidence) {
     switch (statement.type) {
       case 'DirectEvidence':
-        return this.buildDirectRule(statement);
+        return this.buildDirectRule(statement, evidence);
       case 'PatternMatch':
         return this.buildPatternMatchRule(statement, evidence);
       case 'DefeasibleLogic':
@@ -282,7 +293,7 @@ export class RuleGenerator {
       case 'Fusion':
         return this.buildFusionRule(statement);
       case 'PredicateCall':
-        return this.buildPredicateRule(statement);
+        return this.buildPredicateRule(statement, evidence);
       case 'UnaryExpression':
         return this.buildUnaryRule(statement);
       case 'BinaryExpression':
@@ -291,7 +302,7 @@ export class RuleGenerator {
       case 'Expression':
         // Handle expressions that might be predicate calls
         if (statement.type === 'PredicateCall') {
-          return this.buildPredicateRule(statement);
+          return this.buildPredicateRule(statement, evidence);
         }
         return this.buildRuleFromExpressionNode(statement, evidence);
       default:
@@ -459,7 +470,7 @@ export class RuleGenerator {
    * @param {DirectEvidenceNode} directEvidence - Direct evidence statement
    * @returns {Object|null} Rule configuration or null
    */
-  buildDirectRule(directEvidence) {
+  buildDirectRule(directEvidence, evidence) {
     if (!directEvidence.predicate) {
       this.errors.push('Direct evidence must have a predicate');
       return null;
@@ -467,12 +478,24 @@ export class RuleGenerator {
 
     const predicate = directEvidence.predicate;
     const relation = predicate.name;
-    
-    return {
+
+    const rule = {
       type: 'direct',
       relation: relation,
       reverse: false
     };
+
+    // Subject-scoped (unary) call: the predicate call's args omit the
+    // evidence's object parameter (user_risk(user, 1) inside a binary
+    // evidence) → check the relation on the subject itself.
+    const evidenceParams = (evidence && evidence.params) || [];
+    const objectVar = evidenceParams[1] && evidenceParams[1].name;
+    const argName = a => a && (a.name !== undefined ? a.name : a.value);
+    if (objectVar !== undefined && !(predicate.arguments || []).some(a => argName(a) === objectVar)) {
+      rule._subjectAsObject = true;
+    }
+
+    return rule;
   }
 
   /**
@@ -925,9 +948,6 @@ export class RuleGenerator {
    * @returns {Object|null} Rule configuration or null
    */
   buildDirectRuleFromPredicate(predicate, evidence) {
-    const expanded = this._expandPredicate(predicate.name);
-    if (expanded) return expanded;
-
     const rule = {
       type: 'direct',
       relation: predicate.name,
@@ -944,36 +964,105 @@ export class RuleGenerator {
     return rule;
   }
 
-  _expandPredicate(predicateName) {
-    const existingConfig = this.generatedRules.get(predicateName) || this.arbiter?.relationConfigs?.get(predicateName);
-    if (!existingConfig) return null;
-    if (!existingConfig.union && !existingConfig.intersection && !existingConfig.exclusion) return null;
+  _expandPredicate() {
+    // Replaced by resolveEvidenceReferences() (the compile-time evidence
+    // composition pass). Predicate references are now emitted as direct rules
+    // and inlined during resolution, which also handles forward references and
+    // preserves the correct _subjectAsObject scoping.
+  }
 
-    const logicalKey = existingConfig.union ? 'union' : existingConfig.intersection ? 'intersection' : 'exclusion';
-    const subRules = Array.isArray(existingConfig[logicalKey]?.rules)
-      ? existingConfig[logicalKey].rules
-      : Array.isArray(existingConfig[logicalKey]) ? existingConfig[logicalKey] : [];
+  /**
+   * Evidence composition pass. Every rule that references a DERIVED evidence
+   * (e.g. `WHEN can_read(user, doc)` where can_read is itself an evidence) is
+   * rewritten to inline that evidence's own config. This runs after all
+   * evidence configs are generated, so forward references resolve; cycles are
+   * detected and reported. The engine therefore evaluates a fully-resolved,
+   * acyclic config tree — no runtime sub-query traversal is needed.
+   */
+  resolveEvidenceReferences() {
+    for (const name of this.evidenceNames) {
+      if (!this.generatedRules.has(name)) continue;
+      const stack = new Set([name]);
+      const resolved = this._resolveRule(this.generatedRules.get(name), stack);
+      this.generatedRules.set(name, resolved);
+      this._annotateDependencies(name, resolved);
+    }
+  }
 
-    if (subRules.length === 0) return null;
+  /**
+   * Recursively rewrite a rule tree, inlining references to derived evidence
+   * configs. `stack` holds the evidence names currently being expanded so a
+   * cyclic reference (A → B → A) is detected and reported.
+   */
+  _resolveRule(rule, stack) {
+    if (!rule || typeof rule !== 'object') return rule;
+    if (Array.isArray(rule)) return rule.map(r => this._resolveRule(r, stack));
 
-    const expandedRules = subRules.map(r => {
-      if (r && r.type === 'direct') return { type: 'direct', relation: r.relation, reverse: !!r.reverse };
-      if (typeof r === 'string') return { type: 'direct', relation: r, reverse: false };
-      return null;
-    }).filter(Boolean);
+    // Direct rule referencing a derived evidence → inline its resolved config.
+    if (rule.type === 'direct' && rule.relation) {
+      const ref = rule.relation;
+      if (this.evidenceNames.has(ref)) {
+        const referencedConfig = this.generatedRules.get(ref);
+        if (referencedConfig) {
+          if (stack.has(ref)) {
+            this.errors.push(`Cyclic evidence reference involving '${ref}'. Evidence composition must be acyclic.`);
+            return rule;
+          }
+          const refStack = new Set(stack);
+          refStack.add(ref);
+          const resolvedRef = this._resolveRule(referencedConfig, refStack);
+          if (resolvedRef) {
+            const clone = this._deepCloneRule(resolvedRef);
+            if (rule._subjectAsObject) clone._subjectAsObject = true;
+            return clone;
+          }
+        }
+      }
+      return rule;
+    }
 
-    if (expandedRules.length === 0) return null;
+    // Recurse into logical / defeasible / nested containers: rule-lists
+    // (union/intersection/exclusion/never/requires/when/unless .rules) and
+    // single nested rules (always.direct, comparator operands).
+    const out = { ...rule };
+    for (const key of ['union', 'intersection', 'exclusion', 'never', 'always', 'requires', 'when', 'unless', 'direct', 'rule']) {
+      const node = out[key];
+      if (!node || typeof node !== 'object') continue;
+      if (Array.isArray(node)) {
+        out[key] = node.map(r => this._resolveRule(r, stack));
+        continue;
+      }
+      const next = { ...node };
+      if (Array.isArray(next.rules)) {
+        next.rules = next.rules.map(r => this._resolveRule(r, stack));
+      }
+      if (next.union && Array.isArray(next.union.rules)) {
+        next.union = { ...next.union, rules: next.union.rules.map(r => this._resolveRule(r, stack)) };
+      }
+      if (next.intersection && Array.isArray(next.intersection.rules)) {
+        next.intersection = { ...next.intersection, rules: next.intersection.rules.map(r => this._resolveRule(r, stack)) };
+      }
+      if (next.direct && typeof next.direct === 'object') {
+        next.direct = this._resolveRule(next.direct, stack);
+      }
+      if (next.rule && typeof next.rule === 'object') {
+        next.rule = this._resolveRule(next.rule, stack);
+      }
+      out[key] = next;
+    }
+    if (out.type === 'relational_comparator') {
+      if (out.left?.rule) out.left = { ...out.left, rule: this._resolveRule(out.left.rule, stack) };
+      if (out.right?.rule) out.right = { ...out.right, rule: this._resolveRule(out.right.rule, stack) };
+    }
+    return out;
+  }
 
-    return {
-      type: 'logical',
-      [logicalKey]: {
-        rules: expandedRules,
-        aggregator: existingConfig[logicalKey]?.aggregator || 'min'
-      },
-      // Flag to tell the evaluator: this expanded sub-predicate is unary —
-      // use the subject as the object instead of inheriting the parent's object.
-      _subjectAsObject: true
-    };
+  _deepCloneRule(rule) {
+    try {
+      return structuredClone(rule);
+    } catch {
+      return JSON.parse(JSON.stringify(rule));
+    }
   }
 
   /**
@@ -1120,11 +1209,6 @@ export class RuleGenerator {
       return this.buildChallengeRule(expression, null);
     }
 
-    // Expand composite (logical) predicate references into their direct
-    // leaf components so the optimizer can flatten to a correct direct_list.
-    const expanded = this._expandPredicate(predicateName);
-    if (expanded) return expanded;
-
     const rule = {
       type: 'direct',
       relation: predicateName,

src/validation/DSLValidation.js

@@ -41,6 +41,7 @@ export function validateDslText(dslText, options = {}) {
   validateSources(program, tables, errors, warnings, dslText);
   validateMeasures(program, tables, errors, warnings, dslText);
   validateEvidence(program, tables, errors, warnings, dslText);
+  validateCrossKindRelationNames(program, errors, warnings, dslText);
 
   return {
     success: errors.length === 0,
@@ -335,6 +336,37 @@ function validateEvidence(program, tables, errors, warnings, source) {
   }
 }
 
+/**
+ * Relation names must be unique across facts, sources, evidence, and measures.
+ * A fact and an evidence sharing a name would silently overwrite each other's
+ * relation config during generation (and read as a false cyclic reference).
+ */
+function validateCrossKindRelationNames(program, errors, warnings, source) {
+  const seen = new Map();
+  const kinds = [
+    ['fact', program.facts],
+    ['source', program.sources],
+    ['evidence', program.evidence],
+    ['measure', program.measures]
+  ];
+  for (const [kind, items] of kinds) {
+    for (const item of items || []) {
+      const prev = seen.get(item.name);
+      if (prev) {
+        errors.push(createError({
+          message: `Name '${item.name}' is already used by a ${prev} declaration.`,
+          rule: 'Relation names must be unique across facts, sources, evidence, and measures.',
+          fix: `Rename the ${kind} or the ${prev} to a unique name.`,
+          location: findLocation(source, `${kind} ${item.name}`),
+          context: formatContext(source, findLocation(source, item.name))
+        }));
+      } else {
+        seen.set(item.name, kind);
+      }
+    }
+  }
+}
+
 function validateEvidenceBody(body, scope, tables, errors, warnings, source, parent) {
   for (const stmt of body.statements || []) {
     switch (stmt.type) {