@higher.archi/boe 1.0.0

package/dist/engines/defeasible/types.d.ts

@@ -0,0 +1,316 @@
+/**
+ * Defeasible Engine Types
+ *
+ * Non-monotonic reasoning engine that supports rules which can be
+ * defeated (overridden) by other rules. Unlike classical logic where
+ * conclusions are absolute, defeasible logic allows:
+ *
+ * - Strict rules: Cannot be defeated (absolute truths)
+ * - Defeasible rules: Can be overridden by stronger/more specific rules
+ * - Defeaters: Block conclusions without asserting alternatives
+ *
+ * Classic example: "Birds fly" is defeated by "Penguins don't fly"
+ * when the subject is a penguin.
+ */
+import { BaseRule, BaseRuleSet, InputParameter, CompiledBaseRule, CompiledBaseRuleSet, CompiledInputParameter, BindingContext } from '../../core';
+/**
+ * Rule strength determines defeat behavior:
+ * - strict: Cannot be defeated, always applies if conditions match
+ * - defeasible: Can be defeated by other rules
+ * - defeater: Only blocks conclusions, doesn't assert anything
+ */
+export type RuleStrength = 'strict' | 'defeasible' | 'defeater';
+/**
+ * Conclusion status after evaluation
+ */
+export type ConclusionStatus = 'definitely' | 'defeasibly' | 'defeated' | 'blocked' | 'undecided';
+/**
+ * Semantic defeat strength labels - human-readable
+ */
+export type SemanticDefeatStrength = 'completely' | 'strongly' | 'moderately' | 'weakly';
+/**
+ * Semantic strength to numeric mapping
+ */
+export declare const SEMANTIC_DEFEAT_STRENGTHS: Record<SemanticDefeatStrength, number>;
+/**
+ * Defeat target - flexible format
+ * - string: Binary defeat (100%)
+ * - { rule, strength: number }: Weighted defeat
+ * - { rule, strength: SemanticDefeatStrength }: Semantic defeat
+ */
+export type DefeatTarget = string | {
+    rule: string;
+    strength: number;
+} | {
+    rule: string;
+    strength: SemanticDefeatStrength;
+};
+/**
+ * Credibility - how reliable is this rule?
+ */
+export type Credibility = number | 'high' | 'medium' | 'low';
+/**
+ * Credibility to numeric mapping
+ */
+export declare const SEMANTIC_CREDIBILITIES: Record<string, number>;
+/**
+ * Defeasible rule definition
+ *
+ * @example Defeasible rule (can be defeated)
+ * ```typescript
+ * {
+ *   id: 'birds-fly',
+ *   inputs: [{ name: 'x', type: 'Animal' }],
+ *   when: ['equals', '$x.class', 'bird'],
+ *   conclude: 'canFly',
+ *   strength: 'defeasible'  // default
+ * }
+ * ```
+ *
+ * @example Strict rule (cannot be defeated)
+ * ```typescript
+ * {
+ *   id: 'dead-things-dont-fly',
+ *   inputs: [{ name: 'x', type: 'Animal' }],
+ *   when: ['equals', '$x.alive', false],
+ *   conclude: { not: 'canFly' },
+ *   strength: 'strict'
+ * }
+ * ```
+ *
+ * @example Defeating rule with weight
+ * ```typescript
+ * {
+ *   id: 'tired-birds',
+ *   inputs: [{ name: 'x', type: 'Animal' }],
+ *   when: ['equals', '$x.tired', true],
+ *   conclude: { not: 'canFly' },
+ *   defeats: [{ rule: 'birds-fly', strength: 0.8 }]
+ * }
+ * ```
+ */
+export type DefeasibleRule = BaseRule & {
+    /**
+     * What this rule concludes if it fires.
+     * - string: Positive conclusion (e.g., 'canFly')
+     * - { not: string }: Negative conclusion (e.g., { not: 'canFly' })
+     * - undefined: For defeaters that only block
+     */
+    conclude?: string | {
+        not: string;
+    };
+    /**
+     * Rule strength (default: 'defeasible')
+     */
+    strength?: RuleStrength;
+    /**
+     * How reliable is this rule? (default: 1.0)
+     */
+    credibility?: Credibility;
+    /**
+     * Rules that this rule defeats (by rule ID)
+     * Supports binary, weighted, and semantic formats
+     */
+    defeats?: DefeatTarget[];
+    /**
+     * Human-readable explanation of why this rule fires.
+     * Useful for audit trails and explainability.
+     */
+    explanation?: string;
+};
+/**
+ * Superiority relation - explicit defeat ordering between rules
+ */
+export type SuperiorityRelation = {
+    superior: string;
+    inferior: string;
+};
+/**
+ * Aggregation strategy for confidence calculation
+ */
+export type AggregationStrategy = 'average' | 'max-min' | 'weighted-sum' | 'probabilistic';
+/**
+ * Defeasible engine configuration
+ */
+export type DefeasibleConfig = {
+    mode: 'defeasible';
+    /**
+     * How to calculate confidence when rules conflict
+     * Default: 'average'
+     */
+    aggregation?: AggregationStrategy;
+    /**
+     * Confidence threshold for 'holds' (default: 0.5)
+     */
+    threshold?: number;
+    /**
+     * How to resolve conflicts when not explicitly specified
+     * - 'specificity': More conditions = more specific = wins
+     * - 'priority': Higher salience wins
+     * - 'explicit': Only explicit defeats/superiority apply
+     * Default: 'specificity'
+     */
+    conflictResolution?: 'specificity' | 'priority' | 'explicit';
+    /**
+     * Maximum iterations for computing defeat cycles (default: 100)
+     */
+    maxIterations?: number;
+};
+/**
+ * Defeasible ruleset
+ */
+export type DefeasibleRuleSet = BaseRuleSet & {
+    mode: 'defeasible';
+    inputs?: InputParameter[];
+    rules: DefeasibleRule[];
+    /**
+     * Explicit superiority relations between rules
+     */
+    superiority?: SuperiorityRelation[];
+    config?: Partial<DefeasibleConfig>;
+};
+/**
+ * Compiled conclusion
+ */
+export type CompiledConclusion = {
+    literal: string;
+    positive: boolean;
+};
+/**
+ * Compiled defeat with normalized strength
+ */
+export type CompiledDefeat = {
+    rule: string;
+    strength: number;
+};
+/**
+ * Compiled defeasible rule
+ */
+export type CompiledDefeasibleRule = CompiledBaseRule & {
+    strength: RuleStrength;
+    credibility: number;
+    conclusion: CompiledConclusion | null;
+    defeats: CompiledDefeat[];
+    specificity: number;
+};
+/**
+ * Compiled superiority map for O(1) lookup
+ * Maps: inferior rule ID -> set of superior rule IDs
+ */
+export type SuperiorityMap = Map<string, Set<string>>;
+/**
+ * Compiled defeasible ruleset
+ */
+export type CompiledDefeasibleRuleSet = CompiledBaseRuleSet & {
+    mode: 'defeasible';
+    inputs: CompiledInputParameter[];
+    rules: CompiledDefeasibleRule[];
+    superiority: SuperiorityMap;
+    config: Required<DefeasibleConfig>;
+};
+/**
+ * A fired rule with its binding context
+ */
+export type FiredRule = {
+    ruleId: string;
+    conclusion: CompiledConclusion | null;
+    credibility: number;
+    bindings: BindingContext;
+};
+/**
+ * A conclusion with its derivation
+ */
+export type Derivation = {
+    conclusion: string;
+    positive: boolean;
+    holds: boolean;
+    confidence: number;
+    status: ConclusionStatus;
+    supportingRules: string[];
+    defeatedBy: string[];
+    bindings: BindingContext;
+};
+/**
+ * Conflict between rules
+ */
+export type Conflict = {
+    conclusion: string;
+    positiveRules: string[];
+    negativeRules: string[];
+    winner: 'positive' | 'negative' | 'undecided';
+    reason: string;
+};
+/**
+ * Runtime options for defeasible execution
+ */
+export type DefeasibleOptions = {
+    /**
+     * Specific conclusions to query (if omitted, computes all)
+     */
+    query?: string[];
+    /**
+     * Callback when a rule fires
+     */
+    onFire?: (ruleId: string, conclusion: CompiledConclusion | null, context: BindingContext) => void;
+    /**
+     * Callback when a defeat occurs
+     */
+    onDefeat?: (defeated: string, by: string, conclusion: string) => void;
+    /**
+     * Callback when a conflict is resolved
+     */
+    onConflict?: (conflict: Conflict) => void;
+};
+/**
+ * Defeasible execution result
+ */
+export type DefeasibleResult = {
+    /**
+     * All conclusions and their status
+     */
+    conclusions: Record<string, Derivation>;
+    /**
+     * Conclusions that are definitely true (strict rules)
+     */
+    definitely: string[];
+    /**
+     * Conclusions that are defeasibly true (not defeated)
+     */
+    defeasibly: string[];
+    /**
+     * Conclusions that were defeated
+     */
+    defeated: string[];
+    /**
+     * Conflicts that were resolved
+     */
+    conflicts: Conflict[];
+    /**
+     * Rules that fired (in order)
+     */
+    fired: string[];
+    /**
+     * Number of iterations to reach fixed point
+     */
+    iterations: number;
+    /**
+     * Processing time in milliseconds
+     */
+    executionTimeMs: number;
+    /**
+     * Query a specific conclusion
+     */
+    query: (conclusion: string) => QueryResult;
+};
+/**
+ * Query result for a specific conclusion
+ */
+export type QueryResult = {
+    conclusion: string;
+    holds: boolean;
+    confidence: number;
+    status: ConclusionStatus;
+    supportedBy: string[];
+    defeatedBy: string[];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/engines/defeasible/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/engines/defeasible/types.ts"],"names":[],"mappings":"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"}

package/dist/engines/defeasible/types.js

@@ -0,0 +1,35 @@
+"use strict";
+/**
+ * Defeasible Engine Types
+ *
+ * Non-monotonic reasoning engine that supports rules which can be
+ * defeated (overridden) by other rules. Unlike classical logic where
+ * conclusions are absolute, defeasible logic allows:
+ *
+ * - Strict rules: Cannot be defeated (absolute truths)
+ * - Defeasible rules: Can be overridden by stronger/more specific rules
+ * - Defeaters: Block conclusions without asserting alternatives
+ *
+ * Classic example: "Birds fly" is defeated by "Penguins don't fly"
+ * when the subject is a penguin.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEMANTIC_CREDIBILITIES = exports.SEMANTIC_DEFEAT_STRENGTHS = void 0;
+/**
+ * Semantic strength to numeric mapping
+ */
+exports.SEMANTIC_DEFEAT_STRENGTHS = {
+    'completely': 1.0,
+    'strongly': 0.85,
+    'moderately': 0.6,
+    'weakly': 0.3
+};
+/**
+ * Credibility to numeric mapping
+ */
+exports.SEMANTIC_CREDIBILITIES = {
+    'high': 0.9,
+    'medium': 0.7,
+    'low': 0.4
+};
+//# sourceMappingURL=types.js.map

package/dist/engines/defeasible/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/engines/defeasible/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;GAaG;;;AA+CH;;GAEG;AACU,QAAA,yBAAyB,GAA2C;IAC/E,YAAY,EAAE,GAAG;IACjB,UAAU,EAAE,IAAI;IAChB,YAAY,EAAE,GAAG;IACjB,QAAQ,EAAE,GAAG;CACd,CAAC;AAsBF;;GAEG;AACU,QAAA,sBAAsB,GAA2B;IAC5D,MAAM,EAAE,GAAG;IACX,QAAQ,EAAE,GAAG;IACb,KAAK,EAAE,GAAG;CACX,CAAC"}

package/dist/engines/expert/compiler.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Expert System Compiler
+ *
+ * Compiles ExpertRuleSet into optimized form for execution.
+ * Validates templates at compile time to catch errors early.
+ */
+import { ExpertRuleSet, CompiledExpertRuleSet } from './types';
+/**
+ * Compile an expert ruleset.
+ *
+ * @param ruleSet - Source ruleset definition
+ * @returns Compiled ruleset ready for execution
+ * @throws Error if validation fails
+ */
+export declare function compileExpertRuleSet(ruleSet: ExpertRuleSet): CompiledExpertRuleSet;
+//# sourceMappingURL=compiler.d.ts.map

package/dist/engines/expert/compiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../../src/engines/expert/compiler.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,OAAO,EAEL,aAAa,EAGb,qBAAqB,EAKtB,MAAM,SAAS,CAAC;AAqNjB;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,aAAa,GAAG,qBAAqB,CAiClF"}

package/dist/engines/expert/compiler.js

@@ -0,0 +1,205 @@
+"use strict";
+/**
+ * Expert System Compiler
+ *
+ * Compiles ExpertRuleSet into optimized form for execution.
+ * Validates templates at compile time to catch errors early.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileExpertRuleSet = compileExpertRuleSet;
+const core_1 = require("../../core");
+const types_1 = require("./types");
+const interpolation_1 = require("./interpolation");
+// ========================================
+// Helper Functions
+// ========================================
+/**
+ * Normalize confidence to a numeric value (0.0 - 1.0).
+ * Accepts numeric values or semantic labels.
+ */
+function normalizeConfidence(confidence) {
+    if (typeof confidence === 'number') {
+        return Math.max(0, Math.min(1, confidence));
+    }
+    const value = types_1.SEMANTIC_CONFIDENCES[confidence];
+    if (value === undefined) {
+        throw new Error(`Invalid semantic confidence: '${confidence}'. Valid values: ${Object.keys(types_1.SEMANTIC_CONFIDENCES).join(', ')}`);
+    }
+    return value;
+}
+function countConditions(condition) {
+    if (!condition)
+        return 0;
+    if (condition.children) {
+        return 1 + condition.children.reduce((sum, c) => sum + countConditions(c), 0);
+    }
+    return 1;
+}
+function calculateComplexity(inputs, when) {
+    let score = 0;
+    score += inputs.length * 10;
+    score += countConditions(when) * 5;
+    for (const input of inputs) {
+        score += countConditions(input.where) * 2;
+    }
+    return score;
+}
+function compilePath(from) {
+    const str = from.startsWith('$') ? from.slice(1) : from;
+    const parts = str.split('.');
+    return {
+        param: parts[0],
+        path: parts.slice(1)
+    };
+}
+// ========================================
+// Parameter Compilation
+// ========================================
+function compileInputParameter(input) {
+    const compiled = {
+        name: input.name,
+        type: input.type,
+        schema: input.shape ? (0, core_1.normalizeShape)(input.shape) : { type: 'object' }
+    };
+    if (input.where) {
+        compiled.where = (0, core_1.compileCondition)(input.where);
+    }
+    if (input.from) {
+        compiled.from = compilePath(input.from);
+    }
+    return compiled;
+}
+// ========================================
+// Explain Block Compilation
+// ========================================
+/**
+ * Collect all fact names that could be asserted by rules.
+ * Used to build available references for template validation.
+ */
+function collectDerivedFacts(rules) {
+    const facts = new Set();
+    for (const rule of rules) {
+        for (const factName of Object.keys(rule.then.assert)) {
+            facts.add(factName);
+        }
+    }
+    return Array.from(facts);
+}
+/**
+ * Compile an explain block with template validation.
+ */
+function compileExplainBlock(explain, inputNames, derivedFacts, ruleId) {
+    // Get variable names from explain.variables
+    const explainVars = explain.variables ? Object.keys(explain.variables) : [];
+    // Build set of available references
+    const availableRefs = (0, interpolation_1.buildAvailableRefs)(inputNames, derivedFacts, explainVars);
+    // Compile variables expressions
+    const compiledVariables = explain.variables
+        ? Object.fromEntries(Object.entries(explain.variables).map(([name, expr]) => [
+            name,
+            (0, core_1.compileOperand)(expr)
+        ]))
+        : undefined;
+    // Compile templates with validation
+    const compiledOnFire = (0, interpolation_1.compileTemplate)(explain.onFire, availableRefs, ruleId);
+    const compiledOnSkip = explain.onSkip
+        ? (0, interpolation_1.compileTemplate)(explain.onSkip, availableRefs, ruleId)
+        : undefined;
+    const compiledFactors = explain.factors
+        ? explain.factors.map(f => (0, interpolation_1.compileTemplate)(f, availableRefs, ruleId))
+        : undefined;
+    const compiledSuggestion = explain.suggestion
+        ? (0, interpolation_1.compileTemplate)(explain.suggestion, availableRefs, ruleId)
+        : undefined;
+    return {
+        variables: compiledVariables,
+        onFire: compiledOnFire,
+        onSkip: compiledOnSkip,
+        factors: compiledFactors,
+        suggestion: compiledSuggestion
+    };
+}
+// ========================================
+// Rule Compilation
+// ========================================
+/**
+ * Compile a single expert rule.
+ */
+function compileExpertRule(rule, index, derivedFacts) {
+    // Validate required fields
+    if (!rule.description) {
+        throw new Error(`Rule '${rule.id}' is missing required 'description' field`);
+    }
+    if (!rule.explain) {
+        throw new Error(`Rule '${rule.id}' is missing required 'explain' block`);
+    }
+    if (!rule.explain.onFire) {
+        throw new Error(`Rule '${rule.id}' explain block is missing required 'onFire' template`);
+    }
+    // Normalize confidence (handles both numeric and semantic values)
+    const confidence = normalizeConfidence(rule.then.confidence);
+    // Compile inputs
+    const inputs = rule.inputs.map(compileInputParameter);
+    const inputNames = rule.inputs.map(i => i.name);
+    // Compile when condition (for derived facts)
+    const when = rule.when ? (0, core_1.compileCondition)(rule.when) : undefined;
+    // Compile assert expressions
+    const assert = Object.fromEntries(Object.entries(rule.then.assert).map(([name, expr]) => [
+        name,
+        (0, core_1.compileOperand)(expr)
+    ]));
+    // Compile explain block
+    const explain = compileExplainBlock(rule.explain, inputNames, derivedFacts, rule.id);
+    return {
+        id: rule.id,
+        name: rule.name,
+        description: rule.description,
+        salience: rule.salience ?? 0,
+        priority: rule.priority ?? 0,
+        complexity: calculateComplexity(inputs, when),
+        index,
+        inputs,
+        when,
+        assert,
+        confidence,
+        explain
+    };
+}
+// ========================================
+// RuleSet Compilation
+// ========================================
+/**
+ * Compile an expert ruleset.
+ *
+ * @param ruleSet - Source ruleset definition
+ * @returns Compiled ruleset ready for execution
+ * @throws Error if validation fails
+ */
+function compileExpertRuleSet(ruleSet) {
+    // Validate mode
+    if (ruleSet.mode !== 'expert') {
+        throw new Error(`Invalid mode '${ruleSet.mode}' for expert ruleset`);
+    }
+    // Collect all derived facts for reference validation
+    const derivedFacts = collectDerivedFacts(ruleSet.rules);
+    // Compile all rules
+    const compiledRules = ruleSet.rules.map((rule, index) => compileExpertRule(rule, index, derivedFacts));
+    // Sort by priority (higher priority runs later)
+    compiledRules.sort((a, b) => a.priority - b.priority);
+    // Build config with defaults
+    const config = {
+        trackInference: ruleSet.config?.trackInference ?? true,
+        generateExplanations: ruleSet.config?.generateExplanations ?? true,
+        goals: ruleSet.config?.goals ?? [],
+        confidenceThreshold: ruleSet.config?.confidenceThreshold ?? 0.8
+    };
+    return {
+        id: ruleSet.id,
+        name: ruleSet.name,
+        mode: 'expert',
+        schema: ruleSet.shape ? (0, core_1.normalizeShape)(ruleSet.shape) : { type: 'object' },
+        rules: compiledRules,
+        config
+    };
+}
+//# sourceMappingURL=compiler.js.map

package/dist/engines/expert/compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.js","sourceRoot":"","sources":["../../../src/engines/expert/compiler.ts"],"names":[],"mappings":"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"}

package/dist/engines/expert/doc/expert-loan-approval.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Expert System Example: Loan Approval
+ *
+ * Demonstrates an expert system that evaluates loan applications
+ * with full explanation and audit trail capabilities.
+ *
+ * This example shows:
+ * - Tiered classification (credit tiers)
+ * - Derived fact conditions (using `when`)
+ * - Template interpolation with scoped variables
+ * - Goal-directed execution
+ * - Confidence levels
+ * - Denial explanations with suggestions
+ */
+import { ExpertRuleSet } from '../types';
+export declare const loanApprovalRuleSet: ExpertRuleSet;
+//# sourceMappingURL=expert-loan-approval.d.ts.map

package/dist/engines/expert/doc/expert-loan-approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expert-loan-approval.d.ts","sourceRoot":"","sources":["../../../../src/engines/expert/doc/expert-loan-approval.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAKzC,eAAO,MAAM,mBAAmB,EAAE,aAsZjC,CAAC"}