@useody/detectors 0.0.1

package/dist/consensus.js

@@ -0,0 +1,211 @@
+import { analyzeCorpus } from './consultant-analysis.js';
+import { computeDeterministicHealthScore } from './health-score.js';
+/**
+ * Normalize a headline for grouping.
+ * Lowercases, strips punctuation, collapses whitespace.
+ */
+function normalizeHeadline(headline) {
+    return headline
+        .toLowerCase()
+        .replace(/[^a-z0-9\s]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim();
+}
+/** Compute word-overlap similarity between two strings (Jaccard). */
+function wordSimilarity(a, b) {
+    const wordsA = new Set(normalizeHeadline(a).split(' '));
+    const wordsB = new Set(normalizeHeadline(b).split(' '));
+    if (wordsA.size === 0 && wordsB.size === 0)
+        return 1;
+    let intersection = 0;
+    for (const w of wordsA) {
+        if (wordsB.has(w))
+            intersection++;
+    }
+    const union = new Set([...wordsA, ...wordsB]).size;
+    return union === 0 ? 0 : intersection / union;
+}
+/** Check if two findings match the same affected documents. */
+function documentsOverlap(a, b) {
+    if (a.affectedDocuments.length === 0 || b.affectedDocuments.length === 0) {
+        return false;
+    }
+    const setA = new Set(a.affectedDocuments);
+    for (const doc of b.affectedDocuments) {
+        if (setA.has(doc))
+            return true;
+    }
+    return false;
+}
+/** Determine if two findings are semantically similar enough to cluster. */
+function areSimilar(a, b) {
+    if (a.category !== b.category)
+        return false;
+    const headlineSim = wordSimilarity(a.headline, b.headline);
+    if (headlineSim >= 0.5)
+        return true;
+    return documentsOverlap(a, b) && headlineSim >= 0.3;
+}
+/** Group findings into clusters by semantic similarity. */
+function clusterFindings(allFindings) {
+    const clusters = [];
+    for (const { finding, passIndex } of allFindings) {
+        let matched = false;
+        for (const cluster of clusters) {
+            if (areSimilar(cluster.findings[0], finding)) {
+                cluster.findings.push(finding);
+                cluster.passIndices.add(passIndex);
+                matched = true;
+                break;
+            }
+        }
+        if (!matched) {
+            clusters.push({
+                findings: [finding],
+                passIndices: new Set([passIndex]),
+            });
+        }
+    }
+    return clusters;
+}
+/** Pick the best headline from a cluster (longest, most specific). */
+function bestHeadline(findings) {
+    let best = findings[0].headline;
+    for (const f of findings) {
+        if (f.headline.length > best.length) {
+            best = f.headline;
+        }
+    }
+    return best;
+}
+/** Pick the median severity from a cluster. */
+function medianSeverity(findings) {
+    const order = { critical: 2, warning: 1, info: 0 };
+    const sorted = findings
+        .map((f) => order[f.severity] ?? 0)
+        .sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    const val = sorted[mid];
+    if (val >= 2)
+        return 'critical';
+    if (val >= 1)
+        return 'warning';
+    return 'info';
+}
+/** Merge all evidence from a cluster, deduplicating by quote. */
+function mergeEvidence(findings) {
+    const seen = new Set();
+    const result = [];
+    for (const f of findings) {
+        for (const e of f.evidence) {
+            const key = `${e.source}::${e.quote}`;
+            if (!seen.has(key)) {
+                seen.add(key);
+                result.push(e);
+            }
+        }
+    }
+    return result;
+}
+/** Merge a cluster into a single consensus finding. */
+function mergeCluster(cluster) {
+    const base = cluster.findings[0];
+    const allDocs = new Set();
+    for (const f of cluster.findings) {
+        for (const d of f.affectedDocuments)
+            allDocs.add(d);
+    }
+    return {
+        category: base.category,
+        severity: medianSeverity(cluster.findings),
+        headline: bestHeadline(cluster.findings),
+        evidence: mergeEvidence(cluster.findings),
+        businessImpact: base.businessImpact,
+        recommendation: base.recommendation,
+        effort: base.effort,
+        affectedDocuments: [...allDocs],
+    };
+}
+/** Merge document maps from multiple passes. */
+function mergeDocumentMaps(maps) {
+    const byPath = new Map();
+    for (const map of maps) {
+        for (const doc of map) {
+            const existing = byPath.get(doc.path);
+            if (!existing || doc.topics.length > existing.topics.length) {
+                byPath.set(doc.path, doc);
+            }
+        }
+    }
+    return [...byPath.values()];
+}
+/** Compute the median of an array of numbers. */
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    const sorted = [...values].sort((a, b) => a - b);
+    const mid = Math.floor(sorted.length / 2);
+    if (sorted.length % 2 === 0) {
+        return Math.round((sorted[mid - 1] + sorted[mid]) / 2);
+    }
+    return sorted[mid];
+}
+/**
+ * Run consensus analysis: multiple passes with majority voting.
+ * Findings must appear in >= ceil(N/2) passes to be kept.
+ * Health scores are computed deterministically from consensus findings.
+ */
+export async function runConsensusAnalysis(input, llm, options) {
+    const passes = options?.passes ?? 3;
+    const log = options?.logger ?? (() => { });
+    const maxTokens = options?.maxTokens;
+    const threshold = options?.minVotes ?? Math.ceil(passes / 2);
+    const taggedFindings = [];
+    log(`Running ${String(passes)} passes in parallel...`);
+    const passPromises = Array.from({ length: passes }, (_, i) => {
+        const passLog = (msg) => log(`[Pass ${String(i + 1)}] ${msg}`);
+        return analyzeCorpus(input, llm, { maxTokens, logger: passLog })
+            .then((result) => {
+            passLog(`Complete: ${String(result.findings.length)} findings`);
+            return { passIndex: i, result };
+        })
+            .catch((err) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            passLog(`Failed: ${msg}`);
+            return null;
+        });
+    });
+    const settled = await Promise.all(passPromises);
+    const results = [];
+    for (const entry of settled) {
+        if (entry) {
+            results.push(entry.result);
+            for (const finding of entry.result.findings) {
+                taggedFindings.push({ finding, passIndex: entry.passIndex });
+            }
+        }
+    }
+    log('Building consensus...');
+    const clusters = clusterFindings(taggedFindings);
+    const consensusFindings = [];
+    for (const cluster of clusters) {
+        if (cluster.passIndices.size >= threshold) {
+            consensusFindings.push(mergeCluster(cluster));
+        }
+    }
+    const healthScore = computeDeterministicHealthScore(consensusFindings);
+    const documentMap = mergeDocumentMaps(results.map((r) => r.documentMap));
+    const totalTokens = median(results.map((r) => r.metadata.totalTokens));
+    return {
+        findings: consensusFindings,
+        healthScore,
+        documentMap,
+        metadata: {
+            analyzedAt: new Date().toISOString(),
+            documentCount: input.documents.length,
+            totalTokens,
+            modelUsed: `${llm.getModelId()} (${String(passes)}-pass consensus)`,
+        },
+    };
+}
+//# sourceMappingURL=consensus.js.map

