contradiction-mcp 0.1.0

package/dist/intelligence/entityResolver.js

@@ -0,0 +1,152 @@
+export class EntityResolver {
+    defaultAliases = new Map();
+    constructor() {
+        this.registerDefaultAliases();
+    }
+    registerDefaultAliases() {
+        const aliasGroups = [
+            ['api', 'api-server', 'backend', 'api_service', 'core-api'],
+            ['frontend', 'web', 'ui', 'client', 'web-app', 'webapp'],
+            ['gateway', 'api-gateway', 'platform-gateway-service', 'ingress'],
+            ['auth', 'authentication', 'auth-service', 'idp', 'identity'],
+            ['db', 'database', 'postgres', 'postgresql', 'mysql', 'sqlite'],
+        ];
+        for (const group of aliasGroups) {
+            const set = new Set(group.map((s) => this.normalize(s)));
+            for (const item of group) {
+                this.defaultAliases.set(this.normalize(item), set);
+            }
+        }
+    }
+    /**
+     * Canonicalizes an entity name by stripping delimiters, common redundant words, and casing.
+     */
+    normalize(raw) {
+        if (!raw)
+            return '';
+        return raw
+            .trim()
+            .toLowerCase()
+            .replace(/^(@[a-z0-9_-]+\/)/i, '') // strip npm scopes
+            .replace(/^(https?:\/\/)?(www\.)?/i, '') // strip web protocols
+            .replace(/[._\-\s/]+/g, '') // remove separators
+            .replace(/(service|server|daemon|app|application|client|pkg|package)$/i, ''); // strip redundant noun suffixes
+    }
+    /**
+     * Compares two entity references across sources.
+     */
+    resolveEntityMatch(entityA, entityB, options) {
+        const rawA = (entityA || '').trim();
+        const rawB = (entityB || '').trim();
+        if (!rawA || !rawB) {
+            return {
+                isMatch: false,
+                confidence: 0.0,
+                matchType: 'NONE',
+                reason: 'Empty entity string provided',
+                isAmbiguous: false,
+            };
+        }
+        // 1. Exact string match
+        if (rawA === rawB) {
+            return {
+                isMatch: true,
+                confidence: 1.0,
+                matchType: 'EXACT',
+                reason: 'Exact verbatim entity name match',
+                isAmbiguous: false,
+            };
+        }
+        // 2. Exact case-insensitive match
+        if (rawA.toLowerCase() === rawB.toLowerCase()) {
+            return {
+                isMatch: true,
+                confidence: 0.98,
+                matchType: 'EXACT',
+                reason: 'Exact case-insensitive match',
+                isAmbiguous: false,
+            };
+        }
+        // 3. Normalized representation match
+        const normA = this.normalize(rawA);
+        const normB = this.normalize(rawB);
+        if (normA && normB && normA === normB) {
+            return {
+                isMatch: true,
+                confidence: 0.92,
+                matchType: 'NORMALIZED',
+                reason: `Normalized representations match ('${normA}')`,
+                isAmbiguous: false,
+            };
+        }
+        // 4. Custom & Built-in Aliases check
+        if (options?.customAliases) {
+            for (const [key, aliases] of Object.entries(options.customAliases)) {
+                const normKey = this.normalize(key);
+                const normAliases = aliases.map((a) => this.normalize(a));
+                const all = [normKey, ...normAliases];
+                if (all.includes(normA) && all.includes(normB)) {
+                    return {
+                        isMatch: true,
+                        confidence: 0.95,
+                        matchType: 'ALIAS',
+                        reason: `Matched via custom configured alias group '${key}'`,
+                        isAmbiguous: false,
+                    };
+                }
+            }
+        }
+        const defaultSetA = this.defaultAliases.get(normA);
+        if (defaultSetA && defaultSetA.has(normB)) {
+            return {
+                isMatch: true,
+                confidence: 0.88,
+                matchType: 'ALIAS',
+                reason: 'Matched via standard industry service alias dictionary',
+                isAmbiguous: false,
+            };
+        }
+        // 5. Substring / Prefix / Suffix inclusion with caution
+        if (normA.length >= 4 && normB.length >= 4) {
+            if (normA.includes(normB) || normB.includes(normA)) {
+                const ratio = Math.min(normA.length, normB.length) / Math.max(normA.length, normB.length);
+                if (ratio >= 0.6) {
+                    return {
+                        isMatch: true,
+                        confidence: Number((0.7 + ratio * 0.15).toFixed(2)),
+                        matchType: 'SUFFIX_PREFIX',
+                        reason: `Significant component substring overlap ('${normA}' and '${normB}')`,
+                        isAmbiguous: ratio < 0.75,
+                    };
+                }
+            }
+        }
+        // No confident match
+        return {
+            isMatch: false,
+            confidence: 0.1,
+            matchType: 'NONE',
+            reason: `Entities '${rawA}' and '${rawB}' do not correspond deterministically`,
+            isAmbiguous: false,
+        };
+    }
+    /**
+     * Evaluates query against multiple candidate entities, sorting by confidence.
+     */
+    findMatches(query, candidates, options) {
+        const minThreshold = options?.minConfidenceThreshold ?? 0.7;
+        const matches = [];
+        for (const candidate of candidates) {
+            const res = this.resolveEntityMatch(query, candidate, options);
+            if (res.isMatch && res.confidence >= minThreshold) {
+                matches.push({
+                    candidate,
+                    confidence: res.confidence,
+                    matchType: res.matchType,
+                });
+            }
+        }
+        return matches.sort((a, b) => b.confidence - a.confidence);
+    }
+}
+//# sourceMappingURL=entityResolver.js.map

