@higher.archi/boe 1.0.0

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

@@ -0,0 +1,346 @@
+/**
+ * Expert System Engine Types
+ *
+ * The Expert System engine provides explainable AI - decisions with full audit
+ * trails showing WHY each conclusion was reached. Unlike Forward Chaining which
+ * focuses on actions, the Expert System captures reasoning as a first-class output.
+ *
+ * Key Concepts:
+ * - Goals: What the system tries to conclude (e.g., 'loanDecision')
+ * - Assertions: Facts derived by rules (e.g., { creditTier: 'good' })
+ * - Inference Chain: Step-by-step reasoning trace
+ * - Explanations: Human-readable descriptions per rule
+ */
+import { BaseRule, BaseRuleSet, CompiledBaseRule, CompiledBaseRuleSet, Condition, Operand, CompiledCondition, CompiledOperand, BindingContext } from '../../core';
+/**
+ * Semantic confidence labels for human-readable rule authoring.
+ * Maps to numeric values between 0.0 and 1.0.
+ */
+export type SemanticConfidence = 'certain' | 'very-high' | 'high' | 'likely' | 'moderate' | 'possible' | 'unlikely' | 'low';
+/**
+ * Mapping from semantic labels to numeric confidence values.
+ */
+export declare const SEMANTIC_CONFIDENCES: Record<SemanticConfidence, number>;
+/**
+ * Confidence value - either numeric (0.0-1.0) or semantic label.
+ */
+export type Confidence = number | SemanticConfidence;
+/**
+ * Explanation block for a rule.
+ *
+ * Templates support ${...} interpolation:
+ * - ${app.creditScore} - Input binding property
+ * - ${creditTier} - Derived/asserted fact
+ * - ${finalRate} - Scoped variable from 'variables'
+ *
+ * Regular $ signs are preserved as-is (no escaping needed).
+ * Example: "$${amount}" -> "$50000"
+ */
+export type ExplainBlock = {
+    /**
+     * Scoped variables computed at explanation time.
+     * Uses standard expression syntax (operators, references).
+     *
+     * @example
+     * variables: {
+     *   finalRate: ['if', '$loyaltyBonus', 5.25, 5.5],
+     *   formattedIncome: ['concat', '$', '$app.annualIncome']
+     * }
+     */
+    variables?: Record<string, Operand>;
+    /**
+     * Template shown when rule fires.
+     * Supports ${...} interpolation.
+     */
+    onFire: string;
+    /**
+     * Template shown when rule is evaluated but doesn't fire.
+     * Useful for explaining why a rule was skipped.
+     */
+    onSkip?: string;
+    /**
+     * Contributing factors for summary generation.
+     * Array of templates that explain what led to the conclusion.
+     */
+    factors?: string[];
+    /**
+     * Actionable suggestion (typically for denials).
+     * Shown in the explanation to guide next steps.
+     */
+    suggestion?: string;
+};
+/**
+ * Expert System rule.
+ *
+ * Unlike Forward Chaining rules that execute actions, Expert System rules
+ * assert conclusions and provide explanations for auditing.
+ */
+export type ExpertRule = BaseRule & {
+    /**
+     * Human-readable description of what this rule does.
+     * Required for expert rules to support explanation generation.
+     */
+    description: string;
+    /**
+     * Additional condition evaluated after input matching.
+     * Can reference derived facts from previously fired rules.
+     *
+     * Use this when your condition depends on facts asserted by other rules,
+     * not just the input facts from working memory.
+     */
+    when?: Condition;
+    /**
+     * Priority for rule ordering.
+     * Higher values run later, allowing rules to depend on derived facts.
+     */
+    priority?: number;
+    /**
+     * Conclusion asserted when rule fires.
+     */
+    then: {
+        /**
+         * Facts to assert when rule fires.
+         * Keys are fact names, values are constants or expressions.
+         *
+         * @example
+         * assert: {
+         *   creditTier: 'good',
+         *   interestRate: ['subtract', '$baseRate', 0.25]
+         * }
+         */
+        assert: Record<string, Operand>;
+        /**
+         * Confidence level for this conclusion.
+         *
+         * Accepts either:
+         * - Numeric value (0.0 - 1.0)
+         * - Semantic label: 'certain', 'very-high', 'high', 'likely',
+         *   'moderate', 'possible', 'unlikely', 'low'
+         *
+         * @example
+         * // Numeric
+         * confidence: 0.85
+         *
+         * // Semantic
+         * confidence: 'high'
+         */
+        confidence: Confidence;
+    };
+    /**
+     * Explanation templates for this rule.
+     * Required for expert rules.
+     */
+    explain: ExplainBlock;
+};
+/**
+ * Expert System configuration.
+ */
+export type ExpertConfig = {
+    /**
+     * Whether to track full inference chain.
+     * @default true
+     */
+    trackInference?: boolean;
+    /**
+     * Whether to generate human-readable explanations.
+     * @default true
+     */
+    generateExplanations?: boolean;
+    /**
+     * Goal facts the system tries to conclude.
+     * Execution stops when all goals are determined.
+     */
+    goals?: string[];
+    /**
+     * Minimum confidence threshold for a conclusion to "hold".
+     * @default 0.8
+     */
+    confidenceThreshold?: number;
+};
+/**
+ * Fact type definitions for validation.
+ * Maps type names to their property schemas.
+ */
+export type FactDefinitions = Record<string, Record<string, string>>;
+/**
+ * Expert System ruleset.
+ */
+export type ExpertRuleSet = BaseRuleSet & {
+    mode: 'expert';
+    rules: ExpertRule[];
+    config?: ExpertConfig;
+    /**
+     * Optional fact type definitions for compile-time validation.
+     */
+    facts?: FactDefinitions;
+};
+/**
+ * Compiled template for efficient interpolation.
+ */
+export type CompiledTemplate = {
+    /** Original template string */
+    source: string;
+    /** Static parts between interpolations */
+    parts: string[];
+    /** Variable references to interpolate */
+    refs: CompiledTemplateRef[];
+};
+/**
+ * Reference within a template.
+ */
+export type CompiledTemplateRef = {
+    /** Full reference path (e.g., 'app.creditScore' or 'creditTier') */
+    path: string[];
+    /** Whether this references an input binding vs derived fact */
+    isBinding: boolean;
+};
+/**
+ * Compiled explanation block.
+ */
+export type CompiledExplainBlock = {
+    variables?: Record<string, CompiledOperand>;
+    onFire: CompiledTemplate;
+    onSkip?: CompiledTemplate;
+    factors?: CompiledTemplate[];
+    suggestion?: CompiledTemplate;
+};
+/**
+ * Compiled expert rule.
+ */
+export type CompiledExpertRule = CompiledBaseRule & {
+    description: string;
+    priority: number;
+    when?: CompiledCondition;
+    assert: Record<string, CompiledOperand>;
+    confidence: number;
+    explain: CompiledExplainBlock;
+};
+/**
+ * Compiled expert ruleset.
+ */
+export type CompiledExpertRuleSet = CompiledBaseRuleSet & {
+    mode: 'expert';
+    rules: CompiledExpertRule[];
+    config: Required<ExpertConfig>;
+};
+/**
+ * Single step in the inference chain.
+ * Captures what happened when a rule was evaluated.
+ */
+export type InferenceStep = {
+    /** Rule that was evaluated */
+    ruleId: string;
+    /** Rule description */
+    description: string;
+    /** Whether the rule fired */
+    fired: boolean;
+    /** Input facts that were examined during evaluation */
+    factsUsed: string[];
+    /** Derived facts referenced in the `when` condition */
+    derivedFactsUsed?: Record<string, unknown>;
+    /** Facts asserted if rule fired */
+    asserted?: Record<string, unknown>;
+    /** Confidence of assertions */
+    confidence?: number;
+    /** Interpolated explanation (onFire or onSkip) */
+    explanation: string;
+};
+/**
+ * Runtime options for expert system execution.
+ */
+export type ExpertOptions = {
+    /**
+     * Callback when a rule fires.
+     */
+    onFire?: (ruleId: string, asserted: Record<string, unknown>, context: BindingContext) => void;
+    /**
+     * Callback when a rule is evaluated.
+     */
+    onEvaluate?: (ruleId: string, fired: boolean) => void;
+    /**
+     * Whether to include skipped rules in inference chain.
+     * @default false
+     */
+    includeSkipped?: boolean;
+    /**
+     * Whether to generate verbose explanations.
+     * @default true
+     */
+    verbose?: boolean;
+    /**
+     * Maximum rules to evaluate (circuit breaker).
+     * @default 1000
+     */
+    maxEvaluations?: number;
+};
+/**
+ * Execution result from the expert system.
+ */
+export type ExpertResult = {
+    /**
+     * All conclusions reached (asserted facts).
+     */
+    conclusions: Record<string, unknown>;
+    /**
+     * Step-by-step reasoning trace.
+     */
+    inferenceChain: InferenceStep[];
+    /**
+     * Human-readable explanation summary.
+     */
+    explanation: string;
+    /**
+     * Number of rules that fired.
+     */
+    rulesFired: number;
+    /**
+     * Number of rules evaluated (including non-firing).
+     */
+    rulesEvaluated: number;
+    /**
+     * Processing time in milliseconds.
+     */
+    executionTimeMs: number;
+    /**
+     * Timestamp of execution.
+     */
+    timestamp: string;
+    /**
+     * Query a specific conclusion.
+     *
+     * @param factName - Name of the fact to query
+     * @returns Query result with value, confidence, and status
+     */
+    query: (factName: string) => ExpertQueryResult;
+    /**
+     * Format the result as a human-readable string.
+     * Includes the inference chain, conclusions, and statistics.
+     *
+     * @returns Formatted ASCII report
+     *
+     * @example
+     * ```typescript
+     * const result = engine.execute(rules);
+     * console.log(result.toString());
+     * // or simply:
+     * console.log(`${result}`);
+     * ```
+     */
+    toString: () => string;
+};
+/**
+ * Result of querying a specific conclusion.
+ */
+export type ExpertQueryResult = {
+    /** Whether the fact was concluded */
+    exists: boolean;
+    /** The concluded value (if exists) */
+    value: unknown;
+    /** Confidence level of the conclusion */
+    confidence: number;
+    /** How the fact was determined */
+    status: 'concluded' | 'not-concluded' | 'unknown';
+    /** Rule that concluded this fact (if any) */
+    concludedBy?: string;
+};
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/engines/expert/types.js