package/dist/consultant-analysis.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Consultant-grade analysis engine.
+ * Sends all content to an LLM acting as a management consultant and
+ * parses structured findings across 7 categories.
+ * Uses streaming to provide progress feedback and avoid apparent hangs.
+ * @module consultant-analysis
+ */
+import type { LLMProvider } from '@useody/platform-core';
+export type { FindingCategory, ConsultingFinding, HealthScore, DocumentInfo, AnalysisResult, AnalysisInput, } from './consultant-prompts.js';
+import type { AnalysisResult, AnalysisInput } from './consultant-prompts.js';
+/**
+ * Run consulting-style analysis on a document corpus.
+ * Sends all content to the LLM in a single call with a management-
+ * consultant system prompt. For corpora that fit in context.
+ */
+export declare function analyzeCorpus(input: AnalysisInput, llm: LLMProvider, options?: {
+    maxTokens?: number;
+    logger?: (msg: string) => void;
+}): Promise<AnalysisResult>;
+//# sourceMappingURL=consultant-analysis.d.ts.map

package/dist/consultant-analysis.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consultant-analysis.d.ts","sourceRoot":"","sources":["../src/consultant-analysis.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,uBAAuB,CAAC;AAYtE,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,WAAW,EACX,YAAY,EACZ,cAAc,EACd,aAAa,GACd,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAE7E;;;;GAIG;AACH,wBAAsB,aAAa,CACjC,KAAK,EAAE,aAAa,EACpB,GAAG,EAAE,WAAW,EAChB,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAC/D,OAAO,CAAC,cAAc,CAAC,CA4DzB"}

