@higher.archi/boe 1.0.0

package/src/engines/defeasible/types.ts

@@ -0,0 +1,409 @@
+/**
+ * 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 Types
+// ========================================
+
+/**
+ * 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'      // Proven by strict rule (cannot be defeated)
+  | 'defeasibly'      // Proven by defeasible rule (not currently defeated)
+  | 'defeated'        // Was concluded but defeated by another rule
+  | 'blocked'         // Blocked by a defeater
+  | 'undecided';      // No applicable rules
+
+// ========================================
+// Defeat Strength Types
+// ========================================
+
+/**
+ * Semantic defeat strength labels - human-readable
+ */
+export type SemanticDefeatStrength =
+  | 'completely'      // 1.0 - fully defeats
+  | 'strongly'        // 0.85
+  | 'moderately'      // 0.6
+  | 'weakly';         // 0.3
+
+/**
+ * Semantic strength to numeric mapping
+ */
+export const SEMANTIC_DEFEAT_STRENGTHS: Record<SemanticDefeatStrength, number> = {
+  'completely': 1.0,
+  'strongly': 0.85,
+  'moderately': 0.6,
+  'weakly': 0.3
+};
+
+/**
+ * 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            // 0-1
+  | 'high'            // 0.9
+  | 'medium'          // 0.7
+  | 'low';            // 0.4
+
+/**
+ * Credibility to numeric mapping
+ */
+export const SEMANTIC_CREDIBILITIES: Record<string, number> = {
+  'high': 0.9,
+  'medium': 0.7,
+  'low': 0.4
+};
+
+// ========================================
+// Source Types (User-Defined)
+// ========================================
+
+/**
+ * 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;  // Rule ID that wins
+  inferior: string;  // Rule ID that loses
+};
+
+/**
+ * Aggregation strategy for confidence calculation
+ */
+export type AggregationStrategy =
+  | 'average'         // Mean of supporters vs mean of attackers
+  | 'max-min'         // Strongest support vs strongest attack
+  | 'weighted-sum'    // Sum with normalization to 0-1
+  | 'probabilistic';  // Independent probability combination
+
+/**
+ * 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 Types
+// ========================================
+
+/**
+ * Compiled conclusion
+ */
+export type CompiledConclusion = {
+  literal: string;      // The conclusion name
+  positive: boolean;    // true = asserts, false = negates
+};
+
+/**
+ * Compiled defeat with normalized strength
+ */
+export type CompiledDefeat = {
+  rule: string;         // Target rule ID
+  strength: number;     // 0-1 defeat strength
+};
+
+/**
+ * Compiled defeasible rule
+ */
+export type CompiledDefeasibleRule = CompiledBaseRule & {
+  strength: RuleStrength;
+  credibility: number;                    // Normalized to 0-1
+  conclusion: CompiledConclusion | null;  // null for pure defeaters
+  defeats: CompiledDefeat[];              // Normalized defeats
+  specificity: number;                    // Number of conditions (for tie-breaking)
+};
+
+/**
+ * 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>;
+};
+
+// ========================================
+// Runtime Types
+// ========================================
+
+/**
+ * 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;                 // Binary: does it hold?
+  confidence: number;             // Weighted: 0-1 confidence score
+  status: ConclusionStatus;
+  supportingRules: string[];      // Rules that support this
+  defeatedBy: string[];           // Rules that defeated this
+  bindings: BindingContext;       // First supporting binding
+};
+
+/**
+ * Conflict between rules
+ */
+export type Conflict = {
+  conclusion: string;
+  positiveRules: string[];   // Rules concluding the positive
+  negativeRules: string[];   // Rules concluding the negative
+  winner: 'positive' | 'negative' | 'undecided';
+  reason: string;            // Why this resolution was chosen
+};
+
+/**
+ * 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;              // Does this conclusion hold?
+  confidence: number;          // 0-1 confidence score
+  status: ConclusionStatus;
+  supportedBy: string[];       // Rules supporting this
+  defeatedBy: string[];        // Rules that defeated it
+};