@@ -0,0 +1,30 @@
+"use strict";
+/**
+ * Expert System Engine Types
+ *
+ * The Expert System engine provides explainable AI - decisions with full audit
+ * trails showing WHY each conclusion was reached. Unlike Forward Chaining which
+ * focuses on actions, the Expert System captures reasoning as a first-class output.
+ *
+ * Key Concepts:
+ * - Goals: What the system tries to conclude (e.g., 'loanDecision')
+ * - Assertions: Facts derived by rules (e.g., { creditTier: 'good' })
+ * - Inference Chain: Step-by-step reasoning trace
+ * - Explanations: Human-readable descriptions per rule
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SEMANTIC_CONFIDENCES = void 0;
+/**
+ * Mapping from semantic labels to numeric confidence values.
+ */
+exports.SEMANTIC_CONFIDENCES = {
+    'certain': 1.0,
+    'very-high': 0.95,
+    'high': 0.85,
+    'likely': 0.75,
+    'moderate': 0.65,
+    'possible': 0.50,
+    'unlikely': 0.35,
+    'low': 0.20
+};
+//# sourceMappingURL=types.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/engines/expert/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG;;;AAgCH;;GAEG;AACU,QAAA,oBAAoB,GAAuC;IACtE,SAAS,EAAE,GAAG;IACd,WAAW,EAAE,IAAI;IACjB,MAAM,EAAE,IAAI;IACZ,QAAQ,EAAE,IAAI;IACd,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,IAAI;IAChB,UAAU,EAAE,IAAI;IAChB,KAAK,EAAE,IAAI;CACZ,CAAC"}

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