package/dist/consultant-analysis.js

@@ -0,0 +1,69 @@
+import { SYSTEM_PROMPT, buildUserMessage, isValidFinding, parseHealthScore, streamToString, parseOrRetry, buildDocumentMap, } from './consultant-prompts.js';
+/**
+ * Run consulting-style analysis on a document corpus.
+ * Sends all content to the LLM in a single call with a management-
+ * consultant system prompt. For corpora that fit in context.
+ */
+export async function analyzeCorpus(input, llm, options) {
+    const log = options?.logger ?? (() => { });
+    const docCount = input.documents.length;
+    // Scale maxTokens with corpus size: base 1024 + 256 per doc, capped at 4096.
+    const scaledMax = Math.min(4096, 1024 + docCount * 256);
+    const maxTokens = options?.maxTokens ?? scaledMax;
+    const modelId = llm.getModelId();
+    if (input.documents.length === 0) {
+        return emptyResult(modelId);
+    }
+    if (input.documents.length < 2) {
+        log('Single document — cross-document analysis requires 2+ documents.');
+        return {
+            findings: [],
+            healthScore: { overall: 100, consistency: 100, freshness: 100, ownership: 100, coverage: 100 },
+            documentMap: input.documents.map((d) => ({
+                path: d.path, title: d.title, lastModified: d.lastModified, topics: [],
+            })),
+            metadata: {
+                analyzedAt: new Date().toISOString(),
+                documentCount: input.documents.length,
+                totalTokens: 0,
+                modelUsed: modelId,
+            },
+        };
+    }
+    const label = `Analyzing ${String(input.documents.length)} documents with ${modelId}`;
+    log(`${label}...`);
+    const messages = [
+        { role: 'system', content: SYSTEM_PROMPT },
+        { role: 'user', content: buildUserMessage(input) },
+    ];
+    const response = await streamToString(llm, messages, maxTokens, log, label);
+    const data = await parseOrRetry(messages, response, llm, maxTokens, log, label);
+    if (!data) {
+        log('Failed to parse LLM response after retry.');
+        return emptyResult(modelId);
+    }
+    const findings = (data.findings ?? []).filter(isValidFinding);
+    const healthScore = parseHealthScore(data.healthScore);
+    const documentMap = buildDocumentMap(data.documentMap, input);
+    const totalChars = input.documents.reduce((s, d) => s + d.content.length, 0);
+    log(`Found ${String(findings.length)} findings. Health: ${String(healthScore.overall)}`);
+    return {
+        findings, healthScore, documentMap,
+        metadata: {
+            analyzedAt: new Date().toISOString(),
+            documentCount: input.documents.length,
+            totalTokens: Math.ceil(totalChars / 4),
+            modelUsed: modelId,
+        },
+    };
+}
+/** Return a clean empty result. */
+function emptyResult(modelId) {
+    return {
+        findings: [],
+        healthScore: { overall: 100, consistency: 100, freshness: 100, ownership: 100, coverage: 100 },
+        documentMap: [],
+        metadata: { analyzedAt: new Date().toISOString(), documentCount: 0, totalTokens: 0, modelUsed: modelId },
+    };
+}
+//# sourceMappingURL=consultant-analysis.js.map

