claude-flow 3.28.0 → 3.29.0

package/v3/@claude-flow/guidance/dist/uncertainty.d.ts

@@ -0,0 +1,372 @@
+/**
+ * Uncertainty as a First-Class State
+ *
+ * Probabilistic belief tracking with confidence intervals, evidence counts,
+ * and opposing evidence pointers. Uncertainty is preserved, not eliminated.
+ *
+ * Every piece of knowledge in the system carries explicit uncertainty metadata.
+ * Claims can be partial, unresolved, or contested. Confidence propagates
+ * through inference chains and decays over time.
+ *
+ * UncertaintyLedger:
+ * - Asserts beliefs with explicit confidence intervals and evidence
+ * - Recomputes confidence from weighted supporting/opposing evidence
+ * - Propagates uncertainty through inference chains (child bounded by parent)
+ * - Applies time-based decay to all beliefs
+ * - Queries by namespace, status, confidence, and tags
+ * - Traces full inference chains back to root beliefs
+ *
+ * UncertaintyAggregator:
+ * - Computes aggregate confidence across multiple beliefs (geometric mean)
+ * - Worst-case and best-case confidence queries
+ * - Contested and confirmed status checks across belief sets
+ *
+ * @module @claude-flow/guidance/uncertainty
+ */
+/**
+ * Lifecycle status of a belief.
+ *
+ * - confirmed: evidence strongly supports; manually or automatically resolved
+ * - probable: confidence is high but not confirmed
+ * - uncertain: insufficient evidence to decide
+ * - contested: significant opposing evidence exists
+ * - refuted: evidence strongly opposes the claim
+ * - unknown: no evidence has been provided yet
+ */
+export type BeliefStatus = 'confirmed' | 'probable' | 'uncertain' | 'contested' | 'refuted' | 'unknown';
+/**
+ * A bounded confidence estimate with lower, point, and upper values.
+ * All values are in the range [0.0, 1.0].
+ */
+export interface ConfidenceInterval {
+    /** Lower bound of the confidence interval (0.0 - 1.0) */
+    lower: number;
+    /** Best point estimate of confidence (0.0 - 1.0) */
+    point: number;
+    /** Upper bound of the confidence interval (0.0 - 1.0) */
+    upper: number;
+}
+/**
+ * A pointer to a piece of evidence that supports or opposes a belief.
+ */
+export interface EvidencePointer {
+    /** Unique identifier of the evidence source */
+    sourceId: string;
+    /** Classification of the evidence origin */
+    sourceType: 'memory-read' | 'tool-output' | 'truth-anchor' | 'inference' | 'human-input' | 'agent-report';
+    /** true = supporting evidence, false = opposing evidence */
+    supports: boolean;
+    /** Strength of this evidence (0.0 - 1.0) */
+    weight: number;
+    /** Unix timestamp (ms) when this evidence was recorded */
+    timestamp: number;
+}
+/**
+ * A tracked belief with full uncertainty metadata.
+ */
+export interface Belief {
+    /** Unique belief identifier (UUID) */
+    id: string;
+    /** The claim this belief represents */
+    claim: string;
+    /** Namespace for grouping related beliefs */
+    namespace: string;
+    /** Bounded confidence estimate */
+    confidence: ConfidenceInterval;
+    /** Current lifecycle status */
+    status: BeliefStatus;
+    /** Evidence that supports the claim */
+    evidence: EvidencePointer[];
+    /** Evidence that opposes the claim */
+    opposingEvidence: EvidencePointer[];
+    /** Parent belief IDs this belief was inferred from */
+    inferredFrom: string[];
+    /** Unix timestamp (ms) when this belief was first asserted */
+    firstAsserted: number;
+    /** Unix timestamp (ms) of the most recent update */
+    lastUpdated: number;
+    /** Per-belief decay rate (confidence points lost per hour) */
+    decayRate: number;
+    /** Searchable tags */
+    tags: string[];
+}
+/**
+ * Configuration for the UncertaintyLedger.
+ */
+export interface UncertaintyConfig {
+    /** Default point estimate for new beliefs (0.0 - 1.0) */
+    defaultConfidence: number;
+    /** Default confidence decay rate per hour */
+    decayRatePerHour: number;
+    /** Opposing/total evidence ratio threshold to mark a belief contested */
+    contestedThreshold: number;
+    /** Opposing/total evidence ratio threshold to mark a belief refuted */
+    refutedThreshold: number;
+    /** Minimum confidence.point required for an action; below this requires confirmation */
+    minConfidenceForAction: number;
+}
+/**
+ * Query options for filtering beliefs.
+ */
+export interface BeliefQueryOptions {
+    /** Filter by namespace */
+    namespace?: string;
+    /** Filter by status */
+    status?: BeliefStatus;
+    /** Only include beliefs with confidence.point >= this value */
+    minConfidence?: number;
+    /** Only include beliefs that have all specified tags */
+    tags?: string[];
+}
+/**
+ * A node in a confidence inference chain.
+ */
+export interface ConfidenceChainNode {
+    /** The belief at this node */
+    belief: Belief;
+    /** Depth in the inference chain (0 = the queried belief) */
+    depth: number;
+}
+/**
+ * Serializable ledger representation for export/import.
+ */
+export interface SerializedUncertaintyLedger {
+    beliefs: Belief[];
+    createdAt: string;
+    version: number;
+}
+/**
+ * A ledger that tracks beliefs with explicit uncertainty metadata.
+ *
+ * Every belief carries a confidence interval, supporting and opposing evidence,
+ * inference chain links, and time-based decay. The ledger recomputes confidence
+ * from evidence weights and propagates uncertainty through inference chains.
+ */
+export declare class UncertaintyLedger {
+    private readonly config;
+    private readonly beliefs;
+    constructor(config?: Partial<UncertaintyConfig>);
+    /**
+     * Assert a new belief in the ledger.
+     *
+     * Creates a belief with the given claim, namespace, and initial evidence.
+     * If no confidence is provided, the default confidence is used to build
+     * the initial confidence interval.
+     *
+     * @param claim - The claim this belief represents
+     * @param namespace - Namespace for grouping
+     * @param evidence - Initial evidence pointers
+     * @param confidence - Optional explicit confidence interval
+     * @returns The newly created Belief
+     */
+    assert(claim: string, namespace: string, evidence: EvidencePointer[], confidence?: Partial<ConfidenceInterval>): Belief;
+    /**
+     * Add a piece of evidence to an existing belief.
+     *
+     * Appends the evidence to the appropriate list (supporting or opposing),
+     * then recomputes the belief's confidence and status.
+     *
+     * @param beliefId - The belief to update
+     * @param evidence - The new evidence pointer
+     * @returns The updated belief, or undefined if not found
+     */
+    addEvidence(beliefId: string, evidence: EvidencePointer): Belief | undefined;
+    /**
+     * Retrieve a belief by its ID.
+     *
+     * @param id - The belief ID
+     * @returns The belief, or undefined if not found
+     */
+    getBelief(id: string): Belief | undefined;
+    /**
+     * Query beliefs with optional filters.
+     *
+     * All specified filters are ANDed together. Returns beliefs ordered
+     * by lastUpdated descending.
+     *
+     * @param opts - Filter criteria
+     * @returns Matching beliefs
+     */
+    query(opts?: BeliefQueryOptions): Belief[];
+    /**
+     * Get all beliefs with status 'contested'.
+     *
+     * @returns Array of contested beliefs
+     */
+    getContested(): Belief[];
+    /**
+     * Get all beliefs with status 'uncertain' or 'contested'.
+     *
+     * @returns Array of unresolved beliefs
+     */
+    getUnresolved(): Belief[];
+    /**
+     * Recompute the confidence interval for a belief from all evidence.
+     *
+     * The point estimate is a weighted average: total supporting weight minus
+     * total opposing weight, normalized to [0, 1]. The interval bounds are
+     * derived from the spread of evidence weights.
+     *
+     * @param beliefId - The belief to recompute
+     * @returns The updated confidence interval, or undefined if not found
+     */
+    computeConfidence(beliefId: string): ConfidenceInterval | undefined;
+    /**
+     * Propagate uncertainty from a parent belief to a child belief.
+     *
+     * The child's confidence is bounded by the parent's confidence multiplied
+     * by the inference weight. This ensures that downstream beliefs cannot
+     * be more confident than their sources warrant.
+     *
+     * @param parentId - The parent belief ID
+     * @param childId - The child belief ID
+     * @param inferenceWeight - How strongly the parent supports the child (0.0 - 1.0)
+     * @returns The updated child belief, or undefined if either belief is not found
+     */
+    propagateUncertainty(parentId: string, childId: string, inferenceWeight: number): Belief | undefined;
+    /**
+     * Apply time-based decay to all beliefs.
+     *
+     * Each belief's confidence.point is reduced by its decayRate for every
+     * hour elapsed since lastUpdated. The lower and upper bounds shrink
+     * proportionally. Status is updated if confidence drops below thresholds.
+     *
+     * @param currentTime - The reference time for computing elapsed decay (defaults to now)
+     */
+    decayAll(currentTime?: number): void;
+    /**
+     * Manually resolve a belief to a definitive status.
+     *
+     * This overrides the computed status. Typically used for 'confirmed' or
+     * 'refuted' after human review or authoritative evidence.
+     *
+     * @param beliefId - The belief to resolve
+     * @param status - The new status to assign
+     * @param reason - Human-readable reason for the resolution
+     * @returns The updated belief, or undefined if not found
+     */
+    resolve(beliefId: string, status: BeliefStatus, reason: string): Belief | undefined;
+    /**
+     * Check whether a belief's confidence meets the minimum threshold for action.
+     *
+     * @param beliefId - The belief to check
+     * @returns true if confidence.point >= minConfidenceForAction, false otherwise
+     */
+    isActionable(beliefId: string): boolean;
+    /**
+     * Trace the full inference chain from a belief back to its root beliefs.
+     *
+     * Returns an array of { belief, depth } nodes, starting with the queried
+     * belief at depth 0, then its parents at depth 1, their parents at depth 2,
+     * and so on. Handles cycles by tracking visited IDs.
+     *
+     * @param beliefId - The belief whose chain to trace
+     * @returns Array of chain nodes ordered by depth, or empty if not found
+     */
+    getConfidenceChain(beliefId: string): ConfidenceChainNode[];
+    /**
+     * Export all beliefs for persistence.
+     *
+     * @returns Serialized ledger data suitable for JSON.stringify
+     */
+    exportBeliefs(): SerializedUncertaintyLedger;
+    /**
+     * Import previously exported beliefs, replacing all current contents.
+     *
+     * @param data - Serialized ledger data
+     * @throws If the version is unsupported
+     */
+    importBeliefs(data: SerializedUncertaintyLedger): void;
+    /**
+     * Get the number of tracked beliefs.
+     */
+    get size(): number;
+    /**
+     * Get the current configuration.
+     */
+    getConfig(): UncertaintyConfig;
+    /**
+     * Remove all beliefs from the ledger.
+     */
+    clear(): void;
+    /**
+     * Recompute the confidence interval for a belief from its evidence arrays.
+     *
+     * Point estimate is derived from the balance of supporting vs opposing
+     * evidence weights. Bounds reflect the spread of evidence.
+     */
+    private recomputeConfidence;
+    /**
+     * Derive the belief status from its current confidence and evidence ratios.
+     */
+    private deriveStatus;
+}
+/**
+ * Computes aggregate confidence metrics across multiple beliefs.
+ *
+ * Provides geometric mean, worst-case, best-case, and status checks
+ * over sets of beliefs referenced by ID.
+ */
+export declare class UncertaintyAggregator {
+    private readonly ledger;
+    constructor(ledger: UncertaintyLedger);
+    /**
+     * Compute the aggregate confidence across multiple beliefs using
+     * the geometric mean of their point estimates.
+     *
+     * The geometric mean penalizes any single low-confidence belief more
+     * heavily than an arithmetic mean, making it appropriate for combining
+     * independent confidence estimates.
+     *
+     * @param beliefIds - IDs of beliefs to aggregate
+     * @returns Geometric mean of confidence points, or 0 if no valid beliefs
+     */
+    aggregate(beliefIds: string[]): number;
+    /**
+     * Return the lowest confidence point among the specified beliefs.
+     *
+     * @param beliefIds - IDs of beliefs to check
+     * @returns The minimum confidence point, or 0 if no valid beliefs
+     */
+    worstCase(beliefIds: string[]): number;
+    /**
+     * Return the highest confidence point among the specified beliefs.
+     *
+     * @param beliefIds - IDs of beliefs to check
+     * @returns The maximum confidence point, or 0 if no valid beliefs
+     */
+    bestCase(beliefIds: string[]): number;
+    /**
+     * Check if any of the specified beliefs is contested.
+     *
+     * @param beliefIds - IDs of beliefs to check
+     * @returns true if at least one belief has status 'contested'
+     */
+    anyContested(beliefIds: string[]): boolean;
+    /**
+     * Check if all of the specified beliefs are confirmed.
+     *
+     * @param beliefIds - IDs of beliefs to check
+     * @returns true only if every belief exists and has status 'confirmed'
+     */
+    allConfirmed(beliefIds: string[]): boolean;
+    /**
+     * Collect the confidence point estimates for all valid belief IDs.
+     */
+    private collectConfidences;
+}
+/**
+ * Create an UncertaintyLedger with optional configuration.
+ *
+ * @param config - Partial configuration; unspecified values use defaults
+ * @returns A fresh UncertaintyLedger
+ */
+export declare function createUncertaintyLedger(config?: Partial<UncertaintyConfig>): UncertaintyLedger;
+/**
+ * Create an UncertaintyAggregator backed by the given ledger.
+ *
+ * @param ledger - The UncertaintyLedger to aggregate over
+ * @returns A fresh UncertaintyAggregator
+ */
+export declare function createUncertaintyAggregator(ledger: UncertaintyLedger): UncertaintyAggregator;
+//# sourceMappingURL=uncertainty.d.ts.map