package/dist/intelligence/entityResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entityResolver.js","sourceRoot":"","sources":["../../src/intelligence/entityResolver.ts"],"names":[],"mappings":"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"}

package/dist/intelligence/evidenceEvaluator.d.ts

@@ -0,0 +1,15 @@
+import { Claim } from '../domain/entities/claim.js';
+export interface EvidenceQualityResult {
+    quality: 'STRONG' | 'MODERATE' | 'WEAK' | 'INDIRECT';
+    score: number;
+    hasLineProvenance: boolean;
+    hasVerbatimSnippet: boolean;
+    extractionMethod: string;
+    reasons: string[];
+}
+export declare class EvidenceEvaluator {
+    /**
+     * Assesses the empirical solidity and verifiable directness of a claim's evidence.
+     */
+    evaluateEvidence(claim: Claim): EvidenceQualityResult;
+}

package/dist/intelligence/evidenceEvaluator.js

@@ -0,0 +1,63 @@
+export class EvidenceEvaluator {
+    /**
+     * Assesses the empirical solidity and verifiable directness of a claim's evidence.
+     */
+    evaluateEvidence(claim) {
+        const reasons = [];
+        let score = 0.4;
+        const metadata = claim.metadata || {};
+        const snippet = typeof metadata.snippet === 'string' ? metadata.snippet.trim() : '';
+        const hasSnippet = snippet.length > 0;
+        const hasLine = metadata.line !== undefined ||
+            (metadata.startLine !== undefined && metadata.endLine !== undefined);
+        const extractionMethod = typeof metadata.extractionMethod === 'string' ? metadata.extractionMethod : 'heuristic';
+        if (hasLine) {
+            score += 0.25;
+            const lineStr = metadata.line !== undefined
+                ? `line ${metadata.line}`
+                : `lines ${metadata.startLine}-${metadata.endLine}`;
+            reasons.push(`Claim verified with exact line provenance: ${lineStr}`);
+        }
+        else {
+            reasons.push('Claim lacks exact line number citation');
+        }
+        if (hasSnippet) {
+            score += 0.25;
+            reasons.push(`Claim includes verbatim source snippet (${snippet.length} chars)`);
+        }
+        else {
+            reasons.push('No textual evidence snippet captured');
+        }
+        if (extractionMethod === 'json_parse' || extractionMethod === 'ast') {
+            score += 0.1;
+            reasons.push(`Structured deterministic extraction method: ${extractionMethod}`);
+        }
+        else if (extractionMethod === 'regex' || extractionMethod === 'yaml_parse') {
+            score += 0.05;
+            reasons.push(`Pattern-based extraction method: ${extractionMethod}`);
+        }
+        score = Math.min(1.0, score);
+        let quality;
+        if (score >= 0.8) {
+            quality = 'STRONG';
+        }
+        else if (score >= 0.6) {
+            quality = 'MODERATE';
+        }
+        else if (score >= 0.4) {
+            quality = 'WEAK';
+        }
+        else {
+            quality = 'INDIRECT';
+        }
+        return {
+            quality,
+            score: Number(score.toFixed(2)),
+            hasLineProvenance: hasLine,
+            hasVerbatimSnippet: hasSnippet,
+            extractionMethod,
+            reasons,
+        };
+    }
+}
+//# sourceMappingURL=evidenceEvaluator.js.map