package/dist/consultant-prompts.d.ts

@@ -0,0 +1,83 @@
+/**
+ * System prompt, types, and validation helpers for consultant analysis.
+ * Extracted from consultant-analysis.ts to keep files under 250 lines.
+ * @module consultant-prompts
+ */
+import type { LLMProvider, ChatMessage } from '@useody/platform-core';
+/** The seven finding categories a consultant analysis produces. */
+export type FindingCategory = 'contradiction' | 'stale_commitment' | 'ownership_gap' | 'tribal_knowledge' | 'duplicate_truth' | 'commitment_without_followthrough' | 'decision_without_context';
+/** A single finding from the consultant analysis. */
+export interface ConsultingFinding {
+    category: FindingCategory;
+    severity: 'critical' | 'warning' | 'info';
+    headline: string;
+    evidence: Array<{
+        source: string;
+        quote: string;
+    }>;
+    businessImpact: string;
+    recommendation: string;
+    effort: 'quick_win' | 'medium' | 'major';
+    affectedDocuments: string[];
+}
+/** Multi-dimensional health score for the document corpus. */
+export interface HealthScore {
+    overall: number;
+    consistency: number;
+    freshness: number;
+    ownership: number;
+    coverage: number;
+}
+/** Metadata about a single document extracted during analysis. */
+export interface DocumentInfo {
+    path: string;
+    title: string;
+    lastModified?: string;
+    topics: string[];
+    owner?: string;
+}
+/** Complete result of a consultant analysis. */
+export interface AnalysisResult {
+    findings: ConsultingFinding[];
+    healthScore: HealthScore;
+    documentMap: DocumentInfo[];
+    metadata: {
+        analyzedAt: string;
+        documentCount: number;
+        totalTokens: number;
+        modelUsed: string;
+    };
+}
+/** Input documents for analysis. */
+export interface AnalysisInput {
+    documents: Array<{
+        path: string;
+        title: string;
+        content: string;
+        lastModified?: string;
+    }>;
+}
+/** The management consultant system prompt for analysis. */
+export declare const SYSTEM_PROMPT: string;
+/** Build the user message with document delimiters. */
+export declare function buildUserMessage(input: AnalysisInput): string;
+/** Validate that a parsed object is a well-formed finding. */
+export declare function isValidFinding(f: unknown): f is ConsultingFinding;
+/** Parse HealthScore from LLM output, clamping each dimension. */
+export declare function parseHealthScore(raw: unknown): HealthScore;
+/** Shape of the raw JSON the LLM produces. */
+export interface LlmOutput {
+    findings?: unknown[];
+    healthScore?: unknown;
+    documentMap?: unknown[];
+}
+/**
+ * Accumulate a streaming LLM response, logging progress periodically.
+ * Falls back to llm.complete() if the stream method throws.
+ */
+export declare function streamToString(llm: LLMProvider, messages: ChatMessage[], maxTokens: number, log: (msg: string) => void, label: string): Promise<string>;
+/** Attempt to parse LLM response, retrying once on failure. */
+export declare function parseOrRetry(messages: ChatMessage[], firstResponse: string, llm: LLMProvider, maxTokens: number, log: (msg: string) => void, label: string): Promise<LlmOutput | null>;
+/** Merge LLM document analysis with input metadata. */
+export declare function buildDocumentMap(raw: unknown[] | undefined, input: AnalysisInput): DocumentInfo[];
+//# sourceMappingURL=consultant-prompts.d.ts.map

