noteconnection 1.7.0 → 1.9.0

package/dist/src/learning/ragContextPack.js

@@ -0,0 +1,356 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_RAG_CONTEXT_BUDGET = void 0;
+exports.normalizeRagContextBudget = normalizeRagContextBudget;
+exports.estimateRagTokenCount = estimateRagTokenCount;
+exports.buildRagContextPack = buildRagContextPack;
+const crypto_1 = require("crypto");
+const graphClaimMatcher_1 = require("./graphClaimMatcher");
+const ragPublicText_1 = require("./ragPublicText");
+exports.DEFAULT_RAG_CONTEXT_BUDGET = {
+    maxFragments: 16,
+    maxCharsPerFragment: 1600,
+    maxTotalChars: 6400,
+};
+const ROLE_PRIORITY = {
+    direct_support: 0,
+    conflict: 1,
+    graph_neighbor_support: 2,
+    parent_context: 3,
+    adjacent_context: 4,
+    background: 5,
+};
+function normalizeRagContextBudget(input) {
+    const productCapDisabled = input?.productCapDisabled === true;
+    const maxFragmentsLimit = productCapDisabled ? 4096 : 512;
+    const maxTotalCharsLimit = productCapDisabled ? 512000 : 512000;
+    const numberOrDefault = (value, fallback, min, max) => {
+        const numeric = Number(value);
+        if (!Number.isFinite(numeric)) {
+            return fallback;
+        }
+        return Math.floor(Math.max(min, Math.min(max, numeric)));
+    };
+    return {
+        maxFragments: numberOrDefault(input?.maxFragments, exports.DEFAULT_RAG_CONTEXT_BUDGET.maxFragments, 1, maxFragmentsLimit),
+        maxCharsPerFragment: numberOrDefault(input?.maxCharsPerFragment, exports.DEFAULT_RAG_CONTEXT_BUDGET.maxCharsPerFragment, 80, 20000),
+        maxTotalChars: numberOrDefault(input?.maxTotalChars, exports.DEFAULT_RAG_CONTEXT_BUDGET.maxTotalChars, 120, maxTotalCharsLimit),
+        ...(productCapDisabled ? {
+            productCapDisabled: true,
+            runtimeMaxFragments: numberOrDefault(input?.runtimeMaxFragments, input?.maxFragments ?? exports.DEFAULT_RAG_CONTEXT_BUDGET.maxFragments, 1, 4096),
+            runtimeMaxCharsPerFragment: numberOrDefault(input?.runtimeMaxCharsPerFragment, input?.maxCharsPerFragment ?? exports.DEFAULT_RAG_CONTEXT_BUDGET.maxCharsPerFragment, 80, 20000),
+            runtimeMaxTotalChars: numberOrDefault(input?.runtimeMaxTotalChars, input?.maxTotalChars ?? exports.DEFAULT_RAG_CONTEXT_BUDGET.maxTotalChars, 120, 64 * 1024 * 1024),
+        } : {}),
+    };
+}
+function estimateRagTokenCount(text) {
+    const normalized = String(text || '').trim();
+    if (!normalized) {
+        return 0;
+    }
+    return Math.max(1, Math.ceil(normalized.length / 4));
+}
+const QUERY_WINDOW_STOPWORDS = new Set([
+    'and', 'compare', 'contrast', 'difference', 'the', 'versus', 'with',
+]);
+function queryWindowTerms(query) {
+    return Array.from(new Set((String(query || '').toLowerCase().match(/[a-z0-9][a-z0-9_-]{2,}|[\u3400-\u9fff]{2,}/gu) || [])
+        .filter((term) => !QUERY_WINDOW_STOPWORDS.has(term))));
+}
+function queryTermCoverage(text, terms) {
+    const normalized = text.toLowerCase();
+    return terms.reduce((count, term) => count + (normalized.includes(term) ? 1 : 0), 0);
+}
+function queryFeatureCoverage(text, queryFeatures) {
+    return (0, graphClaimMatcher_1.semanticFeatures)(text).reduce((count, feature) => count + (queryFeatures.has(feature) ? 1 : 0), 0);
+}
+function queryWindowAnchors(source, terms, queryFeatures) {
+    const anchors = new Set();
+    const normalizedSource = source.toLowerCase();
+    terms.forEach((term) => {
+        let matchIndex = normalizedSource.indexOf(term);
+        while (matchIndex >= 0) {
+            anchors.add(matchIndex);
+            matchIndex = normalizedSource.indexOf(term, matchIndex + term.length);
+        }
+    });
+    const clausePattern = /[^\n.!?。！？；;]+(?:[.!?。！？；;]+|$)/gu;
+    let clauseMatch;
+    while ((clauseMatch = clausePattern.exec(source)) !== null) {
+        if (queryFeatureCoverage(clauseMatch[0], queryFeatures) > 0) {
+            anchors.add(clauseMatch.index + Math.floor(clauseMatch[0].length / 2));
+        }
+    }
+    return Array.from(anchors).sort((left, right) => left - right);
+}
+function queryCenteredWindow(source, maxChars, query, baseline) {
+    const terms = queryWindowTerms(query);
+    const queryFeatures = new Set((0, graphClaimMatcher_1.semanticFeatures)(query));
+    if (queryFeatures.size < 2) {
+        return null;
+    }
+    const visibleSource = (0, ragPublicText_1.omitFencedMarkdownPayload)(source);
+    const markerLength = '\n[...]\n'.length;
+    const windowLength = Math.max(16, maxChars - markerLength * 2);
+    const visibleBaseline = (0, ragPublicText_1.omitFencedMarkdownPayload)(baseline);
+    const baselineFeatureCoverage = queryFeatureCoverage(visibleBaseline, queryFeatures);
+    const baselineTermCoverage = queryTermCoverage(visibleBaseline, terms);
+    let selected = null;
+    for (const anchor of queryWindowAnchors(visibleSource, terms, queryFeatures)) {
+        const start = Math.max(0, Math.min(visibleSource.length - windowLength, anchor - Math.floor(windowLength * 0.35)));
+        const candidate = visibleSource.slice(start, start + windowLength);
+        const featureCoverage = queryFeatureCoverage(candidate, queryFeatures);
+        const termCoverage = queryTermCoverage(candidate, terms);
+        if (!selected
+            || featureCoverage > selected.featureCoverage
+            || (featureCoverage === selected.featureCoverage
+                && termCoverage > selected.termCoverage)) {
+            selected = { start, text: candidate, featureCoverage, termCoverage };
+        }
+    }
+    if (!selected
+        || selected.featureCoverage < baselineFeatureCoverage
+        || (selected.featureCoverage === baselineFeatureCoverage
+            && selected.termCoverage <= baselineTermCoverage)) {
+        return null;
+    }
+    const prefix = selected.start > 0 ? '[...]\n' : '';
+    const suffix = selected.start + selected.text.length < visibleSource.length ? '\n[...]' : '';
+    return `${prefix}${selected.text.trim()}${suffix}`;
+}
+function truncateMiddle(text, maxChars, query) {
+    const source = String(text || '');
+    if (source.length <= maxChars) {
+        return { text: source, truncated: false };
+    }
+    if (maxChars <= 16) {
+        return { text: source.slice(0, maxChars), truncated: true };
+    }
+    const marker = '\n[...]\n';
+    const available = Math.max(0, maxChars - marker.length);
+    const headLength = Math.ceil(available * 0.6);
+    const tailLength = Math.floor(available * 0.4);
+    const baseline = `${source.slice(0, headLength).trimEnd()}${marker}${source.slice(source.length - tailLength).trimStart()}`;
+    return {
+        text: queryCenteredWindow(source, maxChars, query, baseline) || baseline,
+        truncated: true,
+    };
+}
+function withBudgetedText(fragment, maxChars, reason, query) {
+    const truncated = truncateMiddle(fragment.text, maxChars, query);
+    const text = truncated.text;
+    return {
+        ...fragment,
+        text,
+        charCount: text.length,
+        tokenEstimate: estimateRagTokenCount(text),
+        truncated: fragment.truncated || truncated.truncated,
+        truncationReason: truncated.truncated ? reason : fragment.truncationReason,
+    };
+}
+function rolePriority(fragment) {
+    return ROLE_PRIORITY[fragment.role] ?? ROLE_PRIORITY.background;
+}
+function sortFragmentsForBudget(fragments, fragmentOrder) {
+    const order = new Map((fragmentOrder || []).map((fragmentId, index) => [String(fragmentId), index]));
+    return fragments
+        .map((fragment, index) => ({ fragment, index }))
+        .sort((a, b) => {
+        const priorityDelta = rolePriority(a.fragment) - rolePriority(b.fragment);
+        if (priorityDelta !== 0) {
+            return priorityDelta;
+        }
+        const scoreDelta = Number(b.fragment.score || 0) - Number(a.fragment.score || 0);
+        if (Math.abs(scoreDelta) > 0.0001) {
+            return scoreDelta;
+        }
+        const conditionedOrderDelta = (order.get(a.fragment.fragmentId) ?? Number.MAX_SAFE_INTEGER)
+            - (order.get(b.fragment.fragmentId) ?? Number.MAX_SAFE_INTEGER);
+        if (conditionedOrderDelta !== 0) {
+            return conditionedOrderDelta;
+        }
+        return a.index - b.index;
+    })
+        .map((entry) => entry.fragment);
+}
+function applyContextBudget(fragments, budget, decisions, query, fragmentOrder) {
+    const selected = [];
+    let usedChars = 0;
+    const productCapDisabled = budget.productCapDisabled === true;
+    const maxFragments = productCapDisabled
+        ? budget.runtimeMaxFragments || budget.maxFragments
+        : budget.maxFragments;
+    const maxCharsPerFragment = productCapDisabled
+        ? budget.runtimeMaxCharsPerFragment || budget.maxCharsPerFragment
+        : budget.maxCharsPerFragment;
+    const maxTotalChars = productCapDisabled
+        ? budget.runtimeMaxTotalChars || budget.maxTotalChars
+        : budget.maxTotalChars;
+    sortFragmentsForBudget(fragments, fragmentOrder).forEach((fragment) => {
+        if (selected.length >= maxFragments) {
+            decisions.push({
+                documentId: fragment.documentId,
+                sourcePath: fragment.sourcePath,
+                sourceBoundary: fragment.sourceBoundary,
+                status: 'fragment_dropped',
+                reason: productCapDisabled ? 'runtime_fragment_limit_exceeded' : 'max_fragments_exceeded',
+            });
+            return;
+        }
+        let candidate = withBudgetedText(fragment, maxCharsPerFragment, productCapDisabled ? 'runtime_max_chars_per_fragment_exceeded' : 'max_chars_per_fragment_exceeded', query);
+        const remainingChars = maxTotalChars - usedChars;
+        if (remainingChars <= 0) {
+            decisions.push({
+                documentId: fragment.documentId,
+                sourcePath: fragment.sourcePath,
+                sourceBoundary: fragment.sourceBoundary,
+                status: 'fragment_dropped',
+                reason: productCapDisabled ? 'runtime_total_chars_exceeded' : 'max_total_chars_exceeded',
+            });
+            return;
+        }
+        if (candidate.charCount > remainingChars) {
+            if (remainingChars < 80 && candidate.role !== 'direct_support') {
+                decisions.push({
+                    documentId: fragment.documentId,
+                    sourcePath: fragment.sourcePath,
+                    sourceBoundary: fragment.sourceBoundary,
+                    status: 'fragment_dropped',
+                    reason: 'remaining_context_budget_too_small',
+                });
+                return;
+            }
+            candidate = withBudgetedText(candidate, remainingChars, productCapDisabled ? 'runtime_total_chars_exceeded' : 'max_total_chars_exceeded', query);
+        }
+        selected.push(candidate);
+        usedChars += candidate.charCount;
+        decisions.push({
+            documentId: candidate.documentId,
+            sourcePath: candidate.sourcePath,
+            sourceBoundary: candidate.sourceBoundary,
+            status: candidate.truncated ? 'fragment_truncated' : 'fragment_included',
+            reason: candidate.truncationReason,
+        });
+    });
+    return selected;
+}
+function resolveSourceBoundary(requestedBoundary, fragments) {
+    if (requestedBoundary) {
+        return requestedBoundary;
+    }
+    return fragments.some((fragment) => fragment.sourceBoundary === 'full_document')
+        ? 'full_document'
+        : 'direct_span_only';
+}
+function annotateReadDecisions(decisions, fragments) {
+    const fragmentCountsByDocument = fragments.reduce((counts, fragment) => {
+        const previous = counts.get(fragment.documentId) || 0;
+        counts.set(fragment.documentId, previous + 1);
+        return counts;
+    }, new Map());
+    decisions.forEach((decision) => {
+        if (decision.status === 'read') {
+            decision.fragmentsSelected = fragmentCountsByDocument.get(decision.documentId) || 0;
+        }
+    });
+}
+function sortedStrings(values) {
+    return normalizedStrings(values).sort();
+}
+function normalizedStrings(values) {
+    return (Array.isArray(values) ? values : [])
+        .map((value) => String(value || '').trim())
+        .filter(Boolean);
+}
+function buildRagContextReplayId(params) {
+    const payload = {
+        query: params.query,
+        sourceBoundary: params.sourceBoundary,
+        budget: params.budget,
+        totalCharCount: params.totalCharCount,
+        tokenEstimate: params.tokenEstimate,
+        fragments: params.fragments
+            .map((fragment) => ({
+            fragmentId: fragment.fragmentId,
+            role: fragment.role,
+            documentId: fragment.documentId,
+            sourcePath: fragment.sourcePath,
+            atomId: fragment.atomId || '',
+            title: fragment.title || '',
+            headingPath: normalizedStrings(fragment.headingPath),
+            citationIds: sortedStrings(fragment.citationIds),
+            relationEdgeIds: sortedStrings(fragment.relationEdgeIds),
+            sourceBoundary: fragment.sourceBoundary,
+            startOffset: fragment.startOffset ?? null,
+            endOffset: fragment.endOffset ?? null,
+            startLine: fragment.startLine ?? null,
+            endLine: fragment.endLine ?? null,
+            truncated: fragment.truncated,
+            truncationReason: fragment.truncationReason || '',
+            text: fragment.text,
+        }))
+            .sort((left, right) => [
+            left.role.localeCompare(right.role),
+            left.documentId.localeCompare(right.documentId),
+            left.fragmentId.localeCompare(right.fragmentId),
+            left.text.localeCompare(right.text),
+        ].find((delta) => delta !== 0) || 0),
+        sourceDecisions: params.sourceDecisions
+            .map((decision) => ({
+            documentId: decision.documentId,
+            sourcePath: decision.sourcePath,
+            sourceBoundary: decision.sourceBoundary,
+            status: decision.status,
+            reason: decision.reason || '',
+            charsRead: decision.charsRead ?? null,
+            fragmentsSelected: decision.fragmentsSelected ?? null,
+        }))
+            .sort((left, right) => [
+            left.documentId.localeCompare(right.documentId),
+            left.sourcePath.localeCompare(right.sourcePath),
+            left.sourceBoundary.localeCompare(right.sourceBoundary),
+            left.status.localeCompare(right.status),
+            left.reason.localeCompare(right.reason),
+        ].find((delta) => delta !== 0) || 0),
+        graphConditioning: params.graphConditioning || null,
+    };
+    const digest = (0, crypto_1.createHash)('sha256')
+        .update(JSON.stringify(payload))
+        .digest('hex')
+        .slice(0, 16);
+    return `ragctx_${digest}`;
+}
+function buildRagContextPack(params) {
+    const budget = normalizeRagContextBudget(params.budget);
+    const decisions = Array.isArray(params.sourceDecisions)
+        ? params.sourceDecisions.map((decision) => ({ ...decision }))
+        : [];
+    const fragments = Array.isArray(params.fragments) ? params.fragments.filter(Boolean) : [];
+    const selectedFragments = applyContextBudget(fragments, budget, decisions, params.query, params.fragmentOrder);
+    annotateReadDecisions(decisions, selectedFragments);
+    const totalCharCount = selectedFragments.reduce((sum, fragment) => sum + fragment.charCount, 0);
+    const tokenEstimate = selectedFragments.reduce((sum, fragment) => sum + fragment.tokenEstimate, 0);
+    const query = String(params.query || '');
+    const sourceBoundary = resolveSourceBoundary(params.sourceBoundary, selectedFragments);
+    return {
+        replayId: buildRagContextReplayId({
+            query,
+            sourceBoundary,
+            budget,
+            fragments: selectedFragments,
+            sourceDecisions: decisions,
+            totalCharCount,
+            tokenEstimate,
+            graphConditioning: params.graphConditioning,
+        }),
+        query,
+        generatedAt: String(params.generatedAt || new Date().toISOString()),
+        sourceBoundary,
+        budget,
+        fragments: selectedFragments,
+        sourceDecisions: decisions,
+        totalCharCount,
+        tokenEstimate,
+        graphConditioning: params.graphConditioning,
+    };
+}

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