package/dist/intelligence/evidenceEvaluator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidenceEvaluator.js","sourceRoot":"","sources":["../../src/intelligence/evidenceEvaluator.ts"],"names":[],"mappings":"AAWA,MAAM,OAAO,iBAAiB;IAC5B;;OAEG;IACI,gBAAgB,CAAC,KAAY;QAClC,MAAM,OAAO,GAAa,EAAE,CAAC;QAC7B,IAAI,KAAK,GAAG,GAAG,CAAC;QAEhB,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;QACtC,MAAM,OAAO,GAAG,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpF,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QACtC,MAAM,OAAO,GACX,QAAQ,CAAC,IAAI,KAAK,SAAS;YAC3B,CAAC,QAAQ,CAAC,SAAS,KAAK,SAAS,IAAI,QAAQ,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC;QAEvE,MAAM,gBAAgB,GACpB,OAAO,QAAQ,CAAC,gBAAgB,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,WAAW,CAAC;QAE1F,IAAI,OAAO,EAAE,CAAC;YACZ,KAAK,IAAI,IAAI,CAAC;YACd,MAAM,OAAO,GACX,QAAQ,CAAC,IAAI,KAAK,SAAS;gBACzB,CAAC,CAAC,QAAQ,QAAQ,CAAC,IAAI,EAAE;gBACzB,CAAC,CAAC,SAAS,QAAQ,CAAC,SAAS,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;YACxD,OAAO,CAAC,IAAI,CAAC,8CAA8C,OAAO,EAAE,CAAC,CAAC;QACxE,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,wCAAwC,CAAC,CAAC;QACzD,CAAC;QAED,IAAI,UAAU,EAAE,CAAC;YACf,KAAK,IAAI,IAAI,CAAC;YACd,OAAO,CAAC,IAAI,CAAC,2CAA2C,OAAO,CAAC,MAAM,SAAS,CAAC,CAAC;QACnF,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;QACvD,CAAC;QAED,IAAI,gBAAgB,KAAK,YAAY,IAAI,gBAAgB,KAAK,KAAK,EAAE,CAAC;YACpE,KAAK,IAAI,GAAG,CAAC;YACb,OAAO,CAAC,IAAI,CAAC,+CAA+C,gBAAgB,EAAE,CAAC,CAAC;QAClF,CAAC;aAAM,IAAI,gBAAgB,KAAK,OAAO,IAAI,gBAAgB,KAAK,YAAY,EAAE,CAAC;YAC7E,KAAK,IAAI,IAAI,CAAC;YACd,OAAO,CAAC,IAAI,CAAC,oCAAoC,gBAAgB,EAAE,CAAC,CAAC;QACvE,CAAC;QAED,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;QAE7B,IAAI,OAAoD,CAAC;QACzD,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;YACjB,OAAO,GAAG,QAAQ,CAAC;QACrB,CAAC;aAAM,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;YACxB,OAAO,GAAG,UAAU,CAAC;QACvB,CAAC;aAAM,IAAI,KAAK,IAAI,GAAG,EAAE,CAAC;YACxB,OAAO,GAAG,MAAM,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,OAAO,GAAG,UAAU,CAAC;QACvB,CAAC;QAED,OAAO;YACL,OAAO;YACP,KAAK,EAAE,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;YAC/B,iBAAiB,EAAE,OAAO;YAC1B,kBAAkB,EAAE,UAAU;YAC9B,gBAAgB;YAChB,OAAO;SACR,CAAC;IACJ,CAAC;CACF"}

package/dist/intelligence/freshnessScorer.d.ts

@@ -0,0 +1,25 @@
+import { Claim } from '../domain/entities/claim.js';
+import { Source } from '../domain/entities/source.js';
+export interface FreshnessScoreResult {
+    score: number;
+    observedAgeDays: number;
+    isHistorical: boolean;
+    reasoning: string[];
+}
+export declare class FreshnessScorer {
+    /**
+     * Evaluates the recency and temporal validity of a claim.
+     * Employs an exponential decay heuristic calibrated over days.
+     */
+    scoreFreshness(claim: Claim, source?: Source | null, referenceDate?: Date): FreshnessScoreResult;
+    /**
+     * Compares the freshness of two claims directly.
+     */
+    compareFreshness(claimA: Claim, claimB: Claim, sourceA?: Source | null, sourceB?: Source | null, referenceDate?: Date): {
+        winner: 'claimA' | 'claimB' | 'tie';
+        claimAScore: number;
+        claimBScore: number;
+        differenceDays: number;
+        reason: string;
+    };
+}

package/dist/intelligence/freshnessScorer.js

@@ -0,0 +1,90 @@
+export class FreshnessScorer {
+    /**
+     * Evaluates the recency and temporal validity of a claim.
+     * Employs an exponential decay heuristic calibrated over days.
+     */
+    scoreFreshness(claim, source, referenceDate = new Date()) {
+        const reasoning = [];
+        const refMs = referenceDate.getTime();
+        // 1. Historical flag penalty
+        if (claim.isHistorical) {
+            reasoning.push('Claim explicitly flagged as historical (freshness penalty: 0.10 baseline)');
+            return {
+                score: 0.1,
+                observedAgeDays: Math.max(0, (refMs - claim.observedAt.getTime()) / (1000 * 60 * 60 * 24)),
+                isHistorical: true,
+                reasoning,
+            };
+        }
+        // 2. Temporal validity window check
+        if (claim.validUntil && claim.validUntil.getTime() < refMs) {
+            reasoning.push(`Claim validity expired on ${claim.validUntil.toISOString()} (freshness penalty: 0.15 baseline)`);
+            return {
+                score: 0.15,
+                observedAgeDays: Math.max(0, (refMs - claim.observedAt.getTime()) / (1000 * 60 * 60 * 24)),
+                isHistorical: false,
+                reasoning,
+            };
+        }
+        // 3. Observed Age Decay
+        // Compare observation time and source last fetched time
+        const effectiveTime = source?.lastFetchedAt
+            ? Math.max(claim.observedAt.getTime(), source.lastFetchedAt.getTime())
+            : claim.observedAt.getTime();
+        const ageMs = Math.max(0, refMs - effectiveTime);
+        const ageDays = ageMs / (1000 * 60 * 60 * 24);
+        // Half-life model: score = exp(-0.693 * ageDays / halfLifeDays)
+        // 180 days half-life for technical documentation & runtime assertions
+        const halfLifeDays = 180;
+        let baseFreshness = Math.exp((-0.693 * ageDays) / halfLifeDays);
+        baseFreshness = Math.max(0.2, Math.min(1.0, baseFreshness));
+        reasoning.push(`Observed age: ${ageDays.toFixed(1)} days ago (base freshness: ${baseFreshness.toFixed(2)})`);
+        // 4. Boost if validFrom is explicit and active
+        if (claim.validFrom && claim.validFrom.getTime() <= refMs) {
+            baseFreshness = Math.min(1.0, baseFreshness + 0.05);
+            reasoning.push(`Active validity window starting ${claim.validFrom.toISOString()}`);
+        }
+        const score = Number(baseFreshness.toFixed(4));
+        return {
+            score,
+            observedAgeDays: Number(ageDays.toFixed(1)),
+            isHistorical: false,
+            reasoning,
+        };
+    }
+    /**
+     * Compares the freshness of two claims directly.
+     */
+    compareFreshness(claimA, claimB, sourceA, sourceB, referenceDate = new Date()) {
+        const freshA = this.scoreFreshness(claimA, sourceA, referenceDate);
+        const freshB = this.scoreFreshness(claimB, sourceB, referenceDate);
+        const diffDays = Math.abs(freshA.observedAgeDays - freshB.observedAgeDays);
+        const scoreDiff = freshA.score - freshB.score;
+        if (Math.abs(scoreDiff) < 0.05) {
+            return {
+                winner: 'tie',
+                claimAScore: freshA.score,
+                claimBScore: freshB.score,
+                differenceDays: diffDays,
+                reason: `Both claims have comparable temporal freshness (scores: ${freshA.score.toFixed(2)} vs ${freshB.score.toFixed(2)})`,
+            };
+        }
+        if (freshA.score > freshB.score) {
+            return {
+                winner: 'claimA',
+                claimAScore: freshA.score,
+                claimBScore: freshB.score,
+                differenceDays: diffDays,
+                reason: `Claim A is fresher (${freshA.observedAgeDays.toFixed(0)}d old vs ${freshB.observedAgeDays.toFixed(0)}d old)`,
+            };
+        }
+        return {
+            winner: 'claimB',
+            claimAScore: freshA.score,
+            claimBScore: freshB.score,
+            differenceDays: diffDays,
+            reason: `Claim B is fresher (${freshB.observedAgeDays.toFixed(0)}d old vs ${freshA.observedAgeDays.toFixed(0)}d old)`,
+        };
+    }
+}
+//# sourceMappingURL=freshnessScorer.js.map

package/dist/intelligence/freshnessScorer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshnessScorer.js","sourceRoot":"","sources":["../../src/intelligence/freshnessScorer.ts"],"names":[],"mappings":"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"}

package/dist/intelligence/provenanceAnalyzer.d.ts

@@ -0,0 +1,19 @@
+import { Claim } from '../domain/entities/claim.js';
+import { Source } from '../domain/entities/source.js';
+export interface ProvenanceTrace {
+    sourceId: string;
+    sourceType: string;
+    sourceName: string;
+    sourceUri?: string | null;
+    filePath?: string | null;
+    commitHash?: string | null;
+    observedAt: Date;
+    isTraceable: boolean;
+    summary: string;
+}
+export declare class ProvenanceAnalyzer {
+    /**
+     * Traces and validates the chain of custody for a given claim.
+     */
+    analyzeProvenance(claim: Claim, source?: Source | null): ProvenanceTrace;
+}

package/dist/intelligence/provenanceAnalyzer.js

@@ -0,0 +1,33 @@
+export class ProvenanceAnalyzer {
+    /**
+     * Traces and validates the chain of custody for a given claim.
+     */
+    analyzeProvenance(claim, source) {
+        const metadata = claim.metadata || {};
+        const filePath = typeof metadata.filePath === 'string' ? metadata.filePath : null;
+        const commitHash = typeof metadata.commitSha === 'string'
+            ? metadata.commitSha
+            : typeof metadata.commit === 'string'
+                ? metadata.commit
+                : null;
+        const sourceUri = source?.uri || (typeof metadata.uri === 'string' ? metadata.uri : null);
+        const isTraceable = Boolean(source && (sourceUri || filePath));
+        const locationDesc = filePath ? ` at ${filePath}` : sourceUri ? ` at ${sourceUri}` : '';
+        const commitDesc = commitHash ? ` (rev ${commitHash.substring(0, 7)})` : '';
+        const summary = source
+            ? `Extracted from ${source.type} source '${source.name}'${locationDesc}${commitDesc}, observed ${claim.observedAt.toISOString()}`
+            : `Unlinked claim observed ${claim.observedAt.toISOString()}`;
+        return {
+            sourceId: claim.sourceId,
+            sourceType: source?.type || 'unknown',
+            sourceName: source?.name || 'unknown',
+            sourceUri,
+            filePath,
+            commitHash,
+            observedAt: claim.observedAt,
+            isTraceable,
+            summary,
+        };
+    }
+}
+//# sourceMappingURL=provenanceAnalyzer.js.map

package/dist/intelligence/provenanceAnalyzer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provenanceAnalyzer.js","sourceRoot":"","sources":["../../src/intelligence/provenanceAnalyzer.ts"],"names":[],"mappings":"AAeA,MAAM,OAAO,kBAAkB;IAC7B;;OAEG;IACI,iBAAiB,CAAC,KAAY,EAAE,MAAsB;QAC3D,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC;QACtC,MAAM,QAAQ,GAAG,OAAO,QAAQ,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC;QAClF,MAAM,UAAU,GACd,OAAO,QAAQ,CAAC,SAAS,KAAK,QAAQ;YACpC,CAAC,CAAC,QAAQ,CAAC,SAAS;YACpB,CAAC,CAAC,OAAO,QAAQ,CAAC,MAAM,KAAK,QAAQ;gBACnC,CAAC,CAAC,QAAQ,CAAC,MAAM;gBACjB,CAAC,CAAC,IAAI,CAAC;QAEb,MAAM,SAAS,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,OAAO,QAAQ,CAAC,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAC1F,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,IAAI,CAAC,SAAS,IAAI,QAAQ,CAAC,CAAC,CAAC;QAE/D,MAAM,YAAY,GAAG,QAAQ,CAAC,CAAC,CAAC,OAAO,QAAQ,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxF,MAAM,UAAU,GAAG,UAAU,CAAC,CAAC,CAAC,SAAS,UAAU,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;QAE5E,MAAM,OAAO,GAAG,MAAM;YACpB,CAAC,CAAC,kBAAkB,MAAM,CAAC,IAAI,YAAY,MAAM,CAAC,IAAI,IAAI,YAAY,GAAG,UAAU,cAAc,KAAK,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE;YACjI,CAAC,CAAC,2BAA2B,KAAK,CAAC,UAAU,CAAC,WAAW,EAAE,EAAE,CAAC;QAEhE,OAAO;YACL,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,UAAU,EAAE,MAAM,EAAE,IAAI,IAAI,SAAS;YACrC,UAAU,EAAE,MAAM,EAAE,IAAI,IAAI,SAAS;YACrC,SAAS;YACT,QAAQ;YACR,UAAU;YACV,UAAU,EAAE,KAAK,CAAC,UAAU;YAC5B,WAAW;YACX,OAAO;SACR,CAAC;IACJ,CAAC;CACF"}

package/dist/intelligence/resolutionAdvisor.d.ts

@@ -0,0 +1,40 @@
+import { Claim } from '../domain/entities/claim.js';
+import { Source } from '../domain/entities/source.js';
+import { Contradiction } from '../domain/entities/contradiction.js';
+import { AuthorityScoreResult } from './authorityScorer.js';
+import { FreshnessScoreResult } from './freshnessScorer.js';
+import { EvidenceQualityResult } from './evidenceEvaluator.js';
+export interface ResolutionAdvice {
+    likelyCurrentClaim: 'claimA' | 'claimB' | 'neither' | 'uncertain';
+    confidence: number;
+    recommendedAction: string;
+    reason: string;
+    authorityComparison: {
+        claimAScore: number;
+        claimBScore: number;
+        winner: 'claimA' | 'claimB' | 'tie';
+        details: AuthorityScoreResult;
+    };
+    freshnessComparison: {
+        claimAScore: number;
+        claimBScore: number;
+        winner: 'claimA' | 'claimB' | 'tie';
+        details: FreshnessScoreResult;
+    };
+    evidenceComparison: {
+        claimAQuality: EvidenceQualityResult;
+        claimBQuality: EvidenceQualityResult;
+    };
+    remainingUncertainty: string[];
+}
+export declare class ResolutionAdvisor {
+    private readonly authorityScorer;
+    private readonly freshnessScorer;
+    private readonly evidenceEvaluator;
+    constructor();
+    /**
+     * Generates comprehensive advisory recommendation for resolving a contradiction.
+     * Advisory-only; does not mutate external or database state.
+     */
+    adviseResolution(contradiction: Contradiction, claimA: Claim, claimB: Claim, sourceA?: Source | null, sourceB?: Source | null): ResolutionAdvice;
+}

package/dist/intelligence/resolutionAdvisor.js

@@ -0,0 +1,118 @@
+import { AuthorityScorer } from './authorityScorer.js';
+import { FreshnessScorer } from './freshnessScorer.js';
+import { EvidenceEvaluator } from './evidenceEvaluator.js';
+export class ResolutionAdvisor {
+    authorityScorer;
+    freshnessScorer;
+    evidenceEvaluator;
+    constructor() {
+        this.authorityScorer = new AuthorityScorer();
+        this.freshnessScorer = new FreshnessScorer();
+        this.evidenceEvaluator = new EvidenceEvaluator();
+    }
+    /**
+     * Generates comprehensive advisory recommendation for resolving a contradiction.
+     * Advisory-only; does not mutate external or database state.
+     */
+    adviseResolution(contradiction, claimA, claimB, sourceA, sourceB) {
+        const authA = this.authorityScorer.scoreAuthority(claimA, sourceA);
+        const authB = this.authorityScorer.scoreAuthority(claimB, sourceB);
+        const freshA = this.freshnessScorer.scoreFreshness(claimA, sourceA);
+        const freshB = this.freshnessScorer.scoreFreshness(claimB, sourceB);
+        const evidA = this.evidenceEvaluator.evaluateEvidence(claimA);
+        const evidB = this.evidenceEvaluator.evaluateEvidence(claimB);
+        const remainingUncertainty = [];
+        // Authority comparison
+        const authDiff = authA.score - authB.score;
+        const authWinner = Math.abs(authDiff) < 0.08 ? 'tie' : authDiff > 0 ? 'claimA' : 'claimB';
+        // Freshness comparison
+        const freshDiff = freshA.score - freshB.score;
+        const freshWinner = Math.abs(freshDiff) < 0.08 ? 'tie' : freshDiff > 0 ? 'claimA' : 'claimB';
+        let likelyCurrentClaim;
+        let confidence;
+        let recommendedAction = 'Review both sources manually before updating.';
+        let reason = 'Both claims exhibit similar authority and freshness levels.';
+        if (authWinner === 'claimA' && (freshWinner === 'claimA' || freshWinner === 'tie')) {
+            likelyCurrentClaim = 'claimA';
+            confidence = Math.min(0.95, Number((0.6 + Math.abs(authDiff) * 0.4).toFixed(2)));
+            reason = `Claim A represents a higher-confidence candidate for current truth because it carries higher operational authority (${authA.score.toFixed(2)} vs ${authB.score.toFixed(2)}) and is at least as fresh.`;
+            recommendedAction = `Accept Claim A ('${claimA.value}') and update the conflicting source '${sourceB?.name || claimB.sourceId}'.`;
+        }
+        else if (authWinner === 'claimB' && (freshWinner === 'claimB' || freshWinner === 'tie')) {
+            likelyCurrentClaim = 'claimB';
+            confidence = Math.min(0.95, Number((0.6 + Math.abs(authDiff) * 0.4).toFixed(2)));
+            reason = `Claim B represents a higher-confidence candidate for current truth because it carries higher operational authority (${authB.score.toFixed(2)} vs ${authA.score.toFixed(2)}) and is at least as fresh.`;
+            recommendedAction = `Accept Claim B ('${claimB.value}') and update the conflicting source '${sourceA?.name || claimA.sourceId}'.`;
+        }
+        else if (authWinner === 'claimA' && freshWinner === 'claimB') {
+            // Conflict between authority and recency
+            if (authA.score >= 0.85 &&
+                (claimB.sourceRole === 'documentation' || claimB.sourceRole === 'example')) {
+                likelyCurrentClaim = 'claimA';
+                confidence = 0.72;
+                reason = `Claim A is operational configuration with high authority (${authA.score.toFixed(2)}), outweighing the more recent documentation claim B.`;
+                recommendedAction = `Verify whether documentation in '${sourceB?.name || 'source B'}' is outdated or describes a future planned version.`;
+            }
+            else {
+                likelyCurrentClaim = 'uncertain';
+                confidence = 0.45;
+                reason = `Trade-off detected: Claim A has higher authority (${authA.score.toFixed(2)}) but Claim B is significantly more recent (${freshB.score.toFixed(2)}).`;
+                remainingUncertainty.push('Authority and freshness indicators favor opposing claims.');
+                recommendedAction =
+                    'Investigate git commit history or deploy logs to confirm whether Claim B represents a deliberate recent migration.';
+            }
+        }
+        else if (authWinner === 'claimB' && freshWinner === 'claimA') {
+            if (authB.score >= 0.85 &&
+                (claimA.sourceRole === 'documentation' || claimA.sourceRole === 'example')) {
+                likelyCurrentClaim = 'claimB';
+                confidence = 0.72;
+                reason = `Claim B is operational configuration with high authority (${authB.score.toFixed(2)}), outweighing the more recent documentation claim A.`;
+                recommendedAction = `Verify whether documentation in '${sourceA?.name || 'source A'}' is outdated or describes a future planned version.`;
+            }
+            else {
+                likelyCurrentClaim = 'uncertain';
+                confidence = 0.45;
+                reason = `Trade-off detected: Claim B has higher authority (${authB.score.toFixed(2)}) but Claim A is significantly more recent (${freshA.score.toFixed(2)}).`;
+                remainingUncertainty.push('Authority and freshness indicators favor opposing claims.');
+                recommendedAction =
+                    'Investigate git commit history or deploy logs to confirm whether Claim A represents a deliberate recent migration.';
+            }
+        }
+        else {
+            likelyCurrentClaim = 'uncertain';
+            confidence = 0.5;
+            remainingUncertainty.push('Neither claim exhibits decisive authority or freshness dominance.');
+        }
+        if (evidA.quality === 'WEAK' && evidB.quality === 'STRONG') {
+            remainingUncertainty.push('Claim A has weak evidence quality compared to Claim B.');
+        }
+        else if (evidB.quality === 'WEAK' && evidA.quality === 'STRONG') {
+            remainingUncertainty.push('Claim B has weak evidence quality compared to Claim A.');
+        }
+        return {
+            likelyCurrentClaim,
+            confidence,
+            recommendedAction,
+            reason,
+            authorityComparison: {
+                claimAScore: authA.score,
+                claimBScore: authB.score,
+                winner: authWinner,
+                details: authA,
+            },
+            freshnessComparison: {
+                claimAScore: freshA.score,
+                claimBScore: freshB.score,
+                winner: freshWinner,
+                details: freshA,
+            },
+            evidenceComparison: {
+                claimAQuality: evidA,
+                claimBQuality: evidB,
+            },
+            remainingUncertainty,
+        };
+    }
+}
+//# sourceMappingURL=resolutionAdvisor.js.map

package/dist/intelligence/resolutionAdvisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolutionAdvisor.js","sourceRoot":"","sources":["../../src/intelligence/resolutionAdvisor.ts"],"names":[],"mappings":"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"}

package/dist/intelligence/semanticMatcher.d.ts

@@ -0,0 +1,21 @@
+export interface SemanticMatchResult {
+    matched: boolean;
+    confidence: number;
+    reason: string;
+    matchedFeatures: string[];
+}
+export interface SemanticMatcherConfig {
+    enabled: boolean;
+    threshold?: number;
+}
+export declare class SemanticMatcher {
+    private readonly enabled;
+    private readonly threshold;
+    constructor(config?: SemanticMatcherConfig);
+    isEnabled(): boolean;
+    /**
+     * Compares two phrases or textual predicates using an explainable n-gram and token-set similarity algorithm.
+     */
+    match(textA: string, textB: string): SemanticMatchResult;
+    private tokenize;
+}