@higher.archi/boe 1.0.29 → 1.0.31

package/src/engines/defeasible/types.ts

@@ -36,17 +36,24 @@ import { DecayConfig, DecayInfo } from '../../core/evaluation/decay';
  * - defeasible: Can be defeated by other rules
  * - defeater: Only blocks conclusions, doesn't assert anything
  */
-export type RuleStrength = 'strict' | 'defeasible' | 'defeater';
+export const RuleStrengths = {
+  strict: 'strict',
+  defeasible: 'defeasible',
+  defeater: 'defeater',
+} as const;
+export type RuleStrength = typeof RuleStrengths[keyof typeof RuleStrengths];
 
 /**
  * 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
+export const ConclusionStatuses = {
+  definitely: 'definitely',
+  defeasibly: 'defeasibly',
+  defeated: 'defeated',
+  blocked: 'blocked',
+  undecided: 'undecided',
+} as const;
+export type ConclusionStatus = typeof ConclusionStatuses[keyof typeof ConclusionStatuses];
 
 // ========================================
 // Defeat Strength Types
@@ -55,11 +62,13 @@ export type ConclusionStatus =
 /**
  * Semantic defeat strength labels - human-readable
  */
-export type SemanticDefeatStrength =
-  | 'completely'      // 1.0 - fully defeats
-  | 'strongly'        // 0.85
-  | 'moderately'      // 0.6
-  | 'weakly';         // 0.3
+export const SemanticDefeatStrengths = {
+  completely: 'completely',
+  strongly: 'strongly',
+  moderately: 'moderately',
+  weakly: 'weakly',
+} as const;
+export type SemanticDefeatStrength = typeof SemanticDefeatStrengths[keyof typeof SemanticDefeatStrengths];
 
 /**
  * Semantic strength to numeric mapping
@@ -91,6 +100,12 @@ export type Credibility =
   | 'medium'          // 0.7
   | 'low';            // 0.4
 
+export const SemanticCredibilityLevels = {
+  high: 'high',
+  medium: 'medium',
+  low: 'low',
+} as const;
+
 /**
  * Credibility to numeric mapping
  */