@@ -0,0 +1,311 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ragContextPack_1 = require("./ragContextPack");
+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',
+    };
+}
+describe('buildRagContextPack', () => {
+    test('generates a stable replay id from the selected evidence payload', () => {
+        const direct = makeFragment({
+            fragmentId: 'direct_water_glass',
+            role: 'direct_support',
+            text: 'Direct definition of water glass.',
+            score: 0.72,
+        });
+        const parent = makeFragment({
+            fragmentId: 'parent_water_glass',
+            role: 'parent_context',
+            text: 'Parent section explains the vessel boundary and optical qualifier.',
+            sourceBoundary: 'full_document',
+            score: 0.61,
+        });
+        const baseParams = {
+            query: 'what is water glass?',
+            sourceDecisions: [
+                {
+                    documentId: 'doc_water_glass',
+                    sourcePath: 'Knowledge_Base/test/water-glass.md',
+                    sourceBoundary: 'full_document',
+                    status: 'read',
+                    charsRead: 4096,
+                },
+            ],
+            budget: {
+                maxFragments: 4,
+                maxCharsPerFragment: 400,
+                maxTotalChars: 900,
+            },
+            generatedAt: '2026-07-05T00:00:00.000Z',
+        };
+        const firstPack = (0, ragContextPack_1.buildRagContextPack)({
+            ...baseParams,
+            fragments: [parent, direct],
+        });
+        const secondPack = (0, ragContextPack_1.buildRagContextPack)({
+            ...baseParams,
+            fragments: [direct, parent],
+        });
+        const changedPack = (0, ragContextPack_1.buildRagContextPack)({
+            ...baseParams,
+            fragments: [
+                direct,
+                {
+                    ...parent,
+                    text: 'Parent section now carries a different qualifier.',
+                    charCount: 'Parent section now carries a different qualifier.'.length,
+                },
+            ],
+        });
+        expect(firstPack.replayId).toMatch(/^ragctx_[a-f0-9]{16}$/);
+        expect(secondPack.replayId).toBe(firstPack.replayId);
+        expect(changedPack.replayId).not.toBe(firstPack.replayId);
+    });
+    test('middle-truncates oversized fragments while preserving the opening and terminal qualifier', () => {
+        const longText = [
+            'Opening definition: a water glass is a transparent vessel.',
+            'Middle detail '.repeat(30),
+            'Terminal qualifier: this claim only covers the scoped note.',
+        ].join('\n');
+        const pack = (0, ragContextPack_1.buildRagContextPack)({
+            query: 'what is water glass?',
+            fragments: [
+                makeFragment({
+                    role: 'parent_context',
+                    text: longText,
+                    sourceBoundary: 'full_document',
+                }),
+            ],
+            sourceDecisions: [],
+            budget: {
+                maxFragments: 3,
+                maxCharsPerFragment: 180,
+                maxTotalChars: 220,
+            },
+            generatedAt: '2026-07-05T00:00:00.000Z',
+        });
+        expect(pack.fragments).toHaveLength(1);
+        expect(pack.fragments[0].truncated).toBe(true);
+        expect(pack.fragments[0].text).toContain('Opening definition');
+        expect(pack.fragments[0].text).toContain('Terminal qualifier');
+        expect(pack.fragments[0].text).toContain('[...]');
+        expect(pack.sourceDecisions).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                status: 'fragment_truncated',
+                reason: 'max_chars_per_fragment_exceeded',
+            }),
+        ]));
+    });
+    test('centers the bounded window on query terms when a later comparison clause would otherwise be dropped', () => {
+        const longText = [
+            'Opening definition: a water glass is a transparent vessel.',
+            'Background context '.repeat(28),
+            'Comparison: a plastic cup is lightweight and less rigid than a water glass.',
+            'Terminal qualifier: the comparison remains limited to the scoped note.',
+        ].join('\n');
+        const pack = (0, ragContextPack_1.buildRagContextPack)({
+            query: 'compare water glass and plastic cup',
+            fragments: [
+                makeFragment({
+                    role: 'parent_context',
+                    text: longText,
+                    sourceBoundary: 'full_document',
+                }),
+            ],
+            sourceDecisions: [],
+            budget: {
+                maxFragments: 3,
+                maxCharsPerFragment: 180,
+                maxTotalChars: 220,
+            },
+            generatedAt: '2026-07-05T00:00:00.000Z',
+        });
+        expect(pack.fragments[0].text).toContain('plastic cup');
+        expect(pack.fragments[0].text).toContain('water glass');
+    });
+    test('prefers multilingual comparison prose outside fenced renderer payloads', () => {
+        const longText = [
+            'Opening definition: a water glass is a transparent vessel.',
+            'Background context '.repeat(20),
+            '```mermaid',
+            'graph LR',
+            'A[Water Glass] --> B[Plastic Cup PET]',
+            '```',
+            '相同尺寸下，PET塑料杯比玻璃水杯更轻、更有韧性，但刚度和透明度较低。',
+            'Terminal qualifier: the comparison remains limited to the scoped note.',
+        ].join('\n');
+        const pack = (0, ragContextPack_1.buildRagContextPack)({
+            query: 'compare water glass and plastic cup',
+            fragments: [makeFragment({
+                    role: 'parent_context',
+                    text: longText,
+                    sourceBoundary: 'full_document',
+                })],
+            sourceDecisions: [],
+            budget: {
+                maxFragments: 3,
+                maxCharsPerFragment: 180,
+                maxTotalChars: 220,
+            },
+        });
+        expect(pack.fragments[0].text).toContain('PET塑料杯');
+        expect(pack.fragments[0].text).not.toContain('graph LR');
+    });
+    test('uses role priority so weak background cannot displace direct or graph evidence', () => {
+        const pack = (0, ragContextPack_1.buildRagContextPack)({
+            query: 'what is water glass?',
+            fragments: [
+                makeFragment({
+                    fragmentId: 'background_1',
+                    role: 'background',
+                    text: 'Background note with weak topical overlap.',
+                    score: 0.95,
+                }),
+                makeFragment({
+                    fragmentId: 'direct_1',
+                    role: 'direct_support',
+                    text: 'Direct definition of water glass.',
+                    score: 0.7,
+                }),
+                makeFragment({
+                    fragmentId: 'graph_1',
+                    role: 'graph_neighbor_support',
+                    text: 'Graph neighbor evidence about vessel boundary.',
+                    score: 0.6,
+                    sourceBoundary: 'full_document',
+                }),
+            ],
+            sourceDecisions: [],
+            budget: {
+                maxFragments: 2,
+                maxCharsPerFragment: 200,
+                maxTotalChars: 400,
+            },
+        });
+        expect(pack.fragments.map((fragment) => fragment.fragmentId)).toEqual(['direct_1', 'graph_1']);
+        expect(pack.sourceDecisions).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                status: 'fragment_dropped',
+                reason: 'max_fragments_exceeded',
+                documentId: 'doc_water_glass',
+            }),
+        ]));
+    });
+    test('uses graph-conditioned order only as a tie-break inside the same role and score', () => {
+        const pack = (0, ragContextPack_1.buildRagContextPack)({
+            query: 'what is water glass?',
+            fragments: [
+                makeFragment({ fragmentId: 'graph-unmatched', role: 'graph_neighbor_support', score: 0.6 }),
+                makeFragment({ fragmentId: 'graph-matched', role: 'graph_neighbor_support', score: 0.6 }),
+                makeFragment({ fragmentId: 'direct', role: 'direct_support', score: 0.4 }),
+            ],
+            fragmentOrder: ['graph-matched', 'graph-unmatched', 'direct'],
+            sourceDecisions: [],
+            budget: {
+                maxFragments: 3,
+                maxCharsPerFragment: 200,
+                maxTotalChars: 600,
+            },
+        });
+        expect(pack.fragments.map((fragment) => fragment.fragmentId)).toEqual([
+            'direct',
+            'graph-matched',
+            'graph-unmatched',
+        ]);
+    });
+    test('unbounded product mode ignores product caps while retaining explicit runtime limits', () => {
+        const pack = (0, ragContextPack_1.buildRagContextPack)({
+            query: 'what is water glass?',
+            fragments: Array.from({ length: 4 }, (_, index) => makeFragment({
+                fragmentId: `unbounded_${index}`,
+                role: 'parent_context',
+                text: `Section ${index}: ${'water glass evidence '.repeat(12)}`,
+                sourceBoundary: 'full_document',
+            })),
+            sourceDecisions: [],
+            budget: {
+                maxFragments: 1,
+                maxCharsPerFragment: 100,
+                maxTotalChars: 120,
+                productCapDisabled: true,
+                runtimeMaxFragments: 8,
+                runtimeMaxCharsPerFragment: 900,
+                runtimeMaxTotalChars: 10000,
+            },
+        });
+        expect(pack.fragments).toHaveLength(4);
+        expect(pack.budget.productCapDisabled).toBe(true);
+        expect(pack.sourceDecisions).not.toEqual(expect.arrayContaining([
+            expect.objectContaining({ reason: 'max_fragments_exceeded' }),
+        ]));
+    });
+    test('preserves the configured max tier instead of applying the legacy 200-fragment/100k cap', () => {
+        const pack = (0, ragContextPack_1.buildRagContextPack)({
+            query: 'max budget probe',
+            fragments: Array.from({ length: 260 }, (_, index) => makeFragment({
+                fragmentId: `max_tier_${index}`,
+                role: 'direct_support',
+                text: `Max tier evidence ${index}.`,
+                sourceBoundary: 'full_document',
+            })),
+            sourceDecisions: [],
+            budget: {
+                maxFragments: 256,
+                maxCharsPerFragment: 16000,
+                maxTotalChars: 256000,
+            },
+        });
+        expect(pack.budget.maxFragments).toBe(256);
+        expect(pack.budget.maxTotalChars).toBe(256000);
+        expect(pack.fragments).toHaveLength(256);
+    });
+    test('unbounded mode reports a runtime fragment stop instead of silently dropping content', () => {
+        const pack = (0, ragContextPack_1.buildRagContextPack)({
+            query: 'what is water glass?',
+            fragments: Array.from({ length: 4 }, (_, index) => makeFragment({
+                fragmentId: `runtime_limited_${index}`,
+                role: 'parent_context',
+                text: `Runtime section ${index}: water glass evidence.`,
+                sourceBoundary: 'full_document',
+            })),
+            sourceDecisions: [],
+            budget: {
+                maxFragments: 1,
+                maxCharsPerFragment: 100,
+                maxTotalChars: 120,
+                productCapDisabled: true,
+                runtimeMaxFragments: 2,
+                runtimeMaxCharsPerFragment: 900,
+                runtimeMaxTotalChars: 10000,
+            },
+        });
+        expect(pack.fragments).toHaveLength(2);
+        expect(pack.sourceDecisions).toEqual(expect.arrayContaining([
+            expect.objectContaining({
+                status: 'fragment_dropped',
+                reason: 'runtime_fragment_limit_exceeded',
+            }),
+        ]));
+    });
+});