noteconnection 1.7.0 → 1.8.0

package/dist/src/learning/domains/QualityEvaluator.js

@@ -0,0 +1,307 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QualityEvaluator = void 0;
+class QualityEvaluator {
+    constructor(platform, defaultThresholds = {}) {
+        this.platform = platform;
+        this.defaultThresholds = defaultThresholds;
+        this.evaluationCount = 0;
+        this.snapshotCount = 0;
+        this.planEvaluationCount = 0;
+        this.lastEvaluationAt = null;
+        this.evaluationPassRateHistory = [];
+        // Domain-level analysis state
+        this.evaluationHistory = [];
+        this.lastSnapshot = null;
+        this.regressionCount = 0;
+        this.lastRegressionAt = null;
+        // Domain health scoring weights for composite metric
+        this.healthWeights = {
+            retestPassRateUplift: 0.25,
+            misconceptionReduction: 0.25,
+            evidenceRatio: 0.20,
+            pathEffectiveness: 0.20,
+            queryP95: 0.10,
+        };
+    }
+    // ─── Public API ─────────────────────────────────────────────────
+    async evaluate(r) {
+        this.validateEvaluationRequest(r);
+        this.evaluationCount++;
+        this.lastEvaluationAt = new Date().toISOString();
+        // Domain-level baseline enrichment: auto-fill baseline from last snapshot
+        const enriched = this.enrichWithLastSnapshot(r);
+        const result = await this.platform.evaluateLearningQuality(enriched);
+        // Domain-level analysis
+        const healthScore = this.computeHealthScore(result);
+        const driftedMetrics = this.detectMetricDrift(result);
+        const regressed = this.detectRegression(result);
+        this.evaluationPassRateHistory.push(result.overallPassed);
+        if (this.evaluationPassRateHistory.length > 200)
+            this.evaluationPassRateHistory.shift();
+        // Record evaluation for trend analysis
+        this.recordEvaluation(result, healthScore);
+        if (regressed) {
+            this.regressionCount++;
+            this.lastRegressionAt = new Date().toISOString();
+        }
+        return this.augmentEvaluationResponse(result, healthScore, driftedMetrics, regressed);
+    }
+    async captureSnapshot(r) {
+        this.snapshotCount++;
+        const response = await this.platform.captureLearningQualitySnapshot(r);
+        // Cache the latest snapshot for auto-baseline in evaluate()
+        if (response?.snapshot) {
+            this.lastSnapshot = {
+                snapshot: response.snapshot,
+                sampledAt: response.sampledAt || new Date().toISOString(),
+            };
+        }
+        // Domain-level snapshot metadata
+        return {
+            ...response,
+            _domain: {
+                snapshotNumber: this.snapshotCount,
+                isReference: this.lastSnapshot === null,
+            },
+        };
+    }
+    async queryHistory(r) {
+        const response = await this.platform.queryLearningQualityHistory(r);
+        return {
+            ...response,
+            _domain: {
+                evaluationCount: this.evaluationCount,
+                regressionCount: this.regressionCount,
+                recentHealthScore: this.evaluationHistory.length > 0
+                    ? this.evaluationHistory[this.evaluationHistory.length - 1].healthScore
+                    : null,
+            },
+        };
+    }
+    async queryTrend(r) {
+        const response = await this.platform.queryLearningQualityTrend(r);
+        const domainTrend = this.computeDomainTrend(10);
+        return { ...response, _domain: { domainTrend } };
+    }
+    getThresholds() {
+        return this.platform.getLearningQualityThresholds();
+    }
+    async evaluatePlanQuality(r) {
+        this.planEvaluationCount++;
+        const response = await this.platform.evaluateStudySessionPlanQuality(r);
+        // Domain-level plan quality analysis
+        const planAnalysis = this.analyzePlanQuality(r, response);
+        return {
+            ...response,
+            _domain: {
+                planEvaluationNumber: this.planEvaluationCount,
+                planAnalysis,
+            },
+        };
+    }
+    async queryPlanQualityHistory(r) {
+        return this.platform.queryStudySessionPlanQualityHistory(r);
+    }
+    async queryPlanQualityTrend(r) {
+        return this.platform.queryStudySessionPlanQualityTrend(r);
+    }
+    async queryPlanQualityRuntimeThresholds(r) {
+        return this.platform.queryStudySessionPlanQualityRuntimeThresholds(r);
+    }
+    // ─── Public accessors ───────────────────────────────────────────
+    getEvaluationCount() { return this.evaluationCount; }
+    recentPassRate(n = 50) {
+        const w = this.evaluationPassRateHistory.slice(-n);
+        return w.length === 0 ? 1 : w.filter(Boolean).length / w.length;
+    }
+    getRegressionCount() { return this.regressionCount; }
+    getEvaluationHistory() { return [...this.evaluationHistory]; }
+    getDiagnosticsSummary() {
+        const trend = this.computeDomainTrend(5);
+        return {
+            evaluationCount: this.evaluationCount,
+            snapshotCount: this.snapshotCount,
+            planEvaluationCount: this.planEvaluationCount,
+            lastEvaluationAt: this.lastEvaluationAt,
+            recentPassRate: Number((this.recentPassRate(50) * 100).toFixed(1)),
+            regressionCount: this.regressionCount,
+            lastRegressionAt: this.lastRegressionAt,
+            currentHealthScore: this.evaluationHistory.length > 0
+                ? this.evaluationHistory[this.evaluationHistory.length - 1].healthScore
+                : null,
+            healthTrend: trend,
+        };
+    }
+    // ─── Private: validation ────────────────────────────────────────
+    validateEvaluationRequest(r) {
+        if (!r)
+            throw new Error('Quality evaluation request is required.');
+        if (!r?.userId)
+            throw new Error('userId is required for quality evaluation.');
+    }
+    // ─── Private: augmentation ──────────────────────────────────────
+    augmentEvaluationResponse(response, healthScore, driftedMetrics, regressed) {
+        return {
+            ...response,
+            _domain: {
+                evaluationNumber: this.evaluationCount,
+                snapshotCount: this.snapshotCount,
+                recentPassRate: this.recentPassRate(20),
+                evaluatedAt: this.lastEvaluationAt,
+                healthScore,
+                driftedMetrics,
+                regressed,
+            },
+        };
+    }
+    // ─── Private: health scoring ────────────────────────────────────
+    /**
+     * Compute a composite health score (0-100) from gate deltas.
+     * Weights: retest uplift 25%, misconception reduction 25%,
+     * evidence ratio 20%, path effectiveness 20%, query P95 10%.
+     */
+    computeHealthScore(result) {
+        const deltas = result?.deltas || {};
+        const gates = Array.isArray(result?.gates) ? result.gates : [];
+        const gateMap = new Map();
+        for (const gate of gates) {
+            gateMap.set(gate.gateId, gate.passed);
+        }
+        let score = 0;
+        // Retest uplift: normalize to 0-1 range (expected 0-20% uplift)
+        const uplift = Number(deltas.retestPassRateUpliftPct || 0);
+        const upliftScore = clamp(uplift / 20, 0, 1);
+        score += upliftScore * this.healthWeights.retestPassRateUplift;
+        // Misconception reduction: normalize to 0-1 range (expected 0-15% reduction)
+        const reduction = Number(deltas.misconceptionRecurrenceReductionPct || 0);
+        const reductionScore = clamp(reduction / 15, 0, 1);
+        score += reductionScore * this.healthWeights.misconceptionReduction;
+        // Evidence ratio: binary gate contributes, plus bonus for high ratio
+        const evidencePassed = gateMap.get('evidence_ratio') === true;
+        const evidenceScore = evidencePassed ? 0.8 : 0.3;
+        score += evidenceScore * this.healthWeights.evidenceRatio;
+        // Path effectiveness: normalize to 0-1 range (expected 5-30% lift)
+        const pathLift = Number(deltas.pathEffectivenessLiftPct || 0);
+        const pathScore = clamp(pathLift / 30, 0, 1);
+        score += pathScore * this.healthWeights.pathEffectiveness;
+        // Query P95: passed gate = full, otherwise scale by proximity
+        const queryPassed = gateMap.get('query_p95') === true;
+        const queryScore = queryPassed ? 1.0 : 0.3;
+        score += queryScore * this.healthWeights.queryP95;
+        return Number((score * 100).toFixed(1));
+    }
+    // ─── Private: metric drift detection ────────────────────────────
+    /**
+     * Detect significant metric drift between baseline and current.
+     * Flags any metric whose absolute change exceeds reasonable thresholds.
+     */
+    detectMetricDrift(result) {
+        const drifted = [];
+        const baseline = result?.baseline || {};
+        const current = result?.current || {};
+        const driftThresholds = {
+            retestPassRatePct: 15,
+            misconceptionRecurrenceRatePct: 10,
+            evidenceBackedSuggestionRatioPct: 15,
+            averagePathMasteryGainPct: 12,
+            randomPathMasteryGainPct: 12,
+            queryP95Ms: 2000,
+        };
+        for (const [key, threshold] of Object.entries(driftThresholds)) {
+            const delta = Number((current[key] || 0) - (baseline[key] || 0));
+            if (Math.abs(delta) > threshold) {
+                const direction = delta > 0 ? '+' : '';
+                drifted.push(`${key}: ${direction}${Number(delta).toFixed(1)} (threshold: ${threshold})`);
+            }
+        }
+        return drifted;
+    }
+    // ─── Private: regression detection ──────────────────────────────
+    /**
+     * Detect quality regression by comparing current gates against
+     * the previous evaluation. Regression = previously-passing gate now fails.
+     */
+    detectRegression(result) {
+        if (this.evaluationHistory.length === 0)
+            return false;
+        const prev = this.evaluationHistory[this.evaluationHistory.length - 1];
+        const currentGates = Array.isArray(result?.gates) ? result.gates : [];
+        const currentGateMap = new Map();
+        for (const gate of currentGates) {
+            currentGateMap.set(gate.gateId, gate.passed);
+        }
+        // Check if any previously-passing gate now fails
+        for (const [gateId, wasPassed] of Object.entries(prev.gateResults)) {
+            if (wasPassed && currentGateMap.get(gateId) === false) {
+                return true;
+            }
+        }
+        return false;
+    }
+    // ─── Private: evaluation history ────────────────────────────────
+    recordEvaluation(result, healthScore) {
+        const gates = Array.isArray(result?.gates) ? result.gates : [];
+        const gateResults = {};
+        for (const gate of gates) {
+            gateResults[gate.gateId] = gate.passed;
+        }
+        this.evaluationHistory.push({
+            evaluatedAt: result?.evaluatedAt || new Date().toISOString(),
+            overallPassed: result?.overallPassed ?? false,
+            healthScore,
+            gateResults,
+            deltas: { ...(result?.deltas || {}) },
+        });
+        if (this.evaluationHistory.length > 100)
+            this.evaluationHistory.shift();
+    }
+    // ─── Private: auto-baseline from last snapshot ──────────────────
+    /**
+     * If no baseline is explicitly provided, use the last captured snapshot
+     * as an implicit baseline, enabling trend analysis without manual setup.
+     */
+    enrichWithLastSnapshot(r) {
+        if (r?.baseline || !this.lastSnapshot)
+            return r;
+        return { ...r, baseline: this.lastSnapshot.snapshot };
+    }
+    // ─── Private: domain trend computation ──────────────────────────
+    computeDomainTrend(n) {
+        const window = this.evaluationHistory.slice(-n);
+        if (window.length < 2) {
+            return {
+                direction: 'insufficient_data',
+                recentHealthScore: window[0]?.healthScore ?? 0,
+                windowAvgHealthScore: window[0]?.healthScore ?? 0,
+                healthScoreDelta: 0,
+                snapshotCount: window.length,
+            };
+        }
+        const mid = Math.floor(window.length / 2);
+        const recentAvg = window.slice(-mid).reduce((s, e) => s + e.healthScore, 0) / mid;
+        const earlierAvg = window.slice(0, mid).reduce((s, e) => s + e.healthScore, 0) / mid;
+        const delta = recentAvg - earlierAvg;
+        return {
+            direction: delta > 5 ? 'improving' : delta < -5 ? 'degrading' : 'stable',
+            recentHealthScore: window[window.length - 1].healthScore,
+            windowAvgHealthScore: Number((window.reduce((s, e) => s + e.healthScore, 0) / window.length).toFixed(1)),
+            healthScoreDelta: Number(delta.toFixed(1)),
+            snapshotCount: window.length,
+        };
+    }
+    // ─── Private: plan quality analysis ─────────────────────────────
+    analyzePlanQuality(request, _response) {
+        return {
+            actionCount: Array.isArray(request?.actions) ? request.actions.length : 0,
+            hasExplicitFocus: Array.isArray(request?.focusAtomIds) && request.focusAtomIds.length > 0,
+            hasPathStrategy: typeof request?.pathStrategy === 'string' && request.pathStrategy.length > 0,
+            hasAutoPromote: request?.autoPromoteMemory === true,
+        };
+    }
+}
+exports.QualityEvaluator = QualityEvaluator;
+/** Clamp a value to [min, max]. */
+function clamp(value, min, max) {
+    return value < min ? min : value > max ? max : value;
+}

