bilmem 0.1.0

package/dist/core/index.d.ts

@@ -0,0 +1,311 @@
+import { d as EvidenceRelation, r as ReconciliationResult, K as Knowledge, q as ReconciliationAction, C as ConfidenceTier, o as Observation, c as Evidence, n as KnowledgeType, m as KnowledgeStatus, l as KnowledgeStage, S as Scope, i as KnowledgeHistoryEntry, k as KnowledgeOutcomesSummary, P as Provenance, L as UnknownState, H as UnknownReason, G as UnknownNextAction, U as UnknownRecord, b as BilmemMetrics, p as OutcomeRecord, O as OutcomeType, T as TaskTrajectory, g as KnowledgeBudgetConfig, A as ActionType, R as ResolveOptions, a as ResolutionResult } from '../types-Nxq5Gzay.js';
+export { B as BilmemConfig, E as EvaluatedRule, I as InvestigationReceipt, e as JevExplanation, f as JevMatchStatus, J as JevResult, h as KnowledgeDiff, j as KnowledgeMetrics, N as NextEvidenceAction, s as RelationType, t as ResolutionReason, u as ResolutionState, v as RevisionSnapshot, w as RuleCondition, x as RuleDefinition, y as RuleSet, z as TemporalMetadata, D as TrajectoryEvent, F as TrajectoryEventType } from '../types-Nxq5Gzay.js';
+import { M as MetricEvent, S as Storage } from '../canonical-CglQQ0xc.js';
+import { BilmemRetriever as Retriever, OramaIndex as SearchIndex } from '../search/index.js';
+
+/**
+ * Lightweight, in-memory graph structure for managing relations between
+ * files, observations, evidence, and knowledge nodes.
+ */
+declare class EvidenceGraph {
+    private fromMap;
+    private toMap;
+    constructor(relations?: EvidenceRelation[]);
+    addRelation(relation: EvidenceRelation): void;
+    getRelationsFrom(fromId: string): EvidenceRelation[];
+    getRelationsTo(toId: string): EvidenceRelation[];
+    getRelationsBetween(fromId: string, toId: string): EvidenceRelation[];
+    getAllRelations(): EvidenceRelation[];
+    findCoChanged(file: string, threshold?: number): Array<{
+        file: string;
+        weight: number;
+    }>;
+    findConnected(id: string, maxDepth?: number): string[];
+    toJSON(): EvidenceRelation[];
+    static fromJSON(relations: EvidenceRelation[]): EvidenceGraph;
+}
+
+/**
+ * Deterministic mapping between confidence tiers and normalized float scores.
+ * Replaces arbitrary precision floats with explainable thresholds.
+ */
+declare function tierToConfidence(tier: ConfidenceTier): number;
+declare function confidenceToTier(score: number): ConfidenceTier;
+declare function hashString(input: string): string;
+declare function createObservation(params: {
+    source: string;
+    claim: string;
+    provenance?: Provenance;
+    confidence?: number;
+    positive?: string[];
+    negative?: string[];
+    details?: Record<string, unknown>;
+}): Observation;
+/**
+ * Creates or consolidates evidence based on underlying source.
+ * Crucial constraint: Multiple agents reading the same source must NOT count as independent evidence.
+ */
+declare function createEvidence(observation: Observation, type?: 'supports' | 'contradicts' | 'observes'): Evidence;
+declare function createKnowledge(params: {
+    id: string;
+    type?: KnowledgeType;
+    status?: KnowledgeStatus;
+    stage?: KnowledgeStage;
+    statement: string;
+    positive?: string[];
+    negative?: string[];
+    relations?: string[];
+    depends_on?: string[];
+    resolves?: string[];
+    question?: string;
+    confidence?: number;
+    confidenceTier?: ConfidenceTier;
+    evidence?: string[];
+    scope?: Scope;
+    tags?: string[];
+    history?: KnowledgeHistoryEntry[];
+    outcomesSummary?: KnowledgeOutcomesSummary;
+}): Knowledge;
+/**
+ * Calculate effective confidence combining evidence ratio and outcome history.
+ */
+declare function calculateEffectiveConfidence(knowledge: Knowledge): number;
+/**
+ * Checks if two statements express opposite polarity or semantic contradiction.
+ * Essential rule: High lexical similarity does NOT imply MERGE.
+ * "cache enabled in production" vs "cache disabled in production" have opposite polarity.
+ */
+declare function detectPolarContradiction(stmtA: string, stmtB: string): {
+    contradicted: boolean;
+    reason?: string;
+};
+/**
+ * Reconcile an incoming candidate lesson with existing knowledge.
+ * Classifies the action as: NEW, MERGE, UPDATE, SUPPORT, CONTRADICT, SPECIALIZE, GENERALIZE, IGNORE.
+ */
+declare function reconcileKnowledge(candidate: Partial<Knowledge> & {
+    statement: string;
+}, existingList: Knowledge[]): ReconciliationResult;
+/**
+ * Apply reconciliation to knowledge base.
+ */
+declare function applyReconciliation(reconciliation: ReconciliationResult, candidate: Partial<Knowledge> & {
+    statement: string;
+}, existingList: Knowledge[], storage?: {
+    appendMetricEvent(event: MetricEvent): Promise<void>;
+}): {
+    updatedKnowledge: Knowledge;
+    action: ReconciliationAction;
+    createdId: string;
+};
+
+declare function createUnknown(params: {
+    id: string;
+    state?: UnknownState;
+    reason?: UnknownReason;
+    statement?: string;
+    checked?: string[];
+    next?: UnknownNextAction;
+    scope?: Scope;
+}): UnknownRecord;
+/**
+ * Checks if a specific path or query was already investigated,
+ * helping agents avoid repeating useless investigations.
+ */
+declare function hasBeenInvestigated(unknowns: UnknownRecord[], target: string): {
+    investigated: boolean;
+    record?: UnknownRecord;
+    reason?: string;
+};
+/**
+ * Update an existing unknown with new checked paths or update its state when partially known or resolved.
+ */
+declare function updateUnknown(record: UnknownRecord, updates: {
+    state?: UnknownState;
+    reason?: UnknownReason;
+    statement?: string;
+    addChecked?: string[];
+    next?: UnknownNextAction;
+}): UnknownRecord;
+
+declare function createOutcome(params: {
+    knowledgeId?: string;
+    taskId?: string;
+    result: OutcomeType;
+    context?: {
+        positive?: string[];
+        negative?: string[];
+    };
+    feedback?: string;
+}): OutcomeRecord;
+/**
+ * Apply outcome to a knowledge unit and recalculate its confidence.
+ */
+declare function applyOutcomeToKnowledge(knowledge: Knowledge, outcome: OutcomeRecord): Knowledge;
+declare class MetricsTracker {
+    private metrics;
+    constructor(initial?: Partial<BilmemMetrics>);
+    recordHit(): void;
+    recordMiss(): void;
+    recordReused(): void;
+    recordUnknownResolved(): void;
+    recordInvestigationPrevented(): void;
+    recordCandidateMerged(): void;
+    recordStaleDetected(): void;
+    recordContradiction(): void;
+    recordPromoted(): void;
+    recordSuperseded(): void;
+    getMetrics(): BilmemMetrics;
+    toJSON(): BilmemMetrics;
+}
+
+interface DistilledLesson {
+    id: string;
+    statement: string;
+    positive: string[];
+    negative: string[];
+    confidence: number;
+    evidence: string[];
+    tags: string[];
+    reasoning: string;
+}
+interface TrajectoryLearningResult {
+    taskId: string;
+    observations: Observation[];
+    evidence: Evidence[];
+    candidateLessons: Array<Partial<Knowledge> & {
+        statement: string;
+    }>;
+    reconciliations: Array<{
+        candidate: Partial<Knowledge> & {
+            statement: string;
+        };
+        result: ReconciliationResult;
+        appliedKnowledge?: Knowledge;
+        action: ReconciliationAction;
+    }>;
+    dryRun: boolean;
+}
+/**
+ * Distill a task trajectory into a compact, reusable candidate lesson.
+ * Avoids dumping raw trajectories into permanent memory;
+ * extracts only the crystallized insight (what worked, what failed, negative patterns).
+ */
+declare function distillTrajectory(trajectory: TaskTrajectory): DistilledLesson | null;
+/**
+ * Executes the complete staged trajectory learning pipeline:
+ * trajectory → observations → candidate lessons → reconcile → knowledge
+ *
+ * Honors the "Memory should grow by refinement, not accumulation" principle.
+ * Raw trajectory is never dumped directly to knowledge.
+ */
+declare function learnFromTrajectory(trajectory: TaskTrajectory, existingKnowledge?: Knowledge[], options?: {
+    dryRun?: boolean;
+    storage?: {
+        appendMetricEvent(event: any): Promise<void>;
+    };
+}): TrajectoryLearningResult;
+/**
+ * Handle explicit user correction as high-quality evidence.
+ * Prevents future agents from repeatedly making the same invalid assumption.
+ */
+declare function processUserCorrection(params: {
+    topic: string;
+    incorrectAssumption: string;
+    correctFact: string;
+    context?: string[];
+    author?: string;
+}): {
+    observation: Observation;
+    knowledge: Knowledge;
+};
+
+interface SourceDependencyIndex {
+    sourceToKnowledge: Map<string, Set<string>>;
+}
+declare function normalizeSourceKey(source: string): string;
+/**
+ * Builds a reverse index mapping source paths / files to the knowledge IDs that depend on them.
+ */
+declare function buildDependencyIndex(knowledgeList: Knowledge[]): SourceDependencyIndex;
+interface StalenessCheckResult {
+    knowledgeId: string;
+    affected: boolean;
+    status: KnowledgeStatus;
+    changedSources: string[];
+    unchangedSources: string[];
+    reason?: string;
+}
+/**
+ * Checks a knowledge item against a list of changed file paths / sources.
+ * If any supporting dependency changed, marks as 'needs_revalidation'.
+ */
+declare function checkKnowledgeStaleness(knowledge: Knowledge, changedSources: string[]): StalenessCheckResult;
+/**
+ * Marks knowledge units as 'needs_revalidation' when their underlying dependencies change,
+ * preserving transparent history and reasons without deleting the knowledge.
+ */
+declare function markStaleKnowledge(knowledgeList: Knowledge[], changedSources: string[]): {
+    updatedKnowledge: Knowledge[];
+    affectedCount: number;
+};
+/**
+ * Checks a list of knowledge units against changed sources and returns the affected items.
+ */
+declare function checkKnowledgeListStaleness(knowledgeList: Knowledge[], changedSources: string[]): {
+    affectedKnowledge: Knowledge[];
+    updatedKnowledge: Knowledge[];
+    affectedCount: number;
+};
+
+/**
+ * Determines initial quarantine stage for a new knowledge item.
+ * Deterministic facts (e.g. compiler config, explicit package manifests) skip probation directly to 'active'.
+ * Speculative lessons, heuristics, and inferences start in 'candidate' stage.
+ */
+declare function determineInitialStage(knowledge: Partial<Knowledge>): KnowledgeStage;
+/**
+ * Evaluates whether a knowledge item qualifies for promotion along the quarantine ladder:
+ * CANDIDATE -> PROBATION -> ACTIVE
+ */
+declare function evaluatePromotion(knowledge: Knowledge): {
+    promoted: boolean;
+    newStage: KnowledgeStage;
+    reason?: string;
+};
+/**
+ * Calculates deterministic knowledge value metric.
+ * Combines reuse frequency, evidence backing, successful task outcomes, and penalizes misleading outcomes.
+ * Used during compaction and knowledge budget management.
+ */
+declare function calculateKnowledgeValue(knowledge: Knowledge): number;
+/**
+ * Applies a task outcome record to a knowledge item:
+ * Updates outcome telemetry, recalculates value, and triggers promotion or demotion.
+ */
+declare function recordOutcomeOnKnowledge(knowledge: Knowledge, outcome: OutcomeRecord): {
+    updatedKnowledge: Knowledge;
+    actionTaken?: string;
+};
+/**
+ * Enforces knowledge budget without arbitrarily deleting provenance.
+ * When active knowledge exceeds budget, demotes lowest-value items to probation/candidate.
+ */
+declare function enforceKnowledgeBudget(knowledgeList: Knowledge[], budget?: KnowledgeBudgetConfig): {
+    modifiedList: Knowledge[];
+    demotedCount: number;
+};
+
+/**
+ * Relative cost table for evidence-gathering actions.
+ * Smallest action likely to resolve uncertainty is preferred.
+ */
+declare const RELATIVE_COSTS: Record<ActionType, number>;
+/**
+ * Core Epistemic Resolver:
+ * Answers: "Do I know enough to act, what do I know does not apply,
+ * what am I missing, and what is the cheapest next step to resolve the uncertainty?"
+ */
+declare function resolveEpistemicQuery(options: ResolveOptions, storage: Storage, retriever?: Retriever | SearchIndex): Promise<ResolutionResult>;
+
+export { ActionType, BilmemMetrics, ConfidenceTier, type DistilledLesson, Evidence, EvidenceGraph, EvidenceRelation, Knowledge, KnowledgeBudgetConfig, KnowledgeHistoryEntry, KnowledgeOutcomesSummary, KnowledgeStage, KnowledgeStatus, KnowledgeType, MetricsTracker, Observation, OutcomeRecord, OutcomeType, Provenance, RELATIVE_COSTS, ReconciliationAction, ReconciliationResult, ResolutionResult, ResolveOptions, Scope, type SourceDependencyIndex, type StalenessCheckResult, TaskTrajectory, type TrajectoryLearningResult, UnknownNextAction, UnknownReason, UnknownRecord, UnknownState, applyOutcomeToKnowledge, applyReconciliation, buildDependencyIndex, calculateEffectiveConfidence, calculateKnowledgeValue, checkKnowledgeListStaleness, checkKnowledgeStaleness, confidenceToTier, createEvidence, createKnowledge, createObservation, createOutcome, createUnknown, detectPolarContradiction, determineInitialStage, distillTrajectory, enforceKnowledgeBudget, evaluatePromotion, hasBeenInvestigated, hashString, learnFromTrajectory, markStaleKnowledge, normalizeSourceKey, processUserCorrection, reconcileKnowledge, recordOutcomeOnKnowledge, resolveEpistemicQuery, tierToConfidence, updateUnknown };