@@ -0,0 +1,7 @@
+/**
+ * Forward Chaining Engine Compiler
+ */
+import { ForwardRule, ForwardRuleSet, CompiledForwardRule, CompiledForwardRuleSet } from './types';
+export declare function compileForwardRule(rule: ForwardRule, index?: number): CompiledForwardRule;
+export declare function compileForwardRuleSet(ruleSet: ForwardRuleSet): CompiledForwardRuleSet;
+//# sourceMappingURL=compiler.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"compiler.d.ts","sourceRoot":"","sources":["../../../src/engines/forward/compiler.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH,OAAO,EACL,WAAW,EACX,cAAc,EAEd,mBAAmB,EACnB,sBAAsB,EAMvB,MAAM,SAAS,CAAC;AAgJjB,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,WAAW,EAAE,KAAK,GAAE,MAAU,GAAG,mBAAmB,CAc5F;AAMD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,cAAc,GAAG,sBAAsB,CAerF"}

package/dist/engines/forward/compiler.js

@@ -0,0 +1,160 @@
+"use strict";
+/**
+ * Forward Chaining Engine Compiler
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compileForwardRule = compileForwardRule;
+exports.compileForwardRuleSet = compileForwardRuleSet;
+const core_1 = require("../../core");
+const DEFAULT_MAX_ITERATIONS = 1000;
+// ========================================
+// Helper Functions
+// ========================================
+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, where) {
+    let score = 0;
+    score += inputs.length * 10;
+    score += countConditions(where) * 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)
+    };
+}
+function isPropertyRef(value) {
+    return typeof value === 'string' && value.startsWith('$');
+}
+function isExpression(value) {
+    return Array.isArray(value) && value.length >= 2 && typeof value[0] === 'string';
+}
+// ========================================
+// Action Compilation
+// ========================================
+function compileActionItem(item) {
+    // Set action: compile target paths and value expressions
+    if ('set' in item) {
+        const compiledSets = [];
+        for (const [targetPath, value] of Object.entries(item.set)) {
+            if (!isPropertyRef(targetPath)) {
+                throw new Error(`Set target must be a property reference (e.g., '$person.status'), got: ${targetPath}`);
+            }
+            // Check if value is an expression that needs to be compiled as a condition
+            if (isExpression(value)) {
+                compiledSets.push({
+                    target: (0, core_1.parsePath)(targetPath),
+                    value: { type: 'constant', value: null }, // Placeholder
+                    expr: (0, core_1.compileCondition)(value)
+                });
+            }
+            else {
+                compiledSets.push({
+                    target: (0, core_1.parsePath)(targetPath),
+                    value: (0, core_1.compileOperand)(value)
+                });
+            }
+        }
+        return { set: compiledSets };
+    }
+    // Retract action: extract parameter name from property ref
+    if ('retract' in item) {
+        const ref = item.retract;
+        if (!isPropertyRef(ref)) {
+            throw new Error(`Retract must be a property reference (e.g., '$duplicate'), got: ${ref}`);
+        }
+        // Extract just the parameter name (first part after $)
+        const paramName = ref.slice(1).split('.')[0];
+        return { retract: paramName };
+    }
+    // Call action: pass through unchanged
+    if ('call' in item) {
+        return { call: item.call };
+    }
+    // Halt action: pass through unchanged
+    if ('halt' in item) {
+        return { halt: true };
+    }
+    throw new Error(`Unknown action item type: ${JSON.stringify(item)}`);
+}
+function normalizeThenValue(value) {
+    // String shorthand: 'handlerName' -> [{ call: 'handlerName' }]
+    if (typeof value === 'string') {
+        return [{ call: value }];
+    }
+    // Array: already in correct format
+    if (Array.isArray(value)) {
+        return value;
+    }
+    // Single ActionItem: wrap in array
+    return [value];
+}
+function compileThenAction(thenValue) {
+    const items = normalizeThenValue(thenValue);
+    return {
+        mode: 'forward',
+        actions: items.map(compileActionItem)
+    };
+}
+// ========================================
+// Rule 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;
+}
+function compileForwardRule(rule, index = 0) {
+    const inputs = rule.inputs.map(compileInputParameter);
+    const when = rule.when ? (0, core_1.compileCondition)(rule.when) : undefined;
+    return {
+        id: rule.id,
+        name: rule.name,
+        salience: rule.salience ?? 0,
+        complexity: calculateComplexity(inputs, when),
+        index,
+        inputs,
+        when,
+        action: compileThenAction(rule.then)
+    };
+}
+// ========================================
+// RuleSet Compilation
+// ========================================
+function compileForwardRuleSet(ruleSet) {
+    const config = {
+        mode: 'forward',
+        maxIterations: ruleSet.config?.maxIterations ?? DEFAULT_MAX_ITERATIONS,
+        strategies: ruleSet.config?.strategies ?? core_1.DEFAULT_STRATEGIES
+    };
+    return {
+        id: ruleSet.id,
+        name: ruleSet.name,
+        mode: 'forward',
+        schema: ruleSet.shape ? (0, core_1.normalizeShape)(ruleSet.shape) : { type: 'object' },
+        rules: ruleSet.rules.map((rule, index) => compileForwardRule(rule, index)),
+        config
+    };
+}
+//# sourceMappingURL=compiler.js.map

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

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

package/dist/engines/forward/engine.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Forward Chaining Engine
+ *
+ * Self-contained engine for forward chaining rule execution.
+ * Implements IRuleEngine with strongly-typed ruleset, options, and result.
+ */
+import { IRuleEngine, WorkingMemory, Fact, FactInput, FactChange } from '../../core';
+import { CompiledForwardRuleSet, ForwardOptions, ForwardResult } from './types';
+/**
+ * Forward chaining rule engine.
+ *
+ * Executes rules in a data-driven manner, repeatedly matching rules against
+ * working memory and firing the highest-priority match until no more rules apply.
+ *
+ * @example
+ * ```typescript
+ * const engine = new ForwardEngine();
+ * engine.add({ type: 'Order', data: { amount: 100, status: 'pending' } });
+ *
+ * const result = engine.execute(compiledRules, {
+ *   actions: { processOrder: (ctx, wm) => { ... } }
+ * });
+ * ```
+ *
+ * @example Shared WorkingMemory
+ * ```typescript
+ * const wm = new WorkingMemory();
+ * const engine = new ForwardEngine(wm);
+ * ```
+ */
+export declare class ForwardEngine implements IRuleEngine<CompiledForwardRuleSet, ForwardOptions, ForwardResult> {
+    private wm;
+    private strategy;
+    /**
+     * Create a new ForwardEngine.
+     *
+     * @param workingMemory - Optional shared WorkingMemory. If not provided, creates its own.
+     */
+    constructor(workingMemory?: WorkingMemory);
+    add(input: FactInput): Fact;
+    remove(factId: string): Fact | undefined;
+    update(input: FactInput): Fact;
+    get(factId: string): Fact | undefined;
+    getByType(type: string): Fact[];
+    getAll(): Fact[];
+    has(factId: string): boolean;
+    size(): number;
+    clear(): void;
+    getChanges(): FactChange[];
+    clearChanges(): void;
+    /**
+     * Execute a forward chaining ruleset.
+     *
+     * Rules are matched against working memory iteratively. On each iteration,
+     * the highest-priority matching rule fires, potentially modifying working memory.
+     * Execution continues until no rules match or maxIterations is reached.
+     *
+     * @param ruleSet - Compiled forward ruleset
+     * @param options - Runtime options (actions, callbacks, iteration limit)
+     * @returns Execution result with fired rules and iteration count
+     */
+    execute(ruleSet: CompiledForwardRuleSet, options?: ForwardOptions): ForwardResult;
+    /**
+     * Get the underlying WorkingMemory instance.
+     * Useful for sharing memory between multiple engines.
+     */
+    getWorkingMemory(): WorkingMemory;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/engines/forward/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/engines/forward/engine.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,WAAW,EACX,aAAa,EACb,IAAI,EACJ,SAAS,EACT,UAAU,EACX,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,sBAAsB,EACtB,cAAc,EACd,aAAa,EACd,MAAM,SAAS,CAAC;AAIjB;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,aAAc,YAAW,WAAW,CAAC,sBAAsB,EAAE,cAAc,EAAE,aAAa,CAAC;IACtG,OAAO,CAAC,EAAE,CAAgB;IAC1B,OAAO,CAAC,QAAQ,CAA0B;IAE1C;;;;OAIG;gBACS,aAAa,CAAC,EAAE,aAAa;IASzC,GAAG,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAI3B,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIxC,MAAM,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI;IAI9B,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS;IAIrC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE;IAI/B,MAAM,IAAI,IAAI,EAAE;IAIhB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAI5B,IAAI,IAAI,MAAM;IAId,KAAK,IAAI,IAAI;IAIb,UAAU,IAAI,UAAU,EAAE;IAI1B,YAAY,IAAI,IAAI;IAQpB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,OAAO,EAAE,sBAAsB,EAAE,OAAO,GAAE,cAAmB,GAAG,aAAa;IAQrF;;;OAGG;IACH,gBAAgB,IAAI,aAAa;CAGlC"}