package/dist/src/learning/domains/TutorRouter.js

@@ -0,0 +1,313 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TutorRouter = void 0;
+class TutorRouter {
+    constructor(platform) {
+        this.platform = platform;
+        this.actionExecutionCount = 0;
+        this.catalogFetchCount = 0;
+        this.telemetryFetchCount = 0;
+        this.actionKindCounts = {};
+        // Domain-level analysis state
+        this.confidenceHistory = [];
+        this.sourceEffectiveness = {
+            ruleEngine: { count: 0, avgConfidence: 0, avgEvidenceCount: 0 },
+            llmAdapter: { count: 0, avgConfidence: 0, avgEvidenceCount: 0, downgradeCount: 0, errorCount: 0 },
+        };
+        this.downgradeEvents = [];
+        this.actionKindEffectiveness = new Map();
+        // Domain budgets
+        this.budgets = {
+            minConfidenceForAcceptance: 0.5,
+            downgradeAlertThreshold: 10, // alert when downgrade rate exceeds 10% in window
+            minEvidenceBindingRatio: 0.3, // minimum acceptable evidence-backed trace ratio
+        };
+    }
+    // ─── Public API ─────────────────────────────────────────────────
+    async getCatalog() {
+        this.catalogFetchCount++;
+        const catalog = await this.platform.getTutorAdapterCatalog();
+        // Domain-level catalog augmentation
+        const adapterCount = Array.isArray(catalog?.adapters) ? catalog.adapters.length : 0;
+        return {
+            ...catalog,
+            _domain: {
+                catalogFetchNumber: this.catalogFetchCount,
+                adapterCount,
+                hasFallbackRuleEngine: true,
+            },
+        };
+    }
+    async getTelemetry() {
+        this.telemetryFetchCount++;
+        const telemetry = await this.platform.getTutorAdapterTelemetry();
+        // Domain-level source effectiveness summary
+        return {
+            ...telemetry,
+            _domain: {
+                telemetryFetchNumber: this.telemetryFetchCount,
+                sourceEffectiveness: this.getSourceEffectiveness(),
+                downgradeRate: this.getDowngradeRate(50),
+                topActionKinds: this.getTopActionKinds(5),
+            },
+        };
+    }
+    async queryTraceDiagnostics(r) {
+        const response = await this.platform.queryTutorTraceDiagnostics(r);
+        // Domain-level trace quality analysis
+        const traceQuality = this.analyzeTraceQuality(response);
+        return { ...response, _domain: { traceQuality } };
+    }
+    async queryProviderTrendDiagnostics(r) {
+        const response = await this.platform.queryTutorProviderTrendDiagnostics(r);
+        // Domain-level provider preference analysis
+        const providerAnalysis = this.analyzeProviderTrend(response);
+        return { ...response, _domain: { providerAnalysis } };
+    }
+    async queryProviderTrendHistory(r) {
+        return this.platform.queryTutorProviderTrendHistory(r);
+    }
+    async executeAction(r) {
+        this.validateActionRequest(r);
+        this.actionExecutionCount++;
+        const kind = String(r?.actionKind ?? 'unknown');
+        this.actionKindCounts[kind] = (this.actionKindCounts[kind] || 0) + 1;
+        const response = await this.platform.executeTutorAction(r);
+        // Domain-level post-execution analysis
+        const trace = response?.trace;
+        if (trace) {
+            this.recordConfidence(trace, kind);
+            this.trackSourceEffectiveness(trace);
+            this.trackActionKindEffectiveness(kind, trace);
+            this.detectDowngrade(trace, kind);
+        }
+        return this.augmentActionResponse(response, kind);
+    }
+    // ─── Public accessors ───────────────────────────────────────────
+    getActionExecutionCount() { return this.actionExecutionCount; }
+    getSourceEffectiveness() {
+        return {
+            ruleEngine: { ...this.sourceEffectiveness.ruleEngine },
+            llmAdapter: { ...this.sourceEffectiveness.llmAdapter },
+        };
+    }
+    getDowngradeRate(windowSize = 50) {
+        const totalLlm = this.sourceEffectiveness.llmAdapter.count;
+        if (totalLlm === 0)
+            return 0;
+        const downgraded = this.sourceEffectiveness.llmAdapter.downgradeCount;
+        return Number(((downgraded / totalLlm) * 100).toFixed(1));
+    }
+    getConfidenceHistory() { return [...this.confidenceHistory]; }
+    getDowngradeEvents() { return [...this.downgradeEvents]; }
+    getDiagnosticsSummary() {
+        return {
+            actionExecutionCount: this.actionExecutionCount,
+            catalogFetchCount: this.catalogFetchCount,
+            telemetryFetchCount: this.telemetryFetchCount,
+            actionKindDistribution: { ...this.actionKindCounts },
+            sourceEffectiveness: this.getSourceEffectiveness(),
+            downgradeRate: this.getDowngradeRate(50),
+            downgradeEventCount: this.downgradeEvents.length,
+            recentDowngrades: this.downgradeEvents.slice(-5),
+            confidenceTrend: this.computeConfidenceTrend(20),
+        };
+    }
+    // ─── Private: validation ────────────────────────────────────────
+    validateActionRequest(r) {
+        if (!r)
+            throw new Error('Tutor action request is required.');
+        if (!r?.userId)
+            throw new Error('userId is required for tutor actions.');
+        if (!r?.actionKind)
+            throw new Error('actionKind is required for tutor actions.');
+    }
+    // ─── Private: augmentation ──────────────────────────────────────
+    augmentActionResponse(response, kind) {
+        const trace = response?.trace;
+        const evidenceCount = Array.isArray(trace?.evidenceSpanIds) ? trace.evidenceSpanIds.length : 0;
+        const source = trace?.source ?? 'unknown';
+        return {
+            ...response,
+            _domain: {
+                actionKind: kind,
+                executionNumber: this.actionExecutionCount,
+                kindCount: this.actionKindCounts[kind] || 1,
+                source,
+                confidence: trace?.confidence ?? null,
+                evidenceBindingCount: evidenceCount,
+                evidenceBindingScore: this.scoreEvidenceBinding(evidenceCount, kind),
+                qualityFlag: this.flagTraceQuality(trace),
+            },
+        };
+    }
+    // ─── Private: confidence tracking ───────────────────────────────
+    recordConfidence(trace, actionKind) {
+        const evidenceCount = Array.isArray(trace?.evidenceSpanIds) ? trace.evidenceSpanIds.length : 0;
+        this.confidenceHistory.push({
+            timestamp: trace?.createdAt || new Date().toISOString(),
+            actionKind,
+            source: trace?.source ?? 'unknown',
+            confidence: Number(trace?.confidence ?? 0),
+            evidenceCount,
+        });
+        if (this.confidenceHistory.length > 200)
+            this.confidenceHistory.shift();
+    }
+    computeConfidenceTrend(n) {
+        const window = this.confidenceHistory.slice(-n);
+        if (window.length < 2) {
+            return {
+                direction: 'insufficient_data',
+                recentAvg: window[0]?.confidence ?? 0,
+                windowAvg: window[0]?.confidence ?? 0,
+                snapshotCount: window.length,
+            };
+        }
+        const mid = Math.floor(window.length / 2);
+        const recentAvg = window.slice(-mid).reduce((s, e) => s + e.confidence, 0) / mid;
+        const earlierAvg = window.slice(0, mid).reduce((s, e) => s + e.confidence, 0) / mid;
+        const delta = recentAvg - earlierAvg;
+        return {
+            direction: delta > 0.1 ? 'improving' : delta < -0.1 ? 'declining' : 'stable',
+            recentAvg: Number(recentAvg.toFixed(4)),
+            windowAvg: Number((window.reduce((s, e) => s + e.confidence, 0) / window.length).toFixed(4)),
+            snapshotCount: window.length,
+        };
+    }
+    // ─── Private: source effectiveness ──────────────────────────────
+    trackSourceEffectiveness(trace) {
+        const source = trace?.source;
+        const evidenceCount = Array.isArray(trace?.evidenceSpanIds) ? trace.evidenceSpanIds.length : 0;
+        if (source === 'rule-engine') {
+            const re = this.sourceEffectiveness.ruleEngine;
+            re.count++;
+            re.avgConfidence = Number(((re.avgConfidence * (re.count - 1) + (trace?.confidence || 0)) / re.count).toFixed(4));
+            re.avgEvidenceCount = Number(((re.avgEvidenceCount * (re.count - 1) + evidenceCount) / re.count).toFixed(2));
+        }
+        else if (source === 'llm-adapter') {
+            const la = this.sourceEffectiveness.llmAdapter;
+            la.count++;
+            la.avgConfidence = Number(((la.avgConfidence * (la.count - 1) + (trace?.confidence || 0)) / la.count).toFixed(4));
+            la.avgEvidenceCount = Number(((la.avgEvidenceCount * (la.count - 1) + evidenceCount) / la.count).toFixed(2));
+        }
+    }
+    // ─── Private: action kind effectiveness ─────────────────────────
+    trackActionKindEffectiveness(kind, trace) {
+        let entry = this.actionKindEffectiveness.get(kind);
+        if (!entry) {
+            entry = { count: 0, totalConfidence: 0, evidenceBackedCount: 0 };
+            this.actionKindEffectiveness.set(kind, entry);
+        }
+        entry.count++;
+        entry.totalConfidence += Number(trace?.confidence || 0);
+        const evidenceCount = Array.isArray(trace?.evidenceSpanIds) ? trace.evidenceSpanIds.length : 0;
+        if (evidenceCount > 0)
+            entry.evidenceBackedCount++;
+    }
+    getTopActionKinds(n) {
+        return [...this.actionKindEffectiveness.entries()]
+            .sort((a, b) => b[1].count - a[1].count)
+            .slice(0, n)
+            .map(([kind, stats]) => ({
+            kind,
+            count: stats.count,
+            avgConfidence: Number((stats.totalConfidence / stats.count).toFixed(4)),
+            evidenceRatio: Number(((stats.evidenceBackedCount / stats.count) * 100).toFixed(1)),
+        }));
+    }
+    // ─── Private: downgrade detection ───────────────────────────────
+    detectDowngrade(trace, actionKind) {
+        const source = trace?.source;
+        const confidence = Number(trace?.confidence || 0);
+        const notes = String(trace?.notes || '');
+        // Track LLM adapter downgrades (responses rejected due to low confidence)
+        if (source === 'llm-adapter' && notes.includes('downgraded')) {
+            this.sourceEffectiveness.llmAdapter.downgradeCount++;
+            this.downgradeEvents.push({
+                timestamp: trace?.createdAt || new Date().toISOString(),
+                actionKind,
+                reason: notes,
+                confidence,
+            });
+            if (this.downgradeEvents.length > 100)
+                this.downgradeEvents.shift();
+        }
+        // Track LLM adapter errors (fallback used)
+        if (source === 'llm-adapter' && (notes.includes('failed') || notes.includes('fallback'))) {
+            this.sourceEffectiveness.llmAdapter.errorCount++;
+        }
+    }
+    // ─── Private: evidence binding scoring ──────────────────────────
+    scoreEvidenceBinding(evidenceCount, actionKind) {
+        // Different action kinds have different evidence expectations
+        const expectedEvidence = {
+            explain: 2,
+            quiz: 1,
+            review: 2,
+            analyze_answer: 1,
+            summarize: 1,
+        };
+        const expected = expectedEvidence[actionKind] ?? 1;
+        const score = evidenceCount >= expected ? 1 : evidenceCount / Math.max(1, expected);
+        return {
+            score: Number(score.toFixed(2)),
+            level: score >= 1 ? 'full' : score >= 0.5 ? 'partial' : 'insufficient',
+        };
+    }
+    // ─── Private: trace quality flagging ────────────────────────────
+    flagTraceQuality(trace) {
+        if (!trace)
+            return 'unknown';
+        const confidence = Number(trace?.confidence || 0);
+        const evidenceCount = Array.isArray(trace?.evidenceSpanIds) ? trace.evidenceSpanIds.length : 0;
+        const source = trace?.source;
+        if (source === 'llm-adapter' && confidence < this.budgets.minConfidenceForAcceptance) {
+            return 'unreliable';
+        }
+        if (evidenceCount === 0 && source === 'llm-adapter') {
+            return 'unverified';
+        }
+        if (confidence >= 0.8 && evidenceCount >= 2) {
+            return 'high_quality';
+        }
+        if (confidence >= 0.6 && evidenceCount >= 1) {
+            return 'acceptable';
+        }
+        return 'needs_review';
+    }
+    // ─── Private: trace quality analysis ────────────────────────────
+    analyzeTraceQuality(response) {
+        const items = Array.isArray(response?.items) ? response.items : [];
+        const dist = {};
+        let totalConfidence = 0;
+        let evidenceBound = 0;
+        for (const item of items) {
+            const flag = this.flagTraceQuality(item?.trace);
+            dist[flag] = (dist[flag] || 0) + 1;
+            totalConfidence += Number(item?.trace?.confidence || 0);
+            const evidenceCount = Array.isArray(item?.trace?.evidenceSpanIds) ? item.trace.evidenceSpanIds.length : 0;
+            if (evidenceCount > 0)
+                evidenceBound++;
+        }
+        return {
+            qualityDistribution: dist,
+            evidenceBindingRate: items.length > 0
+                ? Number(((evidenceBound / items.length) * 100).toFixed(1))
+                : 0,
+            averageConfidence: items.length > 0
+                ? Number((totalConfidence / items.length).toFixed(4))
+                : 0,
+        };
+    }
+    // ─── Private: provider trend analysis ───────────────────────────
+    analyzeProviderTrend(response) {
+        const providers = Array.isArray(response?.providers) ? response.providers : [];
+        return {
+            providerCount: providers.length,
+            hasActiveAdapter: this.sourceEffectiveness.llmAdapter.count > 0,
+            ruleEngineFallbackActive: true,
+        };
+    }
+}
+exports.TutorRouter = TutorRouter;

package/dist/src/learning/domains/index.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Domain classes extracted from KnowledgeLearningPlatform.
+ *
+ * Each domain class wraps the platform behind a clean interface.
+ * Implementations are gradually migrated from the monolithic
+ * KnowledgeLearningPlatform into these domain classes.
+ *
+ * Usage:
+ *   const ingestor = new KnowledgeIngestor(platform);
+ *   const querier  = new KnowledgeQuerier(platform);
+ *   const conv     = new ConversationManager(platform);
+ *   const mastery  = new MasteryEngine(platform);
+ *   const quality  = new QualityEvaluator(platform, thresholds);
+ *   const tutor    = new TutorRouter(platform);
+ *   const memory   = new MemoryPolicyManager(platform);
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MemoryPolicyManager = exports.TutorRouter = exports.QualityEvaluator = exports.MasteryEngine = exports.ConversationManager = exports.KnowledgeQuerier = exports.KnowledgeIngestor = void 0;
+var KnowledgeIngestor_1 = require("./KnowledgeIngestor");
+Object.defineProperty(exports, "KnowledgeIngestor", { enumerable: true, get: function () { return KnowledgeIngestor_1.KnowledgeIngestor; } });
+var KnowledgeQuerier_1 = require("./KnowledgeQuerier");
+Object.defineProperty(exports, "KnowledgeQuerier", { enumerable: true, get: function () { return KnowledgeQuerier_1.KnowledgeQuerier; } });
+var ConversationManager_1 = require("./ConversationManager");
+Object.defineProperty(exports, "ConversationManager", { enumerable: true, get: function () { return ConversationManager_1.ConversationManager; } });
+var MasteryEngine_1 = require("./MasteryEngine");
+Object.defineProperty(exports, "MasteryEngine", { enumerable: true, get: function () { return MasteryEngine_1.MasteryEngine; } });
+var QualityEvaluator_1 = require("./QualityEvaluator");
+Object.defineProperty(exports, "QualityEvaluator", { enumerable: true, get: function () { return QualityEvaluator_1.QualityEvaluator; } });
+var TutorRouter_1 = require("./TutorRouter");
+Object.defineProperty(exports, "TutorRouter", { enumerable: true, get: function () { return TutorRouter_1.TutorRouter; } });
+var MemoryPolicyManager_1 = require("./MemoryPolicyManager");
+Object.defineProperty(exports, "MemoryPolicyManager", { enumerable: true, get: function () { return MemoryPolicyManager_1.MemoryPolicyManager; } });

package/dist/src/learning/domains/types.js

@@ -0,0 +1,7 @@
+"use strict";
+/**
+ * Domain base types for the KnowledgeLearningPlatform decomposition.
+ * Uses types from the public API surface (../types) and defines
+ * local interfaces for internal types not in the public contract.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });