noteconnection 1.7.0 → 1.8.0

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

@@ -0,0 +1,53 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConversationManager = void 0;
+class ConversationManager {
+    constructor(platform) {
+        this.platform = platform;
+        this.turnCount = 0;
+        this.totalResponseLatencyMs = 0;
+        this.memoryOpCounts = { add: 0, list: 0, search: 0, delete: 0, feedback: 0 };
+        this.lastConversationAt = null;
+    }
+    async runAgentConversation(request) {
+        this.validateConversationRequest(request);
+        const startMs = Date.now();
+        const response = await this.platform.runAgentConversation(request);
+        this.turnCount++;
+        this.totalResponseLatencyMs += Date.now() - startMs;
+        this.lastConversationAt = new Date().toISOString();
+        return this.augmentConversationResponse(response, Date.now() - startMs);
+    }
+    async addMemory(r) { this.validateMemoryRequest(r, 'add'); this.memoryOpCounts.add++; return this.platform.addConversationMemory(r); }
+    async listMemory(r) { this.memoryOpCounts.list++; return this.platform.listConversationMemory(r); }
+    async searchMemory(r) { this.memoryOpCounts.search++; return this.platform.searchConversationMemory(r); }
+    async deleteMemory(r) { this.memoryOpCounts.delete++; return this.platform.deleteConversationMemory(r); }
+    async feedbackMemory(r) { this.memoryOpCounts.feedback++; return this.platform.feedbackConversationMemory(r); }
+    getTurnCount() { return this.turnCount; }
+    averageResponseLatencyMs() { return this.turnCount === 0 ? 0 : Math.round(this.totalResponseLatencyMs / this.turnCount); }
+    getDiagnosticsSummary() {
+        return { turnCount: this.turnCount, averageResponseLatencyMs: this.averageResponseLatencyMs(), lastConversationAt: this.lastConversationAt, memoryOperations: { ...this.memoryOpCounts }, totalMemoryOps: Object.values(this.memoryOpCounts).reduce((a, b) => a + b, 0) };
+    }
+    validateConversationRequest(r) {
+        if (!r)
+            throw new Error('Conversation request is required.');
+        const query = String(r?.query ?? '').trim();
+        if (!query)
+            throw new Error('Conversation query must not be empty.');
+        if (query.length > 10000)
+            throw new Error('Conversation query exceeds maximum length.');
+    }
+    validateMemoryRequest(r, op) {
+        if (!r)
+            throw new Error(`Memory ${op} request is required.`);
+        if (op === 'add' || op === 'search') {
+            const content = String(r?.content ?? r?.query ?? '').trim();
+            if (!content)
+                throw new Error(`Memory ${op} requires non-empty content.`);
+        }
+    }
+    augmentConversationResponse(response, latencyMs) {
+        return { ...response, _domain: { turnNumber: this.turnCount, latencyMs: Math.round(latencyMs), memoryOps: this.memoryOpCounts, generatedAt: this.lastConversationAt } };
+    }
+}
+exports.ConversationManager = ConversationManager;

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

@@ -0,0 +1,238 @@
+"use strict";
+/**
+ * KnowledgeIngestor domain — L0/L1: Document parsing, atom/evidence extraction,
+ * staleness diagnostics, guardrail evaluation. Adds domain-specific value:
+ * latency tracking, staleness caching, guardrail history.
+ * Note: full type imports pending M8-M10 type stabilization in ../types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KnowledgeIngestor = void 0;
+class KnowledgeIngestor {
+    constructor(platform) {
+        this.platform = platform;
+        this.ingestLatencyHistoryMs = [];
+        this.recomputeLatencyHistoryMs = [];
+        this.latestIngestSummary = null;
+        this.stalenessCache = new Map();
+        this.stalenessQueryCount = 0;
+        this.stalenessSnapshots = [];
+        this.guardrailEvaluationHistory = [];
+    }
+    async ingestKnowledge(request) {
+        const startMs = Date.now();
+        const response = await this.platform.ingestKnowledge(request);
+        this.ingestLatencyHistoryMs.push(Date.now() - startMs);
+        if (this.ingestLatencyHistoryMs.length > 200)
+            this.ingestLatencyHistoryMs.shift();
+        if (response?.summary)
+            this.latestIngestSummary = response.summary;
+        this.stalenessCache.clear();
+        return response;
+    }
+    async queryStalenessDiagnostics(request, options) {
+        this.stalenessQueryCount++;
+        const cacheKey = this.buildStalenessCacheKey(request);
+        // Always serve cached results when available (cache is invalidated on new ingest)
+        const cached = !options?.skipCache ? this.stalenessCache.get(cacheKey) : undefined;
+        if (cached)
+            return cached.response;
+        const response = await this.platform.queryKnowledgeStalenessDiagnostics(request);
+        const generatedAt = new Date().toISOString();
+        // Domain-level staleness analysis
+        const domainAnalysis = this.buildStalenessAnalysis(response);
+        const augmented = { ...response, _domain: { stalenessAnalysis: domainAnalysis, generatedAt, queriedAt: generatedAt } };
+        this.stalenessCache.set(cacheKey, { response: augmented, generatedAt, sourceHash: cacheKey });
+        if (this.stalenessCache.size > 50) {
+            const firstKey = this.stalenessCache.keys().next().value;
+            if (firstKey)
+                this.stalenessCache.delete(firstKey);
+        }
+        // Track staleness trend for governance
+        this.recordStalenessSnapshot(domainAnalysis);
+        return augmented;
+    }
+    async rebuildFromStalenessDiagnostics(request) {
+        const startMs = Date.now();
+        const response = await this.platform.rebuildKnowledgeFromStalenessDiagnostics(request);
+        this.recomputeLatencyHistoryMs.push(Date.now() - startMs);
+        if (this.recomputeLatencyHistoryMs.length > 200)
+            this.recomputeLatencyHistoryMs.shift();
+        this.stalenessCache.clear();
+        return response;
+    }
+    /**
+     * Evaluate ingest guardrails with domain-level gate logic.
+     * Augments the platform response with independent gate validation
+     * and maintains a pass-rate history for governance dashboards.
+     */
+    async evaluateGuardrails(request) {
+        const response = await this.platform.evaluateIngestGuardrails(request);
+        // Domain-level gate validation (independent of platform)
+        const domainGates = this.buildDomainGuardrailGates(request, response);
+        const allPassed = domainGates.every((g) => g.passed);
+        this.guardrailEvaluationHistory.push({
+            passed: allPassed,
+            timestamp: new Date().toISOString(),
+        });
+        if (this.guardrailEvaluationHistory.length > 200) {
+            this.guardrailEvaluationHistory.shift();
+        }
+        // Augment response with domain-level gate telemetry
+        return {
+            ...response,
+            domainGates,
+            domainOverallPassed: allPassed,
+        };
+    }
+    getLatestIngestSummary() { return this.latestIngestSummary; }
+    getIngestLatencyHistory() { return [...this.ingestLatencyHistoryMs]; }
+    getRecomputeLatencyHistory() { return [...this.recomputeLatencyHistoryMs]; }
+    averageIngestLatencyMs(n = 20) {
+        const w = this.ingestLatencyHistoryMs.slice(-n);
+        return w.length === 0 ? 0 : w.reduce((a, b) => a + b, 0) / w.length;
+    }
+    averageRecomputeLatencyMs(n = 20) {
+        const w = this.recomputeLatencyHistoryMs.slice(-n);
+        return w.length === 0 ? 0 : w.reduce((a, b) => a + b, 0) / w.length;
+    }
+    getStalenessQueryCount() { return this.stalenessQueryCount; }
+    getGuardrailPassRate() {
+        if (this.guardrailEvaluationHistory.length === 0)
+            return 1;
+        return this.guardrailEvaluationHistory.filter(e => e.passed).length / this.guardrailEvaluationHistory.length;
+    }
+    invalidateStalenessCache() { this.stalenessCache.clear(); }
+    getDiagnostics() {
+        return {
+            ingestCount: this.ingestLatencyHistoryMs.length,
+            averageIngestLatencyMs: this.averageIngestLatencyMs(20),
+            recomputeCount: this.recomputeLatencyHistoryMs.length,
+            averageRecomputeLatencyMs: this.averageRecomputeLatencyMs(20),
+            stalenessQueryCount: this.stalenessQueryCount,
+            stalenessCacheSize: this.stalenessCache.size,
+            stalenessSnapshots: this.stalenessSnapshots.length,
+            freshnessTrend: this.getFreshnessTrend(10),
+            guardrailEvaluationCount: this.guardrailEvaluationHistory.length,
+            guardrailPassRate: Number((this.getGuardrailPassRate() * 100).toFixed(1)),
+        };
+    }
+    /**
+     * Build domain-level guardrail gates using ingest telemetry.
+     * These gates run independently of the platform's gate evaluation,
+     * providing a second layer of governance verification.
+     */
+    buildDomainGuardrailGates(request, platformResponse) {
+        const summary = this.latestIngestSummary || {};
+        const changedDocs = summary.changedDocuments ?? 0;
+        const deletedDocs = summary.deletedDocuments ?? 0;
+        const avgLatency = this.averageIngestLatencyMs(20);
+        return [
+            {
+                gateId: 'domain:changed_docs',
+                passed: changedDocs <= 500,
+                observedValue: changedDocs,
+                threshold: 500,
+                message: 'Changed document count within domain budget.',
+            },
+            {
+                gateId: 'domain:deleted_docs',
+                passed: deletedDocs <= 100,
+                observedValue: deletedDocs,
+                threshold: 100,
+                message: 'Deleted document count within rollback-safe budget.',
+            },
+            {
+                gateId: 'domain:avg_latency_ms',
+                passed: avgLatency <= 30000,
+                observedValue: Math.round(avgLatency),
+                threshold: 30000,
+                message: 'Average ingest latency within performance budget.',
+            },
+            {
+                gateId: 'domain:history_available',
+                passed: this.ingestLatencyHistoryMs.length >= 3,
+                observedValue: this.ingestLatencyHistoryMs.length,
+                threshold: 3,
+                message: 'Sufficient ingest history for statistical significance.',
+            },
+        ];
+    }
+    /**
+     * Build domain-level staleness analysis from platform response.
+     * Categorizes documents by staleness status and computes a freshness score.
+     */
+    buildStalenessAnalysis(response) {
+        const records = Array.isArray(response?.records) ? response.records : [];
+        const counters = { up_to_date: 0, hash_mismatch: 0, missing_source: 0, read_error: 0 };
+        const staleBySource = new Map();
+        let totalDocuments = 0;
+        for (const record of records) {
+            counters[record.status] = (counters[record.status] || 0) + 1;
+            totalDocuments++;
+            if (record.status !== 'up_to_date' && record.sourcePath) {
+                const dir = String(record.sourcePath).split(/[/\\]/)[0] || 'root';
+                staleBySource.set(dir, (staleBySource.get(dir) || 0) + 1);
+            }
+        }
+        const staleCount = counters.hash_mismatch + counters.missing_source + counters.read_error;
+        const freshnessScore = totalDocuments > 0
+            ? Number(((counters.up_to_date / totalDocuments) * 100).toFixed(1))
+            : 100;
+        return {
+            freshnessScore,
+            freshCount: counters.up_to_date,
+            staleCount,
+            hashMismatchCount: counters.hash_mismatch,
+            missingSourceCount: counters.missing_source,
+            readErrorCount: counters.read_error,
+            totalDocuments,
+            staleBySource: Object.fromEntries(staleBySource),
+            freshnessRating: freshnessScore >= 95 ? 'excellent' : freshnessScore >= 80 ? 'good' : freshnessScore >= 60 ? 'fair' : 'poor',
+        };
+    }
+    /**
+     * Record a staleness snapshot for trend computation.
+     * Keeps the last 100 snapshots for governance dashboards.
+     */
+    recordStalenessSnapshot(analysis) {
+        this.stalenessSnapshots.push({
+            generatedAt: new Date().toISOString(),
+            freshCount: analysis.freshCount,
+            staleCount: analysis.staleCount,
+            hashMismatchCount: analysis.hashMismatchCount,
+            freshnessScore: analysis.freshnessScore,
+        });
+        if (this.stalenessSnapshots.length > 100) {
+            this.stalenessSnapshots.shift();
+        }
+    }
+    /**
+     * Compute the freshness trend over the last N snapshots.
+     * Returns trend direction: 'stable', 'improving', or 'regressing'.
+     */
+    getFreshnessTrend(n = 10) {
+        const window = this.stalenessSnapshots.slice(-n);
+        if (window.length < 2)
+            return { direction: 'stable', recentScore: window[0]?.freshnessScore ?? 100, windowAverage: window[0]?.freshnessScore ?? 100, snapshots: window.length };
+        const recentScore = window[window.length - 1].freshnessScore;
+        const windowAverage = Number((window.reduce((s, e) => s + e.freshnessScore, 0) / window.length).toFixed(1));
+        // Compare recent half vs earlier half
+        const mid = Math.floor(window.length / 2);
+        const recentHalf = window.slice(-mid);
+        const earlierHalf = window.slice(0, mid);
+        const recentAvg = recentHalf.reduce((s, e) => s + e.freshnessScore, 0) / recentHalf.length;
+        const earlierAvg = earlierHalf.reduce((s, e) => s + e.freshnessScore, 0) / earlierHalf.length;
+        const delta = recentAvg - earlierAvg;
+        return {
+            direction: delta > 2 ? 'improving' : delta < -2 ? 'regressing' : 'stable',
+            recentScore,
+            windowAverage,
+            snapshots: window.length,
+        };
+    }
+    getStalenessSnapshots() { return [...this.stalenessSnapshots]; }
+    buildStalenessCacheKey(request) {
+        return [request?.limit ?? 24, request?.sourcePathPrefix ?? '', Array.isArray(request?.statuses) ? request.statuses.join(',') : ''].join('|');
+    }
+}
+exports.KnowledgeIngestor = KnowledgeIngestor;

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

@@ -0,0 +1,187 @@
+"use strict";
+/**
+ * KnowledgeQuerier domain — L2: Evidence-first explainable retrieval.
+ * Query backends, comparison, configuration, diagnostics.
+ * Note: types pending M8-M10 stabilization; using any for now.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KnowledgeQuerier = void 0;
+class KnowledgeQuerier {
+    constructor(platform, options) {
+        this.platform = platform;
+        this.queryLatencyHistoryMs = [];
+        this.queryBackendFallbackCount = 0;
+        this.lastQueryAt = null;
+        this.queryCache = new Map();
+        this.cacheHits = 0;
+        this.cacheMisses = 0;
+        this.comparisonCount = 0;
+        this.queryPatternCounts = new Map();
+        this.slowQueryCount = 0;
+        this.cacheTtlMs = options?.cacheTtlMs ?? 60000;
+    }
+    async queryKnowledge(request, options) {
+        this.lastQueryAt = new Date().toISOString();
+        const cacheKey = this.buildCacheKey(request);
+        const cached = !options?.skipCache ? this.queryCache.get(cacheKey) : undefined;
+        if (cached && (Date.now() - new Date(cached.cachedAt).getTime()) < cached.ttlMs) {
+            this.cacheHits++;
+            return cached.response;
+        }
+        // Domain-level query validation
+        this.validateQueryRequest(request);
+        this.cacheMisses++;
+        const startMs = Date.now();
+        try {
+            const response = await this.platform.queryKnowledge(request);
+            const latencyMs = Date.now() - startMs;
+            this.recordLatency(latencyMs);
+            this.queryCache.set(cacheKey, { response, cachedAt: new Date().toISOString(), ttlMs: this.cacheTtlMs });
+            this.pruneCache();
+            // Track query pattern for analytics
+            this.trackQueryPattern(String(request?.query ?? '').toLowerCase());
+            // Augment response with domain-level telemetry
+            return this.augmentQueryResponse(response, latencyMs, request);
+        }
+        catch (error) {
+            this.queryBackendFallbackCount++;
+            this.queryBackendLastError = String(error);
+            throw error;
+        }
+    }
+    async compareBackends(request) { this.comparisonCount++; return this.platform.compareQueryBackends(request); }
+    async queryComparisonHistory(request) { return this.platform.queryKnowledgeQueryBackendComparisonHistory(request); }
+    async queryComparisonTrend(request) { return this.platform.queryKnowledgeQueryBackendComparisonTrend(request); }
+    getConfig() { return this.platform.getQueryBackendConfig(); }
+    async updateConfig(request) {
+        const response = await this.platform.updateQueryBackendConfig(request);
+        this.invalidateCache();
+        return response;
+    }
+    getDiagnostics() { return this.platform.getQueryBackendDiagnostics(); }
+    invalidateCache() { this.queryCache.clear(); }
+    getQueryLatencyHistory() { return [...this.queryLatencyHistoryMs]; }
+    getFallbackCount() { return this.queryBackendFallbackCount; }
+    getLastError() { return this.queryBackendLastError; }
+    averageQueryLatencyMs(n = 20) {
+        const w = this.queryLatencyHistoryMs.slice(-n);
+        if (w.length === 0)
+            return 0;
+        return w.reduce((a, b) => a + b, 0) / w.length;
+    }
+    queryLatencyP95(n = 50) {
+        const w = [...this.queryLatencyHistoryMs.slice(-n)].sort((a, b) => a - b);
+        if (w.length === 0)
+            return 0;
+        return w[Math.ceil(w.length * 0.95) - 1];
+    }
+    getCacheHitRate() {
+        const total = this.cacheHits + this.cacheMisses;
+        return total === 0 ? 0 : this.cacheHits / total;
+    }
+    getDiagnosticsSummary() {
+        const topQueries = [...this.queryPatternCounts.entries()]
+            .sort((a, b) => b[1] - a[1])
+            .slice(0, 10)
+            .map(([term, count]) => ({ term, count }));
+        return {
+            queryCount: this.queryLatencyHistoryMs.length,
+            averageLatencyMs: this.averageQueryLatencyMs(20),
+            latencyP95Ms: this.queryLatencyP95(50),
+            latencyP99Ms: this.queryLatencyP99(100),
+            fallbackCount: this.queryBackendFallbackCount,
+            lastError: this.queryBackendLastError ?? null,
+            lastQueryAt: this.lastQueryAt,
+            cacheSize: this.queryCache.size,
+            cacheHitRate: Number((this.getCacheHitRate() * 100).toFixed(1)),
+            comparisonCount: this.comparisonCount,
+            slowQueryCount: this.slowQueryCount,
+            uniqueQueryTerms: this.queryPatternCounts.size,
+            topQueryTerms: topQueries,
+        };
+    }
+    queryLatencyP99(n = 100) {
+        const w = [...this.queryLatencyHistoryMs.slice(-n)].sort((a, b) => a - b);
+        if (w.length === 0)
+            return 0;
+        return w[Math.ceil(w.length * 0.99) - 1];
+    }
+    recordLatency(ms) {
+        this.queryLatencyHistoryMs.push(ms);
+        if (this.queryLatencyHistoryMs.length > 500)
+            this.queryLatencyHistoryMs.shift();
+    }
+    /** Track query term frequency for pattern analysis. */
+    trackQueryPattern(query) {
+        if (!query)
+            return;
+        const terms = query.split(/\s+/).filter(t => t.length > 2);
+        for (const term of terms) {
+            this.queryPatternCounts.set(term, (this.queryPatternCounts.get(term) || 0) + 1);
+        }
+        // Prune to top 200 terms
+        if (this.queryPatternCounts.size > 200) {
+            const sorted = [...this.queryPatternCounts.entries()].sort((a, b) => b[1] - a[1]);
+            this.queryPatternCounts = new Map(sorted.slice(0, 150));
+        }
+    }
+    /** Mark a query as slow (exceeds latency threshold). */
+    markSlowQuery(latencyMs) {
+        const p95 = this.queryLatencyP95(50);
+        if (p95 > 0 && latencyMs > p95 * 2) {
+            this.slowQueryCount++;
+        }
+    }
+    buildCacheKey(request) {
+        return [request.query ?? '', String(request.topK ?? 10), request.queryBackend ?? 'default', request.asOf ?? ''].join('|');
+    }
+    /**
+     * Domain-level query validation: ensure the request meets minimum
+     * quality standards before dispatching to the platform.
+     */
+    validateQueryRequest(request) {
+        if (!request) {
+            throw new Error('Query request is required.');
+        }
+        const query = String(request.query ?? '').trim();
+        if (!query) {
+            throw new Error('Query string must not be empty.');
+        }
+        if (query.length > 5000) {
+            throw new Error('Query string exceeds maximum length (5000 chars).');
+        }
+    }
+    /**
+     * Augment the platform response with domain-level telemetry:
+     * query latency, cache status, backend identity, and result metadata.
+     */
+    augmentQueryResponse(response, latencyMs, request) {
+        const items = Array.isArray(response?.items) ? response.items : [];
+        return {
+            ...response,
+            _domain: {
+                latencyMs: Math.round(latencyMs),
+                cacheHit: false,
+                cacheSize: this.queryCache.size,
+                backend: request?.queryBackend ?? 'default',
+                resultCount: items.length,
+                topScore: items.length > 0 ? items[0]?.score ?? null : null,
+            },
+        };
+    }
+    pruneCache() {
+        if (this.queryCache.size <= 200)
+            return;
+        const now = Date.now();
+        for (const [key, entry] of this.queryCache) {
+            if ((now - new Date(entry.cachedAt).getTime()) > entry.ttlMs * 2)
+                this.queryCache.delete(key);
+        }
+        if (this.queryCache.size > 200) {
+            const firstKey = this.queryCache.keys().next().value;
+            if (firstKey)
+                this.queryCache.delete(firstKey);
+        }
+    }
+}
+exports.KnowledgeQuerier = KnowledgeQuerier;