agentic-qe 3.2.2 → 3.3.0

package/v3/dist/strange-loop/belief-reconciler.d.ts

@@ -0,0 +1,357 @@
+/**
+ * Belief Reconciler
+ * ADR-052: Strange Loop Belief Reconciliation Protocol
+ *
+ * Handles contradictory beliefs detected by the CoherenceService.
+ * When the sheaf Laplacian energy indicates high incoherence,
+ * this module identifies conflicting beliefs, determines the optimal
+ * resolution strategy, applies reconciliation, and creates audit records.
+ *
+ * The reconciliation process follows this pattern:
+ * ```
+ *    Detect Contradiction
+ *           |
+ *           v
+ *    Select Strategy -----> latest | authority | consensus | merge | escalate
+ *           |
+ *           v
+ *    Apply Resolution
+ *           |
+ *           v
+ *    Create Witness Record
+ * ```
+ *
+ * @module strange-loop/belief-reconciler
+ */
+import type { Contradiction, Belief, WitnessRecord } from '../integrations/coherence/types.js';
+/**
+ * Strategy for reconciling conflicting beliefs
+ *
+ * | Strategy | Description | Use Case |
+ * |----------|-------------|----------|
+ * | latest | Prefer most recent observation | Temporal data, state updates |
+ * | authority | Prefer higher-confidence agent | Expert systems, hierarchical |
+ * | consensus | Query all agents for votes | Democratic decisions |
+ * | merge | Attempt to merge compatible beliefs | Complementary partial views |
+ * | escalate | Defer to Queen coordinator | Critical/ambiguous conflicts |
+ */
+export type ReconciliationStrategy = 'latest' | 'authority' | 'consensus' | 'merge' | 'escalate';
+/**
+ * Result of a reconciliation attempt
+ */
+export interface ReconciliationResult {
+    /** Whether reconciliation succeeded */
+    success: boolean;
+    /** Strategy that was applied */
+    strategy: ReconciliationStrategy;
+    /** Contradictions that were successfully resolved */
+    resolvedContradictions: Contradiction[];
+    /** Contradictions that could not be resolved */
+    unresolvedContradictions: Contradiction[];
+    /** New beliefs created as a result of reconciliation */
+    newBeliefs: Belief[];
+    /** Witness record ID for audit trail (if witness adapter available) */
+    witnessId?: string;
+    /** Duration of reconciliation in milliseconds */
+    durationMs: number;
+}
+/**
+ * Record of a reconciliation for history tracking
+ */
+export interface ReconciliationRecord {
+    /** Unique identifier for this record */
+    id: string;
+    /** Contradictions that were processed */
+    contradictions: Contradiction[];
+    /** Result of the reconciliation */
+    result: ReconciliationResult;
+    /** Timestamp when reconciliation occurred */
+    timestamp: number;
+}
+/**
+ * A vote from an agent on which belief to accept
+ */
+export interface BeliefVote {
+    /** Agent ID casting the vote */
+    agentId: string;
+    /** Belief ID being voted for */
+    beliefId: string;
+    /** Confidence in this vote (0-1) */
+    confidence: number;
+    /** Optional reasoning */
+    reasoning?: string;
+}
+/**
+ * Configuration for the belief reconciler
+ */
+export interface BeliefReconcilerConfig {
+    /** Default reconciliation strategy */
+    defaultStrategy: ReconciliationStrategy;
+    /** Minimum confidence threshold for authority strategy (0-1) */
+    authorityThreshold: number;
+    /** Minimum consensus percentage required (0-1) */
+    consensusThreshold: number;
+    /** Maximum time to wait for consensus votes in milliseconds */
+    consensusTimeoutMs: number;
+    /** Whether to create witness records for audit trail */
+    enableWitness: boolean;
+    /** Maximum reconciliation history to retain */
+    maxHistorySize: number;
+    /** Similarity threshold for merge strategy (0-1) */
+    mergeSimilarityThreshold: number;
+    /** Whether to auto-escalate on repeated failures */
+    autoEscalateOnFailure: boolean;
+    /** Number of failures before auto-escalation */
+    failuresBeforeEscalate: number;
+}
+/**
+ * Default configuration for belief reconciler
+ */
+export declare const DEFAULT_BELIEF_RECONCILER_CONFIG: BeliefReconcilerConfig;
+/**
+ * Interface for belief reconciler operations
+ */
+export interface IBeliefReconciler {
+    /**
+     * Reconcile a set of contradictions
+     * @param contradictions - Detected contradictions to resolve
+     * @returns Result of the reconciliation attempt
+     */
+    reconcile(contradictions: Contradiction[]): Promise<ReconciliationResult>;
+    /**
+     * Get the current reconciliation strategy
+     */
+    getStrategy(): ReconciliationStrategy;
+    /**
+     * Set the reconciliation strategy
+     * @param strategy - New strategy to use
+     */
+    setStrategy(strategy: ReconciliationStrategy): void;
+    /**
+     * Get reconciliation history
+     */
+    getHistory(): ReconciliationRecord[];
+}
+/**
+ * Interface for collecting consensus votes from agents
+ */
+export interface IVoteCollector {
+    /**
+     * Collect votes from agents on which belief to accept
+     * @param beliefs - Conflicting beliefs to vote on
+     * @param timeoutMs - Maximum time to wait for votes
+     */
+    collectVotes(beliefs: Belief[], timeoutMs: number): Promise<BeliefVote[]>;
+}
+/**
+ * Interface for creating witness records
+ */
+export interface IWitnessAdapter {
+    /**
+     * Create a witness record for a reconciliation
+     * @param data - Data to witness
+     */
+    createWitness(data: unknown): Promise<WitnessRecord>;
+}
+/**
+ * Event types emitted by the belief reconciler
+ */
+export type BeliefReconcilerEventType = 'belief_reconciliation_started' | 'belief_reconciled' | 'belief_reconciliation_failed' | 'strategy_changed' | 'escalation_requested';
+/**
+ * Event payload for belief reconciler events
+ */
+export interface BeliefReconcilerEvent {
+    /** Event type */
+    type: BeliefReconcilerEventType;
+    /** Timestamp of event */
+    timestamp: number;
+    /** Event data */
+    data: unknown;
+}
+/**
+ * Event listener callback type
+ */
+export type BeliefReconcilerEventListener = (event: BeliefReconcilerEvent) => void;
+/**
+ * Reconciles contradictory beliefs in the swarm
+ *
+ * @example
+ * ```typescript
+ * const reconciler = createBeliefReconciler({
+ *   defaultStrategy: 'authority',
+ *   authorityThreshold: 0.8
+ * });
+ *
+ * const result = await reconciler.reconcile(contradictions);
+ * if (result.success) {
+ *   // Apply new beliefs
+ *   for (const belief of result.newBeliefs) {
+ *     await beliefStore.add(belief);
+ *   }
+ * }
+ * ```
+ */
+export declare class BeliefReconciler implements IBeliefReconciler {
+    private config;
+    private strategy;
+    private history;
+    private eventListeners;
+    private voteCollector;
+    private witnessAdapter;
+    private consecutiveFailures;
+    /** Belief store for looking up beliefs by ID */
+    private beliefStore;
+    constructor(config?: Partial<BeliefReconcilerConfig>, options?: {
+        voteCollector?: IVoteCollector;
+        witnessAdapter?: IWitnessAdapter;
+    });
+    /**
+     * Register a belief for lookup during reconciliation
+     */
+    registerBelief(belief: Belief): void;
+    /**
+     * Register multiple beliefs
+     */
+    registerBeliefs(beliefs: Belief[]): void;
+    /**
+     * Clear all registered beliefs
+     */
+    clearBeliefs(): void;
+    /**
+     * Reconcile contradictions using the configured strategy
+     */
+    reconcile(contradictions: Contradiction[]): Promise<ReconciliationResult>;
+    /**
+     * Get the current reconciliation strategy
+     */
+    getStrategy(): ReconciliationStrategy;
+    /**
+     * Set the reconciliation strategy
+     */
+    setStrategy(strategy: ReconciliationStrategy): void;
+    /**
+     * Get reconciliation history
+     */
+    getHistory(): ReconciliationRecord[];
+    /**
+     * Clear reconciliation history
+     */
+    clearHistory(): void;
+    /**
+     * Get reconciliation statistics
+     */
+    getStats(): {
+        totalReconciliations: number;
+        successfulReconciliations: number;
+        failedReconciliations: number;
+        totalContradictionsResolved: number;
+        avgDurationMs: number;
+        strategyDistribution: Record<ReconciliationStrategy, number>;
+    };
+    /**
+     * Add event listener
+     */
+    on(event: BeliefReconcilerEventType, listener: BeliefReconcilerEventListener): void;
+    /**
+     * Remove event listener
+     */
+    off(event: BeliefReconcilerEventType, listener: BeliefReconcilerEventListener): void;
+    /**
+     * Reconcile by preferring the most recent belief
+     */
+    private reconcileByLatest;
+    /**
+     * Reconcile by preferring higher-confidence beliefs
+     */
+    private reconcileByAuthority;
+    /**
+     * Reconcile by collecting votes from agents
+     */
+    private reconcileByConsensus;
+    /**
+     * Reconcile by attempting to merge compatible beliefs
+     *
+     * Uses category theory principles to find a compatible merge:
+     * - If beliefs are about different aspects of the same entity, merge them
+     * - If beliefs can be generalized to a higher-level belief, do so
+     * - If beliefs represent partial views, combine them
+     */
+    private reconcileByMerge;
+    /**
+     * Escalate contradictions to the Queen coordinator
+     */
+    private reconcileByEscalation;
+    /**
+     * Get the beliefs involved in a contradiction
+     */
+    private getConflictingBeliefs;
+    /**
+     * Create a new belief from reconciliation
+     */
+    private createReconciledBelief;
+    /**
+     * Compute confidence for a reconciled belief
+     */
+    private computeReconciledConfidence;
+    /**
+     * Compute cosine similarity between two embeddings
+     */
+    private computeEmbeddingSimilarity;
+    /**
+     * Merge two beliefs using category theory principles
+     *
+     * This implements a simplified pullback construction:
+     * - Find the common "generalization" of both beliefs
+     * - Create a new belief that captures both perspectives
+     */
+    private mergeBeliefsCategorial;
+    /**
+     * Merge two statements into a combined statement
+     */
+    private mergeStatements;
+    /**
+     * Check if auto-escalation should be triggered
+     */
+    private shouldAutoEscalate;
+    /**
+     * Add a reconciliation to history
+     */
+    private addToHistory;
+    /**
+     * Emit an event to listeners
+     */
+    private emit;
+}
+/**
+ * Create a belief reconciler with optional configuration
+ *
+ * @param config - Partial configuration to override defaults
+ * @param options - Optional dependencies (vote collector, witness adapter)
+ * @returns Configured BeliefReconciler instance
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const reconciler = createBeliefReconciler();
+ *
+ * // With custom configuration
+ * const reconciler = createBeliefReconciler({
+ *   defaultStrategy: 'consensus',
+ *   consensusThreshold: 0.7
+ * });
+ *
+ * // With dependencies
+ * const reconciler = createBeliefReconciler(
+ *   { enableWitness: true },
+ *   {
+ *     voteCollector: myVoteCollector,
+ *     witnessAdapter: myWitnessAdapter
+ *   }
+ * );
+ * ```
+ */
+export declare function createBeliefReconciler(config?: Partial<BeliefReconcilerConfig>, options?: {
+    voteCollector?: IVoteCollector;
+    witnessAdapter?: IWitnessAdapter;
+}): BeliefReconciler;
+//# sourceMappingURL=belief-reconciler.d.ts.map

package/v3/dist/strange-loop/belief-reconciler.d.ts.map

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