noteconnection 1.7.0 → 1.9.0

package/dist/src/learning/ragEvidenceQuality.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.iterateRagEvidenceClauses = iterateRagEvidenceClauses;
+exports.segmentRagEvidenceClauses = segmentRagEvidenceClauses;
+exports.scoreRagEvidenceClause = scoreRagEvidenceClause;
+function normalizeWhitespace(value) {
+    return String(value || '').replace(/\s+/gu, ' ').trim();
+}
+function isClauseBoundary(source, index) {
+    const character = source[index];
+    if (/\r|\n|;/u.test(character)) {
+        return true;
+    }
+    if (character === '.' && /[\d\s=+\-(]/u.test(source[index - 1] || ' ') && /\d/u.test(source[index + 1] || '')) {
+        return false;
+    }
+    return /[.!?。！？；]/u.test(character);
+}
+/**
+ * Splits source evidence at discourse boundaries while retaining decimal numbers and
+ * mathematical notation. The caller still owns filtering and public-text naturalization.
+ */
+function* iterateRagEvidenceClauses(value) {
+    const source = String(value || '');
+    if (!source) {
+        return;
+    }
+    let start = 0;
+    for (let index = 0; index < source.length; index += 1) {
+        if (!isClauseBoundary(source, index)) {
+            continue;
+        }
+        const includeBoundary = /[.!?。！？]/u.test(source[index]);
+        const clause = normalizeWhitespace(source.slice(start, includeBoundary ? index + 1 : index));
+        if (clause) {
+            yield clause;
+        }
+        start = index + 1;
+    }
+    const remainder = normalizeWhitespace(source.slice(start));
+    if (remainder) {
+        yield remainder;
+    }
+}
+function segmentRagEvidenceClauses(value) {
+    return Array.from(iterateRagEvidenceClauses(value));
+}
+function delimiterBalance(value) {
+    const pairs = { '(': ')', '[': ']', '{': '}', '（': '）', '［': '］', '｛': '｝' };
+    const closing = new Set(Object.values(pairs));
+    const stack = [];
+    for (const character of value) {
+        if (pairs[character]) {
+            stack.push(pairs[character]);
+        }
+        else if (closing.has(character) && stack.pop() !== character) {
+            return false;
+        }
+    }
+    return stack.length === 0;
+}
+function mathDensity(value) {
+    const mathTokens = value.match(/(?:\b\d+(?:\.\d+)?\b|[=<>±×÷∑∫√]|\b(?:sin|cos|log|exp)\b)/giu) || [];
+    return Math.min(1, mathTokens.length / Math.max(6, value.length / 24));
+}
+function documentaryPenalty(value) {
+    return /\b(?:this (?:document|section|table)|the following|as requested|we will|must follow|ignore this)\b/iu.test(value)
+        || /(?:本文档|下表|如下|按照您的要求|忽略本节)/u.test(value)
+        ? 0.35
+        : 0;
+}
+function scoreRagEvidenceClause(value) {
+    const clause = normalizeWhitespace(value);
+    const hasTerminalPunctuation = /[.!?。！？]$/u.test(clause);
+    const hasBalancedDelimiters = delimiterBalance(clause);
+    const density = mathDensity(clause);
+    const penalty = documentaryPenalty(clause);
+    const lengthScore = clause.length < 8
+        ? -0.3
+        : clause.length <= 420
+            ? 0.25
+            : -Math.min(0.25, (clause.length - 420) / 2400);
+    const score = Math.max(0, Math.min(1, 0.35
+        + (hasTerminalPunctuation ? 0.15 : -0.08)
+        + (hasBalancedDelimiters ? 0.15 : -0.3)
+        + Math.min(0.2, density * 0.2)
+        + lengthScore
+        - penalty));
+    return {
+        score: Number(score.toFixed(4)),
+        hasTerminalPunctuation,
+        hasBalancedDelimiters,
+        mathDensity: Number(density.toFixed(4)),
+        documentaryPenalty: penalty,
+    };
+}

package/dist/src/learning/ragEvidenceQuality.test.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ragEvidenceQuality_1 = require("./ragEvidenceQuality");
+describe('ragEvidenceQuality', () => {
+    test('segments prose without splitting decimal mathematical values', () => {
+        expect((0, ragEvidenceQuality_1.segmentRagEvidenceClauses)('The coefficient is 0.75; heat transfer follows the wall.')).toEqual([
+            'The coefficient is 0.75',
+            'heat transfer follows the wall.',
+        ]);
+    });
+    test('scores complete balanced mathematical evidence above documentary prose', () => {
+        const evidence = (0, ragEvidenceQuality_1.scoreRagEvidenceClause)('The thermal flux is q = kA(T1 - T2) / L, so thickness changes the exchange rate.');
+        const documentary = (0, ragEvidenceQuality_1.scoreRagEvidenceClause)('This document will explain the following table as requested.');
+        expect(evidence.hasBalancedDelimiters).toBe(true);
+        expect(evidence.mathDensity).toBeGreaterThan(0);
+        expect(evidence.score).toBeGreaterThan(documentary.score);
+        expect(documentary.documentaryPenalty).toBeGreaterThan(0);
+    });
+    test('preserves leading decimal measurements without joining numbered sentences', () => {
+        expect((0, ragEvidenceQuality_1.segmentRagEvidenceClauses)('The offset is -.25 ms. The duration is .5 s; 1. Next observation.')).toEqual([
+            'The offset is -.25 ms.', 'The duration is .5 s', '1.', 'Next observation.',
+        ]);
+    });
+    test('penalizes unbalanced mathematical fragments', () => {
+        const quality = (0, ragEvidenceQuality_1.scoreRagEvidenceClause)('The flux is q = kA(T1 - T2 / L.');
+        expect(quality.hasBalancedDelimiters).toBe(false);
+        expect(quality.score).toBeLessThan(0.5);
+    });
+});

package/dist/src/learning/ragPublicText.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.omitFencedMarkdownPayload = omitFencedMarkdownPayload;
+exports.extractPublicMermaidEvidenceLabels = extractPublicMermaidEvidenceLabels;
+exports.naturalizeRagPublicEvidenceClause = naturalizeRagPublicEvidenceClause;
+exports.shouldRejectPublicEvidenceClause = shouldRejectPublicEvidenceClause;
+exports.shouldRejectCompareProcedureEvidenceClause = shouldRejectCompareProcedureEvidenceClause;
+const answerTaskPlan_1 = require("./answerTaskPlan");
+function normalizeWhitespace(value) {
+    return String(value || '').replace(/\s+/g, ' ').trim();
+}
+function omitFencedMarkdownPayload(value) {
+    return String(value || '')
+        .replace(/```[\s\S]*?```/gu, ' ')
+        .replace(/```[\s\S]*$/u, ' ');
+}
+function normalizeMermaidLabel(value) {
+    return normalizeWhitespace(String(value || '')
+        .replace(/<br\s*\/?>/giu, ' ')
+        .replace(/\\n/gu, ' ')
+        .replace(/["`*_~#|{}]/gu, ' '));
+}
+/**
+ * Converts diagram node labels into evidence text while keeping Mermaid syntax out of public answers.
+ */
+function extractPublicMermaidEvidenceLabels(value) {
+    const labels = [];
+    const append = (candidate) => {
+        const label = normalizeMermaidLabel(candidate);
+        if (label && !labels.includes(label)) {
+            labels.push(label);
+        }
+    };
+    const source = String(value || '');
+    const fences = source.matchAll(/```mermaid\s*([\s\S]*?)(?:```|$)/giu);
+    for (const fence of fences) {
+        const body = String(fence[1] || '');
+        body.replace(/\[([^\]]+)\]/gu, (_match, label) => {
+            append(label);
+            return '';
+        });
+        body.replace(/"([^"]+)"/gu, (_match, label) => {
+            append(label);
+            return '';
+        });
+    }
+    return labels;
+}
+const LEADING_SOURCE_LABEL_PATTERN = /^(?:(?:prerequisites?|preconditions?|requirements?|background|context|mechanism|reasoning boundary|downstream checks?|downstream consequences?|failure modes?|mitigation(?: neighbor)?|graph caveat|caveat|evidence|summary|note|material science)\s*[:\uFF1A-]\s*|(?:核心概念(?:及其数学基础)?|材料科学|技术参数)(?:\s*[:\uFF1A-]\s*|\s+))/iu;
+const PRESERVED_LEADING_LABEL_PATTERN = /^(?:step|phase|stage|section)\s*\d+\s*[:\uFF1A-]/iu;
+function naturalizeRagPublicEvidenceClause(value) {
+    let normalized = normalizeWhitespace(omitFencedMarkdownPayload(value)
+        .replace(/^\s*[-+*]\s+/gmu, '')
+        .replace(/\s+\*\s+(?=\$|\*\*|[\u3400-\u9fff])/gu, ' ')
+        .replace(/\*\*([^*]+)\*\*/gu, '$1')
+        .replace(/([+\-]\/)\s+(?=\d)/gu, '$1')
+        .replace(/(\d)\.\s+(?=\d)/gu, '$1.')
+        .replace(/^(?:#{1,6})\s+/u, ''));
+    const tableStart = normalized.search(/\s\|\s*[^|]+\s*\|/u);
+    if (tableStart >= 0) {
+        normalized = normalizeWhitespace(normalized.slice(0, tableStart));
+    }
+    if (!normalized || PRESERVED_LEADING_LABEL_PATTERN.test(normalized)) {
+        return normalized;
+    }
+    for (let pass = 0; pass < 3; pass += 1) {
+        const next = normalizeWhitespace(normalized.replace(LEADING_SOURCE_LABEL_PATTERN, ''));
+        if (!next || next === normalized) {
+            break;
+        }
+        normalized = next;
+        if (PRESERVED_LEADING_LABEL_PATTERN.test(normalized)) {
+            break;
+        }
+    }
+    return normalized;
+}
+function shouldRejectPublicEvidenceClause(value) {
+    const normalized = normalizeWhitespace(value);
+    // A bare wiki link identifies a note, but supplies no factual statement for answer coverage.
+    return /^(?:(?:\d+[.)]|[-*+])?\s*\[\[[^\]]+\]\][\s,;、，；.!。]*)+$/u.test(normalized)
+        || /\b(?:distractor|must not guide|do not use|ignore this (?:section|evidence)|must (?:compare|resolve)|before publishing)\b/iu.test(normalized)
+        || /\b(?:this|the)\s+(?:clause|sentence|paragraph)\b[^.!?]{0,120}\bpublic\s+(?:definition|answer)\s+budget\b/iu.test(normalized)
+        || /\b(?:the following table|the table below)\b/iu.test(normalized)
+        || /(?:下表|以下表格|表中)(?:列出|展示|给出|包含)/u.test(normalized)
+        || /(?:参数\s*\(Parameter\)|Parameter).{0,160}(?:单位\s*\(Unit\)|Unit).{0,160}:---/iu.test(normalized)
+        || /(?:遵从您的指示|所有推理过程|最终输出|仅基于标题|根据您的要求生成|本技术文档旨在)/u.test(normalized);
+}
+function shouldRejectCompareProcedureEvidenceClause(value, query) {
+    const normalizedClause = normalizeWhitespace(value).toLowerCase();
+    const normalizedQuery = normalizeWhitespace(query).toLowerCase();
+    if (!normalizedClause) {
+        return false;
+    }
+    if ((0, answerTaskPlan_1.isProcedureRequest)(normalizedQuery)) {
+        return false;
+    }
+    return /^(?:(?:procedure|workflow|runbook)\s*[:\uFF1A-]|(?:step\s*\d+|steps?|步骤\s*\d+)\b)/u.test(normalizedClause)
+        || /\b(?:follow|execute|perform)\s+(?:this|the following)\s+(?:procedure|workflow|steps?)\b/u.test(normalizedClause)
+        || /\bprocedural\b.{0,80}\bsequence\b/u.test(normalizedClause);
+}

package/dist/src/learning/ragPublicText.test.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ragPublicText_1 = require("./ragPublicText");
+const KnowledgeLearningPlatform_1 = require("./KnowledgeLearningPlatform");
+describe('ragPublicText', () => {
+    test('retains numbered procedure evidence for a how-should request', () => {
+        expect((0, ragPublicText_1.shouldRejectCompareProcedureEvidenceClause)('Step 1: Validate the candidate.', 'How should the index be replaced?')).toBe(false);
+        expect((0, ragPublicText_1.shouldRejectCompareProcedureEvidenceClause)('Step 1: Validate the candidate.', 'Compare the two indexes.')).toBe(true);
+    });
+    test.each(['[[Checkpoint]]', '[[Checkpoint]] [[Mutation log]]', '1. [[Checkpoint]] 2. [[Mutation log]]'])('rejects link-only navigation as factual evidence: %s', text => {
+        expect((0, ragPublicText_1.shouldRejectPublicEvidenceClause)(text)).toBe(true);
+    });
+    test('preserves factual prose that contains a wiki link', () => {
+        expect((0, ragPublicText_1.shouldRejectPublicEvidenceClause)('A [[Mutation log]] records an ordered sequence of changes.')).toBe(false);
+    });
+    test('comparison composition selects source facts instead of bare wiki links', async () => {
+        const platform = new KnowledgeLearningPlatform_1.KnowledgeLearningPlatform({ autoPersist: false });
+        await platform.ingestKnowledge({ documents: [
+                { documentId: 'checkpoint', sourcePath: 'test/checkpoint.md', content: '# Checkpoint\nA checkpoint stores the complete state at a checkpoint. [[Mutation log]]' },
+                { documentId: 'mutation-log', sourcePath: 'test/mutation-log.md', content: '# Mutation Log\nA mutation log records an ordered sequence of state changes. [[Checkpoint]]' },
+            ] });
+        const response = await platform.agentConversation({ message: 'Compare Checkpoint and Mutation Log', persistMemory: false });
+        expect(response.answer).toMatch(/complete state|ordered sequence/i);
+        expect((0, ragPublicText_1.shouldRejectPublicEvidenceClause)(response.answer)).toBe(false);
+    });
+    test('removes Markdown list and bold-label scaffolding before public composition', () => {
+        expect((0, ragPublicText_1.naturalizeRagPublicEvidenceClause)('* **Quantitative analysis**: pressure follows P = rho g h.'))
+            .toBe('Quantitative analysis: pressure follows P = rho g h.');
+        expect((0, ragPublicText_1.naturalizeRagPublicEvidenceClause)('* $T$ is the temperature field.'))
+            .toBe('$T$ is the temperature field.');
+        expect((0, ragPublicText_1.naturalizeRagPublicEvidenceClause)('A value * B value remains mathematical.'))
+            .toBe('A value * B value remains mathematical.');
+    });
+    test('removes markdown headings and table scaffolding while preserving the factual lead', () => {
+        expect((0, ragPublicText_1.naturalizeRagPublicEvidenceClause)('### Technical specifications The glass density is about 2500 kg/m³. | Parameter | Value | | :--- | :--- | | density | 2500 |')).toBe('Technical specifications The glass density is about 2500 kg/m³.');
+    });
+    test('rejects authoring instructions and evidence-control prose in Chinese and English', () => {
+        expect((0, ragPublicText_1.shouldRejectPublicEvidenceClause)('所有推理过程以英文进行，最终输出为简体中文。')).toBe(true);
+        expect((0, ragPublicText_1.shouldRejectPublicEvidenceClause)('Operators must resolve the active owner before publishing.')).toBe(true);
+        expect((0, ragPublicText_1.shouldRejectPublicEvidenceClause)('The glass wall conducts heat into the environment.')).toBe(false);
+        expect((0, ragPublicText_1.shouldRejectPublicEvidenceClause)('This clause is intentionally beyond the public definition budget and should remain internal.')).toBe(true);
+        expect((0, ragPublicText_1.shouldRejectPublicEvidenceClause)('The response budget limits serialized bytes.')).toBe(false);
+    });
+    test('removes fenced diagram payloads instead of exposing renderer source', () => {
+        expect((0, ragPublicText_1.naturalizeRagPublicEvidenceClause)('Heat moves by conduction and convection. ```mermaid graph TD A --> B ```')).toBe('Heat moves by conduction and convection.');
+    });
+    test('rejects flattened table introductions after Markdown extraction', () => {
+        expect((0, ragPublicText_1.shouldRejectPublicEvidenceClause)('下表列出了标准温度和压力下的典型技术参数。参数 Parameter 密度 2500 999.8 kg/m³ 单位 Unit。')).toBe(true);
+        expect((0, ragPublicText_1.shouldRejectPublicEvidenceClause)('The following table lists typical parameters. Parameter Density Value Unit.')).toBe(true);
+        expect((0, ragPublicText_1.shouldRejectPublicEvidenceClause)('参数 (Parameter) 钠钙玻璃 水 单位 (Unit) :--- :--- 密度 2500 999.8 kg/m³。')).toBe(true);
+    });
+    test('removes flattened section labels while retaining their factual sentence', () => {
+        expect((0, ragPublicText_1.naturalizeRagPublicEvidenceClause)('核心概念及其数学基础：水杯系统通过传导、对流和辐射与环境交换热量。')).toBe('水杯系统通过传导、对流和辐射与环境交换热量。');
+        expect((0, ragPublicText_1.naturalizeRagPublicEvidenceClause)('Material science: Glass is an amorphous solid without long-range order.')).toBe('Glass is an amorphous solid without long-range order.');
+        expect((0, ragPublicText_1.naturalizeRagPublicEvidenceClause)('核心概念及其数学基础 水杯系统通过传导、对流和辐射与环境交换热量。')).toBe('水杯系统通过传导、对流和辐射与环境交换热量。');
+    });
+});

package/dist/src/learning/ragSufficiencyJudge.js

@@ -0,0 +1,171 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.reviewRagContextSufficiency = reviewRagContextSufficiency;
+function clampUnit(value) {
+    if (!Number.isFinite(value)) {
+        return 0;
+    }
+    return Number(Math.max(0, Math.min(1, value)).toFixed(4));
+}
+function hasCitation(fragment) {
+    return Array.isArray(fragment.citationIds) && fragment.citationIds.some((citationId) => String(citationId || '').trim());
+}
+function textHasSubstance(fragment) {
+    return String(fragment.text || '').trim().length >= 24;
+}
+function hasDirectSupport(fragments) {
+    return fragments.some((fragment) => fragment.role === 'direct_support' && hasCitation(fragment) && textHasSubstance(fragment));
+}
+function hasDocumentAugmentation(fragments) {
+    return fragments.some((fragment) => ((fragment.role === 'parent_context' || fragment.role === 'adjacent_context')
+        && fragment.sourceBoundary === 'full_document'
+        && textHasSubstance(fragment)));
+}
+function hasGraphEvidence(fragments) {
+    return fragments.some((fragment) => fragment.role === 'graph_neighbor_support' && hasCitation(fragment) && textHasSubstance(fragment));
+}
+function hasConflictEvidence(fragments) {
+    return fragments.some((fragment) => fragment.role === 'conflict' && textHasSubstance(fragment));
+}
+function hasIncompleteSourceScan(pack) {
+    return pack.sourceDecisions.some(decision => decision.status === 'source_window_unavailable'
+        && String(decision.reason || '').startsWith('runtime_'));
+}
+function hasUnavailableGraphNeighborSourceWindow(pack) {
+    return pack.sourceDecisions.some((decision) => (decision.status === 'source_window_unavailable'
+        && String(decision.reason || '').includes('graph_neighbor_support')));
+}
+function hasBudgetViolation(pack) {
+    return pack.sourceDecisions.some((decision) => (decision.status === 'fragment_dropped'
+        && (decision.reason === 'max_total_chars_exceeded' || decision.reason === 'max_fragments_exceeded')));
+}
+function buildDeterministicReview(params) {
+    const fragments = Array.isArray(params.contextPack.fragments) ? params.contextPack.fragments : [];
+    const directSupport = hasDirectSupport(fragments);
+    const documentAugmentation = hasDocumentAugmentation(fragments);
+    const graphEvidence = hasGraphEvidence(fragments);
+    const conflictEvidence = hasConflictEvidence(fragments);
+    const graphNeighborSourceUnavailable = hasUnavailableGraphNeighborSourceWindow(params.contextPack);
+    const budgetViolation = hasBudgetViolation(params.contextPack);
+    const reasons = [];
+    if (!directSupport) {
+        reasons.push('missing_direct_support');
+    }
+    if (!documentAugmentation) {
+        reasons.push('document_augmentation_missing');
+    }
+    const graphNeighborEvidenceMissing = Boolean(params.graphContext && (!graphEvidence || graphNeighborSourceUnavailable) && ((params.graphContext.predecessorWindow?.length || 0) > 0
+        || (params.graphContext.successorWindow?.length || 0) > 0));
+    if (graphNeighborEvidenceMissing) {
+        reasons.push('graph_neighbor_evidence_missing');
+    }
+    if (conflictEvidence) {
+        reasons.push('conflict_evidence_present');
+    }
+    if (budgetViolation) {
+        reasons.push('context_budget_dropped_fragments');
+    }
+    const incompleteSourceScan = hasIncompleteSourceScan(params.contextPack);
+    if (incompleteSourceScan)
+        reasons.push('source_scan_incomplete');
+    if (!directSupport) {
+        return {
+            reviewedAt: String(params.reviewedAt || new Date().toISOString()),
+            status: 'insufficient',
+            score: 0.2,
+            reasons,
+            deterministic: true,
+            recoveryAttempted: false,
+            llmJudgeUsed: false,
+            degradationState: 'insufficient_evidence',
+        };
+    }
+    let score = 0.58;
+    if (documentAugmentation) {
+        score += 0.24;
+    }
+    if (graphEvidence) {
+        score += 0.08;
+    }
+    if (!budgetViolation) {
+        score += 0.06;
+    }
+    if (conflictEvidence) {
+        score -= 0.18;
+    }
+    score = clampUnit(score);
+    const status = score >= 0.75
+        && documentAugmentation
+        && !conflictEvidence
+        && !graphNeighborEvidenceMissing
+        && !incompleteSourceScan
+        ? 'sufficient'
+        : 'borderline';
+    return {
+        reviewedAt: String(params.reviewedAt || new Date().toISOString()),
+        status,
+        score,
+        reasons,
+        deterministic: true,
+        recoveryAttempted: false,
+        llmJudgeUsed: false,
+        degradationState: status === 'sufficient'
+            ? 'none'
+            : conflictEvidence
+                ? 'conflict'
+                : 'partial_coverage',
+    };
+}
+function mergeLlmJudgeReview(deterministicReview, judgeReview) {
+    if (!judgeReview) {
+        return deterministicReview;
+    }
+    const nextStatus = judgeReview.status === 'sufficient'
+        || judgeReview.status === 'borderline'
+        || judgeReview.status === 'insufficient'
+        ? judgeReview.status
+        : deterministicReview.status;
+    const nextScore = Number.isFinite(judgeReview.score)
+        ? clampUnit(Number(judgeReview.score))
+        : deterministicReview.score;
+    const nextReasons = Array.isArray(judgeReview.reasons) && judgeReview.reasons.length > 0
+        ? judgeReview.reasons.map((reason) => String(reason || '').trim()).filter(Boolean)
+        : deterministicReview.reasons;
+    return {
+        ...deterministicReview,
+        ...judgeReview,
+        status: nextStatus,
+        score: nextScore,
+        reasons: nextReasons,
+        deterministic: false,
+        llmJudgeUsed: true,
+    };
+}
+async function reviewRagContextSufficiency(params) {
+    const deterministicReview = buildDeterministicReview(params);
+    if (deterministicReview.status !== 'borderline'
+        || params.allowLlmJudge !== true
+        || typeof params.llmJudge !== 'function'
+        || hasIncompleteSourceScan(params.contextPack)) {
+        return deterministicReview;
+    }
+    try {
+        const judgeReview = await params.llmJudge({
+            signal: params.signal,
+            query: params.query,
+            contextPack: params.contextPack,
+            graphContext: params.graphContext,
+        });
+        return mergeLlmJudgeReview(deterministicReview, judgeReview);
+    }
+    catch (error) {
+        return {
+            ...deterministicReview,
+            reasons: [
+                ...deterministicReview.reasons,
+                `llm_judge_failed:${String(error?.message || error || 'unknown')}`,
+            ],
+            llmJudgeUsed: false,
+        };
+    }
+}

package/dist/src/learning/ragSufficiencyJudge.test.js

@@ -0,0 +1,177 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ragSufficiencyJudge_1 = require("./ragSufficiencyJudge");
+function makeFragment(overrides = {}) {
+    const text = overrides.text || 'A water glass is a transparent drinking vessel that contains water.';
+    return {
+        fragmentId: overrides.fragmentId || `fragment_${overrides.role || 'direct_support'}`,
+        role: overrides.role || 'direct_support',
+        text,
+        atomId: overrides.atomId || 'atom_water_glass',
+        documentId: overrides.documentId || 'doc_water_glass',
+        sourcePath: overrides.sourcePath || 'Knowledge_Base/test/water-glass.md',
+        title: overrides.title || 'Water Glass',
+        headingPath: Array.isArray(overrides.headingPath) ? overrides.headingPath : ['Water Glass'],
+        startOffset: overrides.startOffset,
+        endOffset: overrides.endOffset,
+        startLine: overrides.startLine,
+        endLine: overrides.endLine,
+        charCount: text.length,
+        tokenEstimate: Math.ceil(text.length / 4),
+        truncated: overrides.truncated === true,
+        truncationReason: overrides.truncationReason,
+        citationIds: Array.isArray(overrides.citationIds) ? overrides.citationIds : ['evidence_water_glass'],
+        relationEdgeIds: Array.isArray(overrides.relationEdgeIds) ? overrides.relationEdgeIds : [],
+        score: Number.isFinite(overrides.score) ? Number(overrides.score) : 0.8,
+        sourceBoundary: overrides.sourceBoundary || 'direct_span_only',
+    };
+}
+function makePack(fragments) {
+    return {
+        query: 'what is water glass?',
+        generatedAt: '2026-07-05T00:00:00.000Z',
+        sourceBoundary: fragments.some((fragment) => fragment.sourceBoundary === 'full_document')
+            ? 'full_document'
+            : 'direct_span_only',
+        budget: {
+            maxFragments: 8,
+            maxCharsPerFragment: 800,
+            maxTotalChars: 2400,
+        },
+        fragments,
+        sourceDecisions: [],
+        totalCharCount: fragments.reduce((sum, fragment) => sum + fragment.charCount, 0),
+        tokenEstimate: fragments.reduce((sum, fragment) => sum + fragment.tokenEstimate, 0),
+    };
+}
+describe('reviewRagContextSufficiency', () => {
+    test('marks direct citation plus document augmentation as sufficient without using LLM review', async () => {
+        const llmJudge = jest.fn();
+        const review = await (0, ragSufficiencyJudge_1.reviewRagContextSufficiency)({
+            query: 'what is water glass?',
+            contextPack: makePack([
+                makeFragment({
+                    role: 'direct_support',
+                    text: 'A water glass is a transparent drinking vessel that contains water.',
+                }),
+                makeFragment({
+                    role: 'parent_context',
+                    text: '## Definition\n\nA water glass is a transparent drinking vessel that contains water.\n\nThe vessel boundary and water surface define the observed optical behavior.',
+                    sourceBoundary: 'full_document',
+                }),
+            ]),
+            llmJudge,
+        });
+        expect(review.status).toBe('sufficient');
+        expect(review.score).toBeGreaterThanOrEqual(0.75);
+        expect(review.deterministic).toBe(true);
+        expect(review.llmJudgeUsed).toBe(false);
+        expect(llmJudge).not.toHaveBeenCalled();
+    });
+    test('marks missing direct support as insufficient instead of allowing fluent overreach', async () => {
+        const review = await (0, ragSufficiencyJudge_1.reviewRagContextSufficiency)({
+            query: 'what is water glass?',
+            contextPack: makePack([
+                makeFragment({
+                    role: 'background',
+                    text: 'Background note about liquids and containers.',
+                    citationIds: [],
+                }),
+            ]),
+        });
+        expect(review.status).toBe('insufficient');
+        expect(review.degradationState).toBe('insufficient_evidence');
+        expect(review.reasons).toContain('missing_direct_support');
+    });
+    test('keeps direct-span-only answers borderline so callers can recover once', async () => {
+        const review = await (0, ragSufficiencyJudge_1.reviewRagContextSufficiency)({
+            query: 'what is water glass?',
+            contextPack: makePack([
+                makeFragment({
+                    role: 'direct_support',
+                    text: 'A water glass is a transparent drinking vessel that contains water.',
+                }),
+            ]),
+        });
+        expect(review.status).toBe('borderline');
+        expect(review.degradationState).toBe('partial_coverage');
+        expect(review.reasons).toEqual(expect.arrayContaining([
+            'document_augmentation_missing',
+        ]));
+    });
+    test('degrades graph evidence when graph-neighbor source windows are unavailable', async () => {
+        const pack = makePack([
+            makeFragment({
+                role: 'direct_support',
+                text: 'A brittle glass vessel is stiff and transparent but has low impact tolerance.',
+                documentId: 'doc_brittle_glass',
+                sourcePath: 'Knowledge_Base/test/brittle-glass.md',
+            }),
+            makeFragment({
+                role: 'parent_context',
+                text: '# Brittle Glass Vessel\n\nA brittle glass vessel is stiff and transparent but has low impact tolerance.',
+                documentId: 'doc_brittle_glass',
+                sourcePath: 'Knowledge_Base/test/brittle-glass.md',
+                sourceBoundary: 'full_document',
+            }),
+            makeFragment({
+                role: 'graph_neighbor_support',
+                text: 'Missing neighbor evidence should not be treated as complete graph evidence.',
+                atomId: 'atom_missing_neighbor',
+                documentId: 'doc_missing_neighbor',
+                sourcePath: 'Knowledge_Base/test/missing-neighbor.md',
+                title: 'Missing Neighbor Evidence',
+                sourceBoundary: 'direct_span_only',
+            }),
+        ]);
+        pack.sourceDecisions = [
+            {
+                documentId: 'doc_brittle_glass',
+                sourcePath: 'Knowledge_Base/test/brittle-glass.md',
+                sourceBoundary: 'full_document',
+                status: 'read',
+            },
+            {
+                documentId: 'doc_missing_neighbor',
+                sourcePath: 'Knowledge_Base/test/missing-neighbor.md',
+                sourceBoundary: 'direct_span_only',
+                status: 'source_window_unavailable',
+                reason: 'source_resolver_returned_no_content:graph_neighbor_support',
+            },
+        ];
+        const review = await (0, ragSufficiencyJudge_1.reviewRagContextSufficiency)({
+            query: 'compare brittle glass vessel with missing neighbor evidence',
+            contextPack: pack,
+            graphContext: {
+                anchorAtomId: 'atom_brittle_glass',
+                anchorTitle: 'Brittle Glass Vessel',
+                anchorDocumentId: 'doc_brittle_glass',
+                predecessorWindow: [],
+                successorWindow: [
+                    {
+                        atomId: 'atom_missing_neighbor',
+                        title: 'Missing Neighbor Evidence',
+                        relationKind: 'analogy',
+                        confidence: 0.91,
+                    },
+                ],
+                supportingAtomIds: ['atom_missing_neighbor'],
+                supportingTitles: ['Missing Neighbor Evidence'],
+                relationKinds: ['analogy'],
+                relationSummaries: [],
+                knowledgePointRelations: [],
+                temporalValidity: {
+                    checkedAt: '2026-07-05T00:00:00.000Z',
+                    allPointsValid: true,
+                    warningReasons: [],
+                    invalidKnowledgePointTitles: [],
+                    edgeKinds: [],
+                    details: [],
+                },
+            },
+        });
+        expect(review.status).toBe('borderline');
+        expect(review.degradationState).toBe('partial_coverage');
+        expect(review.reasons).toContain('graph_neighbor_evidence_missing');
+    });
+});