monomind 1.19.0 → 2.0.0

package/packages/@monomind/guidance/dist/uncertainty.js

@@ -1,619 +0,0 @@
-/**
- * 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 @monomind/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/packages/@monomind/guidance/dist/wasm-kernel.d.ts

@@ -1,48 +0,0 @@
-/**
- * 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 @monomind/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