claude-flow 3.28.0 → 3.29.0

package/v3/@claude-flow/guidance/dist/uncertainty.js

@@ -0,0 +1,619 @@
+/**
+ * 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
+ */
+import { randomUUID } from 'node:crypto';
+// ============================================================================
+// Default Configuration
+// ============================================================================
+const DEFAULT_UNCERTAINTY_CONFIG = {
+    defaultConfidence: 0.7,
+    decayRatePerHour: 0.01,
+    contestedThreshold: 0.3,
+    refutedThreshold: 0.7,
+    minConfidenceForAction: 0.3,
+};
+const SERIALIZATION_VERSION = 1;
+// ============================================================================
+// UncertaintyLedger
+// ============================================================================
+/**
+ * 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 class UncertaintyLedger {
+    config;
+    beliefs = new Map();
+    constructor(config = {}) {
+        this.config = { ...DEFAULT_UNCERTAINTY_CONFIG, ...config };
+    }
+    /**
+     * 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, namespace, evidence, confidence) {
+        const now = Date.now();
+        const point = confidence?.point ?? this.config.defaultConfidence;
+        const lower = confidence?.lower ?? clamp(point - 0.1, 0, 1);
+        const upper = confidence?.upper ?? clamp(point + 0.1, 0, 1);
+        const supporting = evidence.filter(e => e.supports);
+        const opposing = evidence.filter(e => !e.supports);
+        const belief = {
+            id: randomUUID(),
+            claim,
+            namespace,
+            confidence: {
+                lower: clamp(lower, 0, 1),
+                point: clamp(point, 0, 1),
+                upper: clamp(upper, 0, 1),
+            },
+            status: 'unknown',
+            evidence: supporting,
+            opposingEvidence: opposing,
+            inferredFrom: [],
+            firstAsserted: now,
+            lastUpdated: now,
+            decayRate: this.config.decayRatePerHour,
+            tags: [],
+        };
+        // Compute initial status from evidence
+        belief.status = this.deriveStatus(belief);
+        this.beliefs.set(belief.id, belief);
+        return 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, evidence) {
+        const belief = this.beliefs.get(beliefId);
+        if (!belief)
+            return undefined;
+        if (evidence.supports) {
+            belief.evidence.push(evidence);
+        }
+        else {
+            belief.opposingEvidence.push(evidence);
+        }
+        this.recomputeConfidence(belief);
+        belief.status = this.deriveStatus(belief);
+        belief.lastUpdated = Date.now();
+        return belief;
+    }
+    /**
+     * Retrieve a belief by its ID.
+     *
+     * @param id - The belief ID
+     * @returns The belief, or undefined if not found
+     */
+    getBelief(id) {
+        return this.beliefs.get(id);
+    }
+    /**
+     * 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 = {}) {
+        const results = [];
+        for (const belief of this.beliefs.values()) {
+            if (opts.namespace !== undefined && belief.namespace !== opts.namespace) {
+                continue;
+            }
+            if (opts.status !== undefined && belief.status !== opts.status) {
+                continue;
+            }
+            if (opts.minConfidence !== undefined && belief.confidence.point < opts.minConfidence) {
+                continue;
+            }
+            if (opts.tags !== undefined && opts.tags.length > 0) {
+                const beliefTags = new Set(belief.tags);
+                if (!opts.tags.every(t => beliefTags.has(t))) {
+                    continue;
+                }
+            }
+            results.push(belief);
+        }
+        return results.sort((a, b) => b.lastUpdated - a.lastUpdated);
+    }
+    /**
+     * Get all beliefs with status 'contested'.
+     *
+     * @returns Array of contested beliefs
+     */
+    getContested() {
+        return this.query({ status: 'contested' });
+    }
+    /**
+     * Get all beliefs with status 'uncertain' or 'contested'.
+     *
+     * @returns Array of unresolved beliefs
+     */
+    getUnresolved() {
+        const results = [];
+        for (const belief of this.beliefs.values()) {
+            if (belief.status === 'uncertain' || belief.status === 'contested') {
+                results.push(belief);
+            }
+        }
+        return results.sort((a, b) => b.lastUpdated - a.lastUpdated);
+    }
+    /**
+     * 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) {
+        const belief = this.beliefs.get(beliefId);
+        if (!belief)
+            return undefined;
+        this.recomputeConfidence(belief);
+        belief.status = this.deriveStatus(belief);
+        belief.lastUpdated = Date.now();
+        return { ...belief.confidence };
+    }
+    /**
+     * 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, childId, inferenceWeight) {
+        const parent = this.beliefs.get(parentId);
+        const child = this.beliefs.get(childId);
+        if (!parent || !child)
+            return undefined;
+        const weight = clamp(inferenceWeight, 0, 1);
+        // Record the inference relationship
+        if (!child.inferredFrom.includes(parentId)) {
+            child.inferredFrom.push(parentId);
+        }
+        // Bound child confidence by parent * weight
+        const maxPoint = parent.confidence.point * weight;
+        const maxUpper = parent.confidence.upper * weight;
+        const maxLower = parent.confidence.lower * weight;
+        child.confidence.point = Math.min(child.confidence.point, maxPoint);
+        child.confidence.upper = Math.min(child.confidence.upper, maxUpper);
+        child.confidence.lower = Math.min(child.confidence.lower, maxLower);
+        // Ensure ordering invariant: lower <= point <= upper
+        child.confidence.lower = Math.min(child.confidence.lower, child.confidence.point);
+        child.confidence.upper = Math.max(child.confidence.upper, child.confidence.point);
+        child.status = this.deriveStatus(child);
+        child.lastUpdated = Date.now();
+        return child;
+    }
+    /**
+     * 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) {
+        const now = currentTime ?? Date.now();
+        for (const belief of this.beliefs.values()) {
+            const elapsedMs = now - belief.lastUpdated;
+            if (elapsedMs <= 0)
+                continue;
+            const elapsedHours = elapsedMs / 3_600_000;
+            const decay = belief.decayRate * elapsedHours;
+            if (decay <= 0)
+                continue;
+            // Apply decay to point estimate
+            belief.confidence.point = clamp(belief.confidence.point - decay, 0, 1);
+            // Shrink bounds proportionally
+            belief.confidence.lower = clamp(belief.confidence.lower - decay, 0, belief.confidence.point);
+            belief.confidence.upper = clamp(belief.confidence.upper - decay * 0.5, belief.confidence.point, 1);
+            belief.status = this.deriveStatus(belief);
+            belief.lastUpdated = now;
+        }
+    }
+    /**
+     * 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, status, reason) {
+        const belief = this.beliefs.get(beliefId);
+        if (!belief)
+            return undefined;
+        belief.status = status;
+        belief.lastUpdated = Date.now();
+        // When confirming, set confidence to high; when refuting, set to low
+        if (status === 'confirmed') {
+            belief.confidence.point = clamp(Math.max(belief.confidence.point, 0.95), 0, 1);
+            belief.confidence.upper = 1.0;
+            belief.confidence.lower = clamp(Math.max(belief.confidence.lower, 0.9), 0, 1);
+        }
+        else if (status === 'refuted') {
+            belief.confidence.point = clamp(Math.min(belief.confidence.point, 0.05), 0, 1);
+            belief.confidence.lower = 0.0;
+            belief.confidence.upper = clamp(Math.min(belief.confidence.upper, 0.1), 0, 1);
+        }
+        // Record the resolution as evidence
+        const resolutionEvidence = {
+            sourceId: `resolution:${beliefId}:${Date.now()}`,
+            sourceType: 'human-input',
+            supports: status === 'confirmed',
+            weight: 1.0,
+            timestamp: Date.now(),
+        };
+        if (resolutionEvidence.supports) {
+            belief.evidence.push(resolutionEvidence);
+        }
+        else {
+            belief.opposingEvidence.push(resolutionEvidence);
+        }
+        // Store reason in the evidence sourceId for traceability
+        // (reason is captured via the resolution evidence pattern)
+        return belief;
+    }
+    /**
+     * 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) {
+        const belief = this.beliefs.get(beliefId);
+        if (!belief)
+            return false;
+        return belief.confidence.point >= this.config.minConfidenceForAction;
+    }
+    /**
+     * 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) {
+        const root = this.beliefs.get(beliefId);
+        if (!root)
+            return [];
+        const result = [];
+        const visited = new Set();
+        const traverse = (id, depth) => {
+            if (visited.has(id))
+                return;
+            visited.add(id);
+            const belief = this.beliefs.get(id);
+            if (!belief)
+                return;
+            result.push({ belief, depth });
+            for (const parentId of belief.inferredFrom) {
+                traverse(parentId, depth + 1);
+            }
+        };
+        traverse(beliefId, 0);
+        return result.sort((a, b) => a.depth - b.depth);
+    }
+    /**
+     * Export all beliefs for persistence.
+     *
+     * @returns Serialized ledger data suitable for JSON.stringify
+     */
+    exportBeliefs() {
+        return {
+            beliefs: Array.from(this.beliefs.values()).map(b => ({ ...b })),
+            createdAt: new Date().toISOString(),
+            version: SERIALIZATION_VERSION,
+        };
+    }
+    /**
+     * Import previously exported beliefs, replacing all current contents.
+     *
+     * @param data - Serialized ledger data
+     * @throws If the version is unsupported
+     */
+    importBeliefs(data) {
+        if (data.version !== SERIALIZATION_VERSION) {
+            throw new Error(`Unsupported uncertainty ledger version: ${data.version} (expected ${SERIALIZATION_VERSION})`);
+        }
+        this.beliefs.clear();
+        for (const belief of data.beliefs) {
+            this.beliefs.set(belief.id, { ...belief });
+        }
+    }
+    /**
+     * Get the number of tracked beliefs.
+     */
+    get size() {
+        return this.beliefs.size;
+    }
+    /**
+     * Get the current configuration.
+     */
+    getConfig() {
+        return { ...this.config };
+    }
+    /**
+     * Remove all beliefs from the ledger.
+     */
+    clear() {
+        this.beliefs.clear();
+    }
+    // ===== Private =====
+    /**
+     * 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.
+     */
+    recomputeConfidence(belief) {
+        const allEvidence = [...belief.evidence, ...belief.opposingEvidence];
+        if (allEvidence.length === 0) {
+            // No evidence: keep current confidence (from assertion)
+            return;
+        }
+        let supportingWeight = 0;
+        let opposingWeight = 0;
+        for (const e of belief.evidence) {
+            supportingWeight += e.weight;
+        }
+        for (const e of belief.opposingEvidence) {
+            opposingWeight += e.weight;
+        }
+        const totalWeight = supportingWeight + opposingWeight;
+        if (totalWeight === 0) {
+            // All evidence has zero weight: no update
+            return;
+        }
+        // Point estimate: proportion of supporting weight
+        const point = supportingWeight / totalWeight;
+        // Compute spread from evidence count (more evidence = tighter interval)
+        const evidenceCount = allEvidence.length;
+        const spread = Math.max(0.02, 0.3 / Math.sqrt(evidenceCount));
+        belief.confidence = {
+            lower: clamp(point - spread, 0, 1),
+            point: clamp(point, 0, 1),
+            upper: clamp(point + spread, 0, 1),
+        };
+    }
+    /**
+     * Derive the belief status from its current confidence and evidence ratios.
+     */
+    deriveStatus(belief) {
+        const allEvidence = [...belief.evidence, ...belief.opposingEvidence];
+        if (allEvidence.length === 0) {
+            return 'unknown';
+        }
+        // If already manually resolved to confirmed or refuted, preserve it
+        if (belief.status === 'confirmed' || belief.status === 'refuted') {
+            // Only preserve if there's resolution evidence (weight 1.0 human-input)
+            const hasResolution = allEvidence.some(e => e.sourceType === 'human-input' && e.weight === 1.0);
+            if (hasResolution)
+                return belief.status;
+        }
+        let supportingWeight = 0;
+        let opposingWeight = 0;
+        for (const e of belief.evidence) {
+            supportingWeight += e.weight;
+        }
+        for (const e of belief.opposingEvidence) {
+            opposingWeight += e.weight;
+        }
+        const totalWeight = supportingWeight + opposingWeight;
+        if (totalWeight === 0) {
+            return 'unknown';
+        }
+        const opposingRatio = opposingWeight / totalWeight;
+        // Check thresholds from most severe to least
+        if (opposingRatio >= this.config.refutedThreshold) {
+            return 'refuted';
+        }
+        if (opposingRatio >= this.config.contestedThreshold) {
+            return 'contested';
+        }
+        // Not contested; determine from confidence level
+        if (belief.confidence.point >= 0.8) {
+            return 'probable';
+        }
+        if (belief.confidence.point >= 0.5) {
+            return 'uncertain';
+        }
+        return 'uncertain';
+    }
+}
+// ============================================================================
+// UncertaintyAggregator
+// ============================================================================
+/**
+ * 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 class UncertaintyAggregator {
+    ledger;
+    constructor(ledger) {
+        this.ledger = ledger;
+    }
+    /**
+     * 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) {
+        const confidences = this.collectConfidences(beliefIds);
+        if (confidences.length === 0)
+            return 0;
+        // Geometric mean via log-space to avoid underflow
+        const logSum = confidences.reduce((sum, c) => {
+            // Protect against log(0)
+            const safe = Math.max(c, 1e-10);
+            return sum + Math.log(safe);
+        }, 0);
+        return Math.exp(logSum / confidences.length);
+    }
+    /**
+     * 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) {
+        const confidences = this.collectConfidences(beliefIds);
+        if (confidences.length === 0)
+            return 0;
+        return Math.min(...confidences);
+    }
+    /**
+     * 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) {
+        const confidences = this.collectConfidences(beliefIds);
+        if (confidences.length === 0)
+            return 0;
+        return Math.max(...confidences);
+    }
+    /**
+     * 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) {
+        for (const id of beliefIds) {
+            const belief = this.ledger.getBelief(id);
+            if (belief && belief.status === 'contested')
+                return true;
+        }
+        return false;
+    }
+    /**
+     * 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) {
+        if (beliefIds.length === 0)
+            return false;
+        for (const id of beliefIds) {
+            const belief = this.ledger.getBelief(id);
+            if (!belief || belief.status !== 'confirmed')
+                return false;
+        }
+        return true;
+    }
+    // ===== Private =====
+    /**
+     * Collect the confidence point estimates for all valid belief IDs.
+     */
+    collectConfidences(beliefIds) {
+        const confidences = [];
+        for (const id of beliefIds) {
+            const belief = this.ledger.getBelief(id);
+            if (belief) {
+                confidences.push(belief.confidence.point);
+            }
+        }
+        return confidences;
+    }
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Create an UncertaintyLedger with optional configuration.
+ *
+ * @param config - Partial configuration; unspecified values use defaults
+ * @returns A fresh UncertaintyLedger
+ */
+export function createUncertaintyLedger(config) {
+    return new UncertaintyLedger(config);
+}
+/**
+ * Create an UncertaintyAggregator backed by the given ledger.
+ *
+ * @param ledger - The UncertaintyLedger to aggregate over
+ * @returns A fresh UncertaintyAggregator
+ */
+export function createUncertaintyAggregator(ledger) {
+    return new UncertaintyAggregator(ledger);
+}
+// ============================================================================
+// Helpers
+// ============================================================================
+/**
+ * Clamp a number to the range [min, max].
+ */
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+//# sourceMappingURL=uncertainty.js.map

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

@@ -0,0 +1,48 @@
+/**
+ * WASM Kernel Host Bridge
+ *
+ * Layer B: Node host runtime that calls into the Rust WASM kernel (Layer A).
+ * All WASM calls go through this bridge. If the WASM module fails to load,
+ * the bridge transparently falls back to the JavaScript implementations.
+ *
+ * Key rule: The host calls the kernel once per event with a batch payload,
+ * not thousands of tiny calls.
+ *
+ * @module @claude-flow/guidance/wasm-kernel
+ */
+export interface WasmKernel {
+    /** Whether the WASM kernel is loaded (false = JS fallback) */
+    readonly available: boolean;
+    /** Kernel version string (or 'js-fallback') */
+    readonly version: string;
+    sha256(input: string): string;
+    hmacSha256(key: string, input: string): string;
+    contentHash(jsonInput: string): string;
+    signEnvelope(key: string, envelopeJson: string): string;
+    verifyChain(chainJson: string, key: string): boolean;
+    scanSecrets(content: string): string[];
+    detectDestructive(command: string): string | null;
+    batchProcess(ops: BatchOp[]): BatchResult[];
+}
+export interface BatchOp {
+    op: string;
+    payload: string;
+    key?: string;
+}
+export interface BatchResult {
+    [key: string]: unknown;
+}
+/**
+ * Get the WASM kernel instance. Automatically falls back to JS if WASM is
+ * unavailable. Thread-safe (single initialization).
+ */
+export declare function getKernel(): WasmKernel;
+/**
+ * Check if the WASM kernel is available without initializing it.
+ */
+export declare function isWasmAvailable(): boolean;
+/**
+ * Reset the kernel instance (for testing).
+ */
+export declare function resetKernel(): void;
+//# sourceMappingURL=wasm-kernel.d.ts.map