372 lines
14 KiB
TypeScript
372 lines
14 KiB
TypeScript
/**
|
|
* 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
|