@@ -192,11 +207,20 @@ export type SuperiorityRelation = {
 /**
  * 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
+export const DefeasibleAggregations = {
+  average: 'average',
+  maxMin: 'max-min',
+  weightedSum: 'weighted-sum',
+  probabilistic: 'probabilistic',
+} as const;
+export type AggregationStrategy = typeof DefeasibleAggregations[keyof typeof DefeasibleAggregations];
+
+export const ConflictResolutions = {
+  specificity: 'specificity',
+  priority: 'priority',
+  explicit: 'explicit',
+} as const;
+export type ConflictResolution = typeof ConflictResolutions[keyof typeof ConflictResolutions];
 
 /**
  * Defeasible engine configuration
@@ -222,7 +246,7 @@ export type DefeasibleConfig = {
    * - 'explicit': Only explicit defeats/superiority apply
    * Default: 'specificity'
    */
-  conflictResolution?: 'specificity' | 'priority' | 'explicit';
+  conflictResolution?: ConflictResolution;
 
   /**
    * Maximum iterations for computing defeat cycles (default: 100)

package/src/engines/ensemble/index.ts

@@ -22,6 +22,12 @@ export type {
   EnsembleSummaryOptions
 } from './types';
 
+// Constants
+export {
+  FusionStrategies,
+  AgreementLevels
+} from './types';
+
 // Compiler
 export { compileEnsembleRuleSet } from './compiler';
 

package/src/engines/ensemble/types.ts

@@ -18,13 +18,15 @@ import type { FactInput } from '../../core';
 // Fusion Strategy
 // ========================================
 
-export type FusionStrategy =
-  | 'weighted-average'   // weighted mean of member scores
-  | 'median'             // middle value, robust to outliers
-  | 'min'                // most conservative member score
-  | 'max'                // most optimistic member score
-  | 'voting'             // highest confidence*weight member wins
-  | 'stacking';          // second-layer scoring ruleset over member scores
+export const FusionStrategies = {
+  weightedAverage: 'weighted-average',
+  median: 'median',
+  min: 'min',
+  max: 'max',
+  voting: 'voting',
+  stacking: 'stacking',
+} as const;
+export type FusionStrategy = typeof FusionStrategies[keyof typeof FusionStrategies];
 
 // ========================================
 // Member Definitions (Source)
@@ -123,12 +125,14 @@ export type MemberResult = {
 // ========================================
 
 /** Semantic agreement levels based on coefficient of variation */
-export type AgreementLevel =
-  | 'unanimous'   // agreement = 1.0 (all identical)
-  | 'strong'      // agreement >= 0.90
-  | 'moderate'    // agreement >= 0.70
-  | 'weak'        // agreement >= 0.50
-  | 'divided';    // agreement < 0.50
+export const AgreementLevels = {
+  unanimous: 'unanimous',
+  strong: 'strong',
+  moderate: 'moderate',
+  weak: 'weak',
+  divided: 'divided',
+} as const;
+export type AgreementLevel = typeof AgreementLevels[keyof typeof AgreementLevels];
 
 /** Ensemble result — mirrors ScoringResult shape for downstream compatibility */
 export type EnsembleResult<T extends TierDefinition = TierDefinition> = {

package/src/engines/expert/index.ts

@@ -32,6 +32,7 @@
 // Types
 export {
   // Semantic confidence
+  SemanticConfidences,
   SemanticConfidence,
   SEMANTIC_CONFIDENCES,
   Confidence,

package/src/engines/expert/types.ts

@@ -32,15 +32,17 @@ import {
  * Semantic confidence labels for human-readable rule authoring.
  * Maps to numeric values between 0.0 and 1.0.
  */
-export type SemanticConfidence =
-  | 'certain'     // 1.0 - Absolute certainty (e.g., mathematical facts)
-  | 'very-high'   // 0.95 - Near certain (e.g., well-established patterns)
-  | 'high'        // 0.85 - Strong confidence (e.g., clear evidence)
-  | 'likely'      // 0.75 - Probable (e.g., good indicators)
-  | 'moderate'    // 0.65 - Moderate confidence (e.g., partial evidence)
-  | 'possible'    // 0.50 - Even odds (e.g., uncertain)
-  | 'unlikely'    // 0.35 - Improbable (e.g., weak evidence)
-  | 'low';        // 0.20 - Low confidence (e.g., minimal support)
+export const SemanticConfidences = {
+  certain: 'certain',
+  veryHigh: 'very-high',
+  high: 'high',
+  likely: 'likely',
+  moderate: 'moderate',
+  possible: 'possible',
+  unlikely: 'unlikely',
+  low: 'low',
+} as const;
+export type SemanticConfidence = typeof SemanticConfidences[keyof typeof SemanticConfidences];
 
 /**
  * Mapping from semantic labels to numeric confidence values.

package/src/engines/fuzzy/fuzzy.types.ts

@@ -15,22 +15,48 @@ import { BindingContext } from '../../core';
  * Membership function shapes
  * These define how membership degree (0-1) is calculated from a crisp value
  */
-export type MembershipShape = 'triangle' | 'trapezoid' | 'gaussian' | 'shoulder' | 'block';
+export const MembershipShapes = {
+  triangle: 'triangle',
+  trapezoid: 'trapezoid',
+  gaussian: 'gaussian',
+  shoulder: 'shoulder',
+  block: 'block',
+} as const;
+export type MembershipShape = typeof MembershipShapes[keyof typeof MembershipShapes];
 
 /**
  * Semantic position within domain (compiles to numeric center)
  */
-export type PositionSemantic = 'very-low' | 'low' | 'medium' | 'high' | 'very-high';
+export const PositionSemantics = {
+  veryLow: 'very-low',
+  low: 'low',
+  medium: 'medium',
+  high: 'high',
+  veryHigh: 'very-high',
+} as const;
+export type PositionSemantic = typeof PositionSemantics[keyof typeof PositionSemantics];
 
 /**
  * Semantic width/spread (compiles to numeric spread as % of domain)
  */
-export type WidthSemantic = 'tight' | 'narrow' | 'medium' | 'wide' | 'very-wide';
+export const WidthSemantics = {
+  tight: 'tight',
+  narrow: 'narrow',
+  medium: 'medium',
+  wide: 'wide',
+  veryWide: 'very-wide',
+} as const;
+export type WidthSemantic = typeof WidthSemantics[keyof typeof WidthSemantics];
 
 /**
  * Edge behavior for shoulder/block shapes
  */
-export type EdgeSemantic = 'open-left' | 'open-right' | 'closed';
+export const EdgeSemantics = {
+  openLeft: 'open-left',
+  openRight: 'open-right',
+  closed: 'closed',
+} as const;
+export type EdgeSemantic = typeof EdgeSemantics[keyof typeof EdgeSemantics];
 
 // ========================================
 // Fuzzy Term Definitions
@@ -127,33 +153,39 @@ export type CompiledFuzzyVariable = {
 /**
  * Aggregation methods - combine multiple rule activations for same output
  */
-export type AggregationMethod =
-  | 'max'     // Maximum membership (standard fuzzy OR)
-  | 'sum'     // Sum memberships (can exceed 1)
-  | 'probor'  // Probabilistic OR: a + b - ab
-  | 'bound'   // Bounded sum: min(1, a + b)
-  | 'min';    // Intersection (rare)
+export const AggregationMethods = {
+  max: 'max',
+  sum: 'sum',
+  probor: 'probor',
+  bound: 'bound',
+  min: 'min',
+} as const;
+export type AggregationMethod = typeof AggregationMethods[keyof typeof AggregationMethods];
 
 /**
  * Defuzzification methods - convert fuzzy output to crisp value
  */
-export type DefuzzifyMethod =
-  | 'centroid'  // Center of gravity (most common)
-  | 'bisector'  // Line that divides area in half
-  | 'mom'       // Mean of maximum
-  | 'som'       // Smallest of maximum
-  | 'lom'       // Largest of maximum
-  | 'wtaver';   // Weighted average of term centers
+export const DefuzzifyMethods = {
+  centroid: 'centroid',
+  bisector: 'bisector',
+  mom: 'mom',
+  som: 'som',
+  lom: 'lom',
+  wtaver: 'wtaver',
+} as const;
+export type DefuzzifyMethod = typeof DefuzzifyMethods[keyof typeof DefuzzifyMethods];
 
 /**
  * Transform methods - post-process the crisp output
  */
-export type TransformMethod =
-  | 'clamp'     // Enforce output bounds
-  | 'round'     // Round to integer
-  | 'deadband'  // Zero out small values
-  | 'scale'     // Scale to different range
-  | 'quantize'; // Snap to discrete steps
+export const TransformMethods = {
+  clamp: 'clamp',
+  round: 'round',
+  deadband: 'deadband',
+  scale: 'scale',
+  quantize: 'quantize',
+} as const;
+export type TransformMethod = typeof TransformMethods[keyof typeof TransformMethods];
 
 /**
  * Any defuzzification pipeline stage
@@ -163,14 +195,16 @@ export type DefuzzifyStage = AggregationMethod | DefuzzifyMethod | TransformMeth
 /**
  * Named presets that expand to full pipelines
  */
-export type DefuzzifyPreset =
-  | 'balanced'    // ['max', 'centroid', 'clamp'] - general purpose
-  | 'smooth'      // ['probor', 'centroid', 'clamp'] - gradual transitions
-  | 'decisive'    // ['max', 'mom'] - snappy response
-  | 'cautious'    // ['max', 'som', 'clamp'] - conservative
-  | 'aggressive'  // ['max', 'lom', 'clamp'] - responsive
-  | 'discrete'    // ['max', 'centroid', 'clamp', 'round'] - integer outputs
-  | 'stable';     // ['max', 'centroid', 'deadband', 'clamp'] - reduce chatter
+export const DefuzzifyPresets = {
+  balanced: 'balanced',
+  smooth: 'smooth',
+  decisive: 'decisive',
+  cautious: 'cautious',
+  aggressive: 'aggressive',
+  discrete: 'discrete',
+  stable: 'stable',
+} as const;
+export type DefuzzifyPreset = typeof DefuzzifyPresets[keyof typeof DefuzzifyPresets];
 
 /**
  * Defuzzification pipeline configuration

package/src/engines/loyalty/compiler.ts

@@ -0,0 +1,174 @@
+/**
+ * Loyalty Engine Compiler
+ *
+ * Validates loyalty rulesets and resolves defaults.
+ */
+
+import { CompilationError } from '../../core/errors';
+
+import type {
+  LoyaltyRuleSet,
+  CompiledLoyaltyRuleSet,
+  CompiledEarningRuleSet,
+  CompiledRedemptionRuleSet,
+  CompiledTierEvaluationRuleSet
+} from './types';
+
+/**
+ * Compile and validate a loyalty ruleset.
+ */
+export function compileLoyaltyRuleSet(
+  ruleSet: LoyaltyRuleSet
+): CompiledLoyaltyRuleSet {
+  if (!ruleSet.id) {
+    throw new CompilationError('Loyalty ruleset requires an id');
+  }
+
+  if (ruleSet.mode !== 'loyalty') {
+    throw new CompilationError(`Expected mode 'loyalty', got '${ruleSet.mode}'`);
+  }
+
+  switch (ruleSet.strategy) {
+    case 'earning':
+      return compileEarning(ruleSet);
+    case 'redemption':
+      return compileRedemption(ruleSet);
+    case 'tier-evaluation':
+      return compileTierEvaluation(ruleSet);
+    default:
+      throw new CompilationError(`Unknown loyalty strategy: '${(ruleSet as any).strategy}'`);
+  }
+}
+
+function compileEarning(
+  ruleSet: LoyaltyRuleSet & { strategy: 'earning' }
+): CompiledEarningRuleSet {
+  if (!ruleSet.earningRules || ruleSet.earningRules.length === 0) {
+    throw new CompilationError('Earning strategy requires at least one earning rule');
+  }
+
+  // Validate unique rule IDs
+  const ruleIds = new Set<string>();
+  for (const rule of ruleSet.earningRules) {
+    if (!rule.id) {
+      throw new CompilationError('Each earning rule requires an id');
+    }
+    if (ruleIds.has(rule.id)) {
+      throw new CompilationError(`Duplicate earning rule id: '${rule.id}'`);
+    }
+    if (rule.baseRate < 0) {
+      throw new CompilationError(`Earning rule '${rule.id}' baseRate must be non-negative`);
+    }
+    ruleIds.add(rule.id);
+  }
+
+  // Validate tier IDs are unique
+  validateTierIds(ruleSet.tiers);
+
+  // Validate promotions
+  validatePromotions(ruleSet.promotions);
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'loyalty',
+    strategy: 'earning',
+    earningRules: ruleSet.earningRules,
+    defaultRate: ruleSet.defaultRate ?? 1,
+    tiers: ruleSet.tiers ?? [],
+    expirationPolicy: ruleSet.expirationPolicy ?? {},
+    promotions: ruleSet.promotions ?? []
+  };
+}
+
+function compileRedemption(
+  ruleSet: LoyaltyRuleSet & { strategy: 'redemption' }
+): CompiledRedemptionRuleSet {
+  if (!ruleSet.redemptionOptions || ruleSet.redemptionOptions.length === 0) {
+    throw new CompilationError('Redemption strategy requires at least one redemption option');
+  }
+
+  // Validate unique option IDs
+  const optionIds = new Set<string>();
+  for (const option of ruleSet.redemptionOptions) {
+    if (!option.id) {
+      throw new CompilationError('Each redemption option requires an id');
+    }
+    if (optionIds.has(option.id)) {
+      throw new CompilationError(`Duplicate redemption option id: '${option.id}'`);
+    }
+    if (option.pointsRequired <= 0) {
+      throw new CompilationError(`Redemption option '${option.id}' pointsRequired must be positive`);
+    }
+    optionIds.add(option.id);
+  }
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'loyalty',
+    strategy: 'redemption',
+    redemptionOptions: ruleSet.redemptionOptions,
+    tiers: ruleSet.tiers ?? [],
+    expirationPolicy: ruleSet.expirationPolicy ?? {},
+    promotions: ruleSet.promotions ?? []
+  };
+}
+
+function compileTierEvaluation(
+  ruleSet: LoyaltyRuleSet & { strategy: 'tier-evaluation' }
+): CompiledTierEvaluationRuleSet {
+  if (!ruleSet.tiers || ruleSet.tiers.length === 0) {
+    throw new CompilationError('Tier-evaluation strategy requires at least one tier definition');
+  }
+
+  // Validate tier IDs are unique
+  validateTierIds(ruleSet.tiers);
+
+  // Validate tiers are sorted by threshold ascending
+  for (let i = 1; i < ruleSet.tiers.length; i++) {
+    if (ruleSet.tiers[i].qualifyingThreshold < ruleSet.tiers[i - 1].qualifyingThreshold) {
+      throw new CompilationError(
+        `Tier '${ruleSet.tiers[i].id}' threshold (${ruleSet.tiers[i].qualifyingThreshold}) ` +
+        `is less than previous tier '${ruleSet.tiers[i - 1].id}' (${ruleSet.tiers[i - 1].qualifyingThreshold}). ` +
+        `Tiers must be ordered by ascending threshold.`
+      );
+    }
+  }
+
+  return {
+    id: ruleSet.id,
+    name: ruleSet.name,
+    mode: 'loyalty',
+    strategy: 'tier-evaluation',
+    evaluationPeriod: ruleSet.evaluationPeriod ?? 'rolling-12-months',
+    tiers: ruleSet.tiers,
+    expirationPolicy: ruleSet.expirationPolicy ?? {},
+    promotions: ruleSet.promotions ?? []
+  };
+}
+
+function validateTierIds(tiers?: { id: string }[]): void {
+  if (!tiers) return;
+  const tierIds = new Set<string>();
+  for (const tier of tiers) {
+    if (tierIds.has(tier.id)) {
+      throw new CompilationError(`Duplicate tier id: '${tier.id}'`);
+    }
+    tierIds.add(tier.id);
+  }
+}
+
+function validatePromotions(promotions?: { id: string }[]): void {
+  if (!promotions) return;
+  const promoIds = new Set<string>();
+  for (const promo of promotions) {
+    if (!promo.id) {
+      throw new CompilationError('Each promotion requires an id');
+    }
+    if (promoIds.has(promo.id)) {
+      throw new CompilationError(`Duplicate promotion id: '${promo.id}'`);
+    }
+    promoIds.add(promo.id);
+  }
+}

package/src/engines/loyalty/engine.ts

@@ -0,0 +1,174 @@
+/**
+ * Loyalty Engine
+ *
+ * Point ledger engine that manages earning rules with category multipliers,
+ * point transactions, tier-qualified balances, and promotion stacking.
+ * Unlike other BOE engines, the Loyalty engine maintains a running balance
+ * ledger across operations.
+ *
+ * @example
+ * ```typescript
+ * const engine = new LoyaltyEngine();
+ * const compiled = compileLoyaltyRuleSet({ ... });
+ *
+ * // Stream purchases as they arrive
+ * const r1 = engine.ingest({ memberId: 'M001', amount: 250, category: 'dining' }, compiled);
+ * // r1.pointsEarned: 500, r1.newBalance: 500
+ *
+ * engine.getBalance('M001'); // { currentBalance: 500, ... }
+ * ```
+ */
+
+import {
+  WorkingMemory,
+  Fact,
+  FactInput,
+  FactChange
+} from '../../core';
+
+import type {
+  CompiledLoyaltyRuleSet,
+  CompiledEarningRuleSet,
+  LoyaltyOptions,
+  LoyaltyResult,
+  LoyaltyIngestResult,
+  MemberBalance
+} from './types';
+
+import { LoyaltyExecutor } from './strategy';
+
+export class LoyaltyEngine {
+  private wm: WorkingMemory;
+  private strategy: LoyaltyExecutor;
+  private _ledger: Map<string, MemberBalance> = new Map();
+
+  constructor(workingMemory?: WorkingMemory) {
+    this.wm = workingMemory ?? new WorkingMemory();
+    this.strategy = new LoyaltyExecutor();
+  }
+
+  // ========================================
+  // IWorkingMemory Implementation
+  // ========================================
+
+  add<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
+    return this.wm.add(input);
+  }
+
+  remove(factId: string): Fact | undefined {
+    return this.wm.remove(factId);
+  }
+
+  update<T = Record<string, any>>(input: FactInput<T>): Fact<T> {
+    return this.wm.update(input);
+  }
+
+  get(factId: string): Fact | undefined {
+    return this.wm.get(factId);
+  }
+
+  getByType(type: string): Fact[] {
+    return this.wm.getByType(type);
+  }
+
+  getAll(): Fact[] {
+    return this.wm.getAll();
+  }
+
+  has(factId: string): boolean {
+    return this.wm.has(factId);
+  }
+
+  size(): number {
+    return this.wm.size();
+  }
+
+  clear(): void {
+    this.wm.clear();
+  }
+
+  getChanges(): FactChange[] {
+    return this.wm.getChanges();
+  }
+
+  clearChanges(): void {
+    this.wm.clearChanges();
+  }
+
+  // ========================================
+  // Engine Execution
+  // ========================================
+
+  /**
+   * Execute a loyalty ruleset against all facts in working memory.
+   *
+   * @param ruleSet - Compiled loyalty ruleset
+   * @param options - Runtime options (asOf date)
+   * @returns Loyalty result (earning, redemption, or tier-evaluation)
+   */
+  execute(
+    ruleSet: CompiledLoyaltyRuleSet,
+    options: LoyaltyOptions = {}
+  ): LoyaltyResult {
+    return this.strategy.run(ruleSet, this.wm, this._ledger, options);
+  }
+
+  // ========================================
+  // Streaming Ingest
+  // ========================================
+
+  /**
+   * Process a single purchase/activity event incrementally.
+   *
+   * Each call computes points earned, updates the internal ledger,
+   * evaluates tier status, and returns the result with the new balance.
+   * Only works with earning strategy rulesets.
+   *
+   * @param eventData - Event data with memberId, amount, and optional category
+   * @param ruleSet - Compiled earning ruleset
+   * @param asOf - Reference time (default: now)
+   * @returns Earning result with updated balance
+   */
+  ingest(
+    eventData: Record<string, any>,
+    ruleSet: CompiledEarningRuleSet,
+    asOf: Date = new Date()
+  ): LoyaltyIngestResult {
+    return this.strategy.earnSingle(eventData, ruleSet, this._ledger, asOf);
+  }
+
+  // ========================================
+  // Ledger Operations
+  // ========================================
+
+  /**
+   * Get the current balance for a member.
+   * Returns undefined if the member has no transactions.
+   */
+  getBalance(memberId: string): MemberBalance | undefined {
+    return this._ledger.get(memberId);
+  }
+
+  /**
+   * Get the full ledger state (all member balances).
+   */
+  getLedger(): Map<string, MemberBalance> {
+    return new Map(this._ledger);
+  }
+
+  /**
+   * Reset the ledger, clearing all member balances.
+   * Does not affect working memory.
+   */
+  resetLedger(): void {
+    this._ledger.clear();
+  }
+
+  // ========================================
+  // Utility Methods
+  // ========================================
+
+  getWorkingMemory(): WorkingMemory {
+    return this.wm;
+  }
+}