package/dist/consultant-prompts.d.ts.map

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

package/dist/consultant-prompts.js

@@ -0,0 +1,135 @@
+import { parseLlmJsonResponse } from '@useody/platform-core';
+const VALID_CATEGORIES = new Set([
+    'contradiction', 'stale_commitment', 'ownership_gap', 'tribal_knowledge',
+    'duplicate_truth', 'commitment_without_followthrough', 'decision_without_context',
+]);
+const VALID_SEVERITIES = new Set(['critical', 'warning', 'info']);
+const VALID_EFFORTS = new Set(['quick_win', 'medium', 'major']);
+/** The management consultant system prompt for analysis. */
+export const SYSTEM_PROMPT = [
+    'You are a senior management consultant conducting a knowledge health assessment for an executive team.',
+    'Analyze every document. Cite exact passages as evidence. Identify both problems AND coverage gaps.',
+    '',
+    '## Systematic Cross-Reference (MANDATORY)',
+    'Before writing findings: extract every policy, number, deadline, and rule from EACH document. Then cross-reference each assertion against EVERY other document. Check all document pairs — do not skip any.',
+    'Pay special attention to: numerical disagreements (different numbers for the same policy), cases where one doc allows what another forbids, and conflicting dates/deadlines/timelines.',
+    '',
+    '## 7 Categories',
+    '1. contradiction — documents making conflicting claims. Numbers that don\'t match. Policies that disagree. One doc allows what another forbids.',
+    '2. stale_commitment — deadlines passed, pending decisions never resolved, outdated references.',
+    '3. ownership_gap — no clear process owner, overlapping responsibilities, orphaned projects. Also flag under-documented areas.',
+    '4. tribal_knowledge — critical info in only one document, single points of failure. Also flag areas that seem under-documented.',
+    '5. duplicate_truth — same topic in multiple places with divergent content.',
+    '6. commitment_without_followthrough — stated commitments, timelines, or action items with no evidence of completion.',
+    '7. decision_without_context — decisions stated without rationale, creating reversal risk if the decision-maker leaves.',
+    '',
+    '## Writing Rules',
+    '- Headlines must name the SPECIFIC policy, number, or commitment. Never generic ("potentially outdated"). Instead: "Vacation policy: 20 days (HR handbook) vs 15 days (onboarding guide)."',
+    '- Lead with business impact, use "This creates risk of..." framing. Zero jargon.',
+    '- Every contradiction MUST cite both conflicting claims as exact quotes in the evidence array.',
+    '',
+    '## Severity: critical=money/customers/compliance/safety/passed deadlines. warning=internal conflicts, >6mo stale, ambiguous ownership. info=not-yet-divergent duplicates, non-critical single-source.',
+    '',
+    '## JSON Output (no fencing, no preamble)',
+    '{"findings":[{"category":"<id>","severity":"<level>","headline":"<CEO-scannable>","evidence":[{"source":"<doc path>","quote":"<exact passage>"}],"businessImpact":"<what happens if ignored>","recommendation":"<specific fix>","effort":"<quick_win|medium|major>","affectedDocuments":["<paths>"]}],"healthScore":{"overall":<0-100>,"consistency":<0-100>,"freshness":<0-100>,"ownership":<0-100>,"coverage":<0-100>},"documentMap":[{"path":"<path>","title":"<title>","topics":["<topic>"],"owner":"<if identifiable>"}]}',
+    '',
+    'Dimensions: consistency=cross-doc agreement, freshness=currency, ownership=responsibility clarity, coverage=breadth.',
+    'Write in the documents\' language. Only JSON keys and category IDs use English.',
+].join('\n');
+/** Build the user message with document delimiters. */
+export function buildUserMessage(input) {
+    return input.documents.map((doc) => {
+        const mod = doc.lastModified ? ` (Last modified: ${doc.lastModified})` : '';
+        return `--- DOCUMENT: ${doc.path}${mod} ---\n${doc.content}`;
+    }).join('\n\n');
+}
+/** Validate that a parsed object is a well-formed finding. */
+export function isValidFinding(f) {
+    if (!f || typeof f !== 'object')
+        return false;
+    const o = f;
+    if (typeof o.category !== 'string' || !VALID_CATEGORIES.has(o.category))
+        return false;
+    if (typeof o.severity !== 'string' || !VALID_SEVERITIES.has(o.severity))
+        return false;
+    if (typeof o.headline !== 'string' || !Array.isArray(o.evidence))
+        return false;
+    if (typeof o.effort !== 'string' || !VALID_EFFORTS.has(o.effort))
+        o.effort = 'medium';
+    if (!Array.isArray(o.affectedDocuments))
+        o.affectedDocuments = [];
+    if (typeof o.businessImpact !== 'string')
+        o.businessImpact = '';
+    if (typeof o.recommendation !== 'string')
+        o.recommendation = '';
+    return true;
+}
+/** Clamp a value to 0-100. */
+function clamp(v) {
+    return Math.max(0, Math.min(100, Math.round(typeof v === 'number' ? v : 0)));
+}
+/** Parse HealthScore from LLM output, clamping each dimension. */
+export function parseHealthScore(raw) {
+    const o = (raw && typeof raw === 'object' ? raw : {});
+    return {
+        overall: clamp(o.overall), consistency: clamp(o.consistency),
+        freshness: clamp(o.freshness), ownership: clamp(o.ownership), coverage: clamp(o.coverage),
+    };
+}
+/**
+ * Accumulate a streaming LLM response, logging progress periodically.
+ * Falls back to llm.complete() if the stream method throws.
+ */
+export async function streamToString(llm, messages, maxTokens, log, label) {
+    try {
+        const chunks = [];
+        let tokenCount = 0;
+        let lastLog = Date.now();
+        const LOG_INTERVAL_MS = 3_000;
+        for await (const token of llm.stream(messages, { temperature: 0, maxTokens })) {
+            chunks.push(token);
+            tokenCount++;
+            const now = Date.now();
+            if (now - lastLog >= LOG_INTERVAL_MS) {
+                log(`${label} (${String(tokenCount)} tokens...)`);
+                lastLog = now;
+            }
+        }
+        return chunks.join('');
+    }
+    catch {
+        return llm.complete(messages, { temperature: 0, maxTokens });
+    }
+}
+/** Attempt to parse LLM response, retrying once on failure. */
+export async function parseOrRetry(messages, firstResponse, llm, maxTokens, log, label) {
+    const first = parseLlmJsonResponse(firstResponse);
+    if (first.data)
+        return first.data;
+    log(`${label} — retrying (response was not valid JSON)...`);
+    const retry = [
+        ...messages,
+        { role: 'assistant', content: firstResponse },
+        { role: 'user', content: 'That was not valid JSON. Return ONLY the JSON object, no other text.' },
+    ];
+    const second = await streamToString(llm, retry, maxTokens, log, `${label} retry`);
+    return parseLlmJsonResponse(second).data;
+}
+/** Merge LLM document analysis with input metadata. */
+export function buildDocumentMap(raw, input) {
+    const idx = new Map();
+    for (const d of (Array.isArray(raw) ? raw : [])) {
+        if (d && typeof d === 'object' && typeof d.path === 'string') {
+            idx.set(d.path, d);
+        }
+    }
+    return input.documents.map((doc) => {
+        const m = idx.get(doc.path);
+        return {
+            path: doc.path, title: doc.title, lastModified: doc.lastModified,
+            topics: Array.isArray(m?.topics) ? m.topics : [],
+            owner: typeof m?.owner === 'string' ? m.owner : undefined,
+        };
+    });
+}
+//# sourceMappingURL=consultant-prompts.js.map

package/dist/contradiction-helpers.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Heuristic helpers for the contradiction detector.
+ * Extracted to keep contradictions.ts under 250 lines.
+ * @module detectors/contradiction-helpers
+ */
+import type { KnowledgeNode, Detection } from '@useody/platform-core';
+/** A number+unit fact extracted from text. */
+export interface NumberFact {
+    value: number;
+    unit: string;
+    raw: string;
+    index: number;
+}
+/** Extract number+unit pairs from text. */
+export declare function extractNumbers(text: string): NumberFact[];
+/** Normalize unit names for comparison. */
+export declare function normalizeUnit(u: string): string;
+/** Get raw text from a node for content-based heuristics. */
+export declare function getNodeText(node: KnowledgeNode): string;
+/** Extract the sentence containing the match at matchIndex. */
+export declare function extractSentence(text: string, matchIndex: number): string;
+/** Capitalize the first letter of a string. */
+export declare function capitalizeFirst(s: string): string;
+/** Extract topic keywords from a node's raw content only. */
+export declare function rawKeywords(node: KnowledgeNode): Set<string>;
+/** Canonical pair key for deduplication. */
+export declare function pairKey(id1: string, id2: string): string;
+/** Return true if two nodes plausibly discuss the same topic. */
+export declare function areSameTopic(a: KnowledgeNode, b: KnowledgeNode): boolean;
+/** Return true if both texts share an identical long sentence. */
+export declare function shareExactSentence(textA: string, textB: string): boolean;
+/** Build set of entities appearing in >50% of nodes. */
+export declare function buildHighFreqEntities(nodes: KnowledgeNode[]): Set<string>;
+/** @internal */
+export declare const BOOLEAN_PAIRS: [RegExp, RegExp, string, string][];
+/** Words near enabled/disabled or required/optional that indicate a spec, not a policy. */
+export declare const CONFIG_CONTEXT: RegExp;
+/** Detect contradictions from shared entities with different facts. */
+export declare function detectFactContradiction(a: KnowledgeNode, b: KnowledgeNode, out: Detection[], highFreqEntities: Set<string>): void;
+//# sourceMappingURL=contradiction-helpers.d.ts.map

package/dist/contradiction-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contradiction-helpers.d.ts","sourceRoot":"","sources":["../src/contradiction-helpers.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EACV,aAAa,EACb,SAAS,EACV,MAAM,uBAAuB,CAAC;AAkB/B,8CAA8C;AAC9C,MAAM,WAAW,UAAU;IAAG,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE;AAEvF,2CAA2C;AAC3C,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CAUzD;AAED,2CAA2C;AAC3C,wBAAgB,aAAa,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAS/C;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,MAAM,CAIvD;AAED,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAMxE;AAED,+CAA+C;AAC/C,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,6DAA6D;AAC7D,wBAAgB,WAAW,CAAC,IAAI,EAAE,aAAa,GAAG,GAAG,CAAC,MAAM,CAAC,CAM5D;AAED,4CAA4C;AAC5C,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAExD;AAED,iEAAiE;AACjE,wBAAgB,YAAY,CAAC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,GAAG,OAAO,CAUxE;AAED,kEAAkE;AAClE,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAIxE;AAED,wDAAwD;AACxD,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,GAAG,CAAC,MAAM,CAAC,CAezE;AAGD,gBAAgB;AAChB,eAAO,MAAM,aAAa,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAe3D,CAAC;AAEF,2FAA2F;AAC3F,eAAO,MAAM,cAAc,QAA6M,CAAC;AAEzO,uEAAuE;AACvE,wBAAgB,uBAAuB,CACrC,CAAC,EAAE,aAAa,EAAE,CAAC,EAAE,aAAa,EAAE,GAAG,EAAE,SAAS,EAAE,EACpD,gBAAgB,EAAE,GAAG,CAAC,MAAM,CAAC,GAC5B,IAAI,CAqCN"}