noteconnection 1.7.0 → 1.9.0

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

@@ -0,0 +1,907 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const graphAnswerPlan_1 = require("./graphAnswerPlan");
+const knowledgePoint = {
+    atomId: 'water_glass',
+    atomIds: ['water_glass', 'material_boundary', 'thermal_exchange'],
+    documentId: 'doc_water_glass',
+    sourcePath: 'Knowledge_Base/waterglass/water-glass.md',
+    title: 'Water Glass',
+    summary: 'A water glass is a transparent drinking vessel.',
+    evidenceSnippet: 'A water glass is a transparent drinking vessel.',
+    score: 0.98,
+    citation: null,
+    citations: [],
+    matchedSpans: [
+        {
+            atomId: 'water_glass',
+            title: 'Water Glass',
+            snippet: 'A water glass is a transparent drinking vessel used to contain water.',
+            sourcePath: 'Knowledge_Base/waterglass/water-glass.md',
+            score: 0.98,
+            citation: null,
+        },
+        {
+            atomId: 'material_boundary',
+            title: 'Material Boundary',
+            snippet: 'Its solid wall forms a material boundary between the liquid and the surrounding environment.',
+            sourcePath: 'Knowledge_Base/waterglass/water-glass.md',
+            score: 0.91,
+            citation: null,
+        },
+        {
+            atomId: 'thermal_exchange',
+            title: 'Thermal Exchange',
+            snippet: 'Heat moves through the glass wall, so the material and thickness affect thermal exchange.',
+            sourcePath: 'Knowledge_Base/waterglass/water-glass.md',
+            score: 0.9,
+            citation: null,
+        },
+    ],
+    matchCount: 3,
+    relationPath: [],
+    relationPathAtomIds: [],
+    relationKinds: [],
+    capabilities: [],
+};
+const graphContext = {
+    anchorAtomId: 'water_glass',
+    anchorTitle: 'Water Glass',
+    anchorGraphProfile: { atomId: 'water_glass', title: 'Water Glass', inDegree: 2, outDegree: 3 },
+    supportingAtomIds: ['container', 'heat_transfer'],
+    supportingTitles: ['Container', 'Heat Transfer'],
+    relationKinds: ['prerequisite', 'application'],
+    relationSummaries: [],
+    knowledgePointRelations: [{
+            edgeId: 'edge_water_heat',
+            relationKind: 'application',
+            sourceAtomId: 'water_glass',
+            sourceTitle: 'Water Glass',
+            targetAtomId: 'heat_transfer',
+            targetTitle: 'Heat Transfer',
+            confidence: 0.88,
+        }],
+    predecessorWindow: [
+        { atomId: 'container', title: 'Container', relationKind: 'prerequisite', confidence: 0.92 },
+    ],
+    successorWindow: [
+        { atomId: 'heat_transfer', title: 'Heat Transfer', relationKind: 'application', confidence: 0.88 },
+    ],
+    temporalValidity: {
+        checkedAt: '2026-07-11T00:00:00.000Z',
+        allPointsValid: true,
+        warningReasons: [],
+        invalidKnowledgePointTitles: [],
+    },
+};
+const ragContextPack = {
+    query: 'what is water glass',
+    generatedAt: '2026-07-11T00:00:00.000Z',
+    sourceBoundary: 'full_document',
+    budget: { maxFragments: 20, maxCharsPerFragment: 1500, maxTotalChars: 7600 },
+    fragments: [
+        {
+            fragmentId: 'neighbor_heat_transfer',
+            role: 'graph_neighbor_support',
+            text: 'Heat Transfer explains why the glass wall conducts heat between the drink and the environment.',
+            atomId: 'heat_transfer',
+            documentId: 'doc_heat_transfer',
+            sourcePath: 'Knowledge_Base/physics/heat-transfer.md',
+            title: 'Heat Transfer',
+            headingPath: ['Heat Transfer'],
+            charCount: 96,
+            tokenEstimate: 24,
+            truncated: false,
+            citationIds: ['citation_heat_transfer'],
+            relationEdgeIds: ['edge_water_heat'],
+            sourceBoundary: 'full_document',
+            score: 0.88,
+        },
+    ],
+    sourceDecisions: [],
+    totalCharCount: 96,
+    tokenEstimate: 24,
+};
+describe('buildGraphAnswerPlan', () => {
+    test('drops truncated math clauses instead of publishing an incomplete formula', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'what is amorphous ice?',
+            knowledgePoints: [{
+                    ...knowledgePoint,
+                    atomId: 'amorphous_ice',
+                    title: 'Amorphous Ice',
+                    sourcePath: 'Knowledge_Base/waterglass/Amorphous ice.md',
+                    summary: 'Amorphous ice is a solid form of water.',
+                    evidenceSnippet: 'Amorphous ice is a solid form of water.',
+                    matchedSpans: [{
+                            atomId: 'amorphous_ice_math',
+                            title: 'Core Mathematics',
+                            snippet: 'The radial distribution function is defined by $$g(r) = \\frac{V}{N^2} \\left\\langle \\sum_{i=1}^{N} \\delta(\\mathbf{r} - (\\mathb',
+                            sourcePath: 'Knowledge_Base/waterglass/Amorphous ice.md',
+                            score: 0.93,
+                            citation: null,
+                        }],
+                }],
+            graphContext,
+        });
+        expect(plan.claims.some((claim) => claim.statement.includes('\\mathb'))).toBe(false);
+    });
+    test('models compound definition and learning-route deliverables separately', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'what is amorphous ice? Which knowledge points should I learn?',
+            knowledgePoints: [{
+                    ...knowledgePoint,
+                    atomId: 'amorphous_ice',
+                    atomIds: ['amorphous_ice', 'water_structure', 'radial_distribution', 'glass_transition'],
+                    documentId: 'doc_amorphous_ice',
+                    sourcePath: 'Knowledge_Base/waterglass/Amorphous ice.md',
+                    title: 'Amorphous Ice',
+                    summary: 'Amorphous ice is a solid form of water without long-range crystalline order.',
+                    evidenceSnippet: 'Amorphous ice is a solid form of water without long-range crystalline order.',
+                    matchedSpans: [
+                        {
+                            atomId: 'amorphous_ice',
+                            title: 'Amorphous Ice',
+                            snippet: 'Amorphous ice is a solid form of water without long-range crystalline order.',
+                            sourcePath: 'Knowledge_Base/waterglass/Amorphous ice.md',
+                            score: 0.98,
+                            citation: null,
+                        },
+                        {
+                            atomId: 'water_structure',
+                            title: 'Water Molecular Structure',
+                            snippet: 'Water molecules and hydrogen bonding explain the local structure of ice.',
+                            sourcePath: 'Knowledge_Base/waterglass/Amorphous ice.md',
+                            score: 0.86,
+                            citation: null,
+                        },
+                        {
+                            atomId: 'radial_distribution',
+                            title: 'Radial Distribution Function',
+                            snippet: 'The radial distribution function g(r) distinguishes short-range from long-range order.',
+                            sourcePath: 'Knowledge_Base/waterglass/Amorphous ice.md',
+                            score: 0.84,
+                            citation: null,
+                        },
+                    ],
+                }],
+            graphContext,
+        });
+        expect(plan.answerTaskPlan).toEqual(expect.objectContaining({
+            schemaVersion: '1',
+            primarySubject: 'Amorphous Ice',
+            subtasks: expect.arrayContaining([
+                expect.objectContaining({ kind: 'definition', required: true }),
+                expect.objectContaining({ kind: 'learning_route', required: true, expectedOutput: 'ordered_nodes' }),
+            ]),
+        }));
+        expect(plan.answerTaskPlan?.learningRoute?.length).toBeGreaterThanOrEqual(3);
+        expect(plan.answerTaskPlan?.learningRoute?.map((node) => node.title)).toEqual(expect.arrayContaining([
+            'Amorphous Ice',
+            'Water Molecular Structure',
+            'Radial Distribution Function',
+        ]));
+    });
+    test('turns grouped anchor spans and evidenced graph neighbors into required semantic claims', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'what is water glass',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack,
+        });
+        expect(plan.anchorAtomId).toBe('water_glass');
+        expect(plan.claims.map((claim) => claim.role)).toEqual(expect.arrayContaining([
+            'definition',
+            'boundary',
+            'mechanism',
+            'application',
+        ]));
+        expect(plan.claims.filter((claim) => claim.required).length).toBeGreaterThanOrEqual(3);
+        expect(plan.claims.find((claim) => claim.role === 'application')?.supportingEdgeIds)
+            .toContain('edge_water_heat');
+    });
+    test('does not promote a title-only graph neighbor into a factual claim', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'what is water glass',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+        });
+        expect(plan.claims.some((claim) => claim.supportingAtomIds.includes('container'))).toBe(false);
+        expect(plan.omittedCandidates).toContainEqual(expect.objectContaining({
+            atomId: 'container',
+            reason: 'weak_evidence',
+        }));
+    });
+    test('orders claims by discourse dependency instead of raw confidence', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'explain water glass in detail',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack: {
+                ...ragContextPack,
+                fragments: ragContextPack.fragments.map((fragment) => ({ ...fragment, score: 0.99 })),
+            },
+        });
+        const roles = plan.claims.map((claim) => claim.role);
+        expect(roles.indexOf('boundary')).toBeLessThan(roles.indexOf('mechanism'));
+        expect(roles.indexOf('mechanism')).toBeLessThan(roles.indexOf('application'));
+    });
+    test('omits semantically redundant graph evidence from the public claim plan', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'what is water glass',
+            knowledgePoints: [knowledgePoint],
+            graphContext: {
+                ...graphContext,
+                supportingAtomIds: [...graphContext.supportingAtomIds, 'heat_transfer_duplicate'],
+            },
+            ragContextPack: {
+                ...ragContextPack,
+                fragments: [
+                    ...ragContextPack.fragments,
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'neighbor_heat_transfer_duplicate',
+                        atomId: 'heat_transfer_duplicate',
+                        text: 'Thermal energy passes through the glass wall between the drink and its environment.',
+                        score: 0.86,
+                    },
+                ],
+            },
+        });
+        expect(plan.claims.filter((claim) => claim.role === 'application')).toHaveLength(1);
+        expect(plan.omittedCandidates).toContainEqual({
+            atomId: 'heat_transfer_duplicate',
+            reason: 'redundant',
+        });
+    });
+    test('preserves polarity-opposed claims instead of semantic-deduplicating them', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'explain glass wall heat transfer',
+            knowledgePoints: [{
+                    ...knowledgePoint,
+                    matchedSpans: knowledgePoint.matchedSpans ? [knowledgePoint.matchedSpans[0]] : [],
+                }],
+            graphContext: {
+                ...graphContext,
+                supportingAtomIds: [],
+                supportingTitles: [],
+                knowledgePointRelations: [],
+            },
+            ragContextPack: {
+                ...ragContextPack,
+                fragments: [
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'positive_heat_transfer',
+                        role: 'direct_support',
+                        atomId: 'positive_heat_transfer',
+                        title: 'Heat Transfer',
+                        text: 'The glass wall conducts heat through the liquid boundary.',
+                        relationEdgeIds: [],
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'negative_heat_transfer',
+                        role: 'direct_support',
+                        atomId: 'negative_heat_transfer',
+                        title: 'Heat Transfer',
+                        text: 'The glass wall does not conduct heat through the liquid boundary.',
+                        relationEdgeIds: [],
+                    },
+                ],
+            },
+        });
+        expect(plan.claims.map((claim) => claim.statement)).toEqual(expect.arrayContaining([
+            'The glass wall conducts heat through the liquid boundary.',
+            'The glass wall does not conduct heat through the liquid boundary.',
+        ]));
+    });
+    test('requires distinct high-confidence claims even when they share one semantic role', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'explain water glass in detail',
+            knowledgePoints: [knowledgePoint],
+            graphContext: {
+                ...graphContext,
+                supportingAtomIds: [
+                    ...graphContext.supportingAtomIds,
+                    'heat_conduction',
+                    'thermal_capacity',
+                ],
+            },
+            ragContextPack: {
+                ...ragContextPack,
+                fragments: [
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'neighbor_heat_transfer_conduction',
+                        atomId: 'heat_conduction',
+                        text: 'The glass wall conducts thermal energy from the drink to the surrounding air.',
+                        score: 0.93,
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'neighbor_heat_transfer_capacity',
+                        atomId: 'thermal_capacity',
+                        text: 'The wall heat capacity delays how quickly the drink approaches ambient temperature.',
+                        score: 0.91,
+                    },
+                ],
+            },
+        });
+        const applicationClaims = plan.claims.filter((claim) => claim.role === 'application');
+        expect(applicationClaims).toHaveLength(2);
+        expect(applicationClaims.every((claim) => claim.required)).toBe(true);
+    });
+    test('plans public semantic statements instead of renderer and table payloads', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'explain water glass in detail',
+            knowledgePoints: [{
+                    ...knowledgePoint,
+                    matchedSpans: [
+                        ...(knowledgePoint.matchedSpans || []),
+                        {
+                            atomId: 'thermal_equation_diagram',
+                            title: 'Thermal Equation Diagram',
+                            snippet: 'Heat crosses the glass wall by conduction. ```mermaid\ngraph TD\nA --> B\n```',
+                            sourcePath: 'Knowledge_Base/waterglass/water-glass.md',
+                            score: 0.89,
+                            citation: null,
+                        },
+                        {
+                            atomId: 'parameter_table',
+                            title: 'Parameter Table',
+                            snippet: 'The following table lists typical values. | Parameter | Unit | | :--- | :--- |',
+                            sourcePath: 'Knowledge_Base/waterglass/water-glass.md',
+                            score: 0.88,
+                            citation: null,
+                        },
+                    ],
+                }],
+            graphContext,
+        });
+        expect(plan.claims).toContainEqual(expect.objectContaining({
+            statement: 'Heat crosses the glass wall by conduction.',
+        }));
+        expect(plan.claims.some((claim) => claim.statement.includes('```'))).toBe(false);
+        expect(plan.claims.some((claim) => claim.statement.includes('| Parameter |'))).toBe(false);
+    });
+    test('selects a complete clause from dense mathematical evidence while retaining provenance', () => {
+        const denseEvidence = [
+            'Thermal transfer is governed by q = kA(T1 - T2) / L.',
+            'This document will explain the following table as requested.',
+            'For soda-lime glass the coefficient is usually between',
+        ].join(' ');
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'explain thermal transfer in a water glass',
+            knowledgePoints: [{
+                    ...knowledgePoint,
+                    matchedSpans: [{
+                            atomId: 'thermal_transfer_dense',
+                            title: 'Thermal Transfer',
+                            snippet: denseEvidence,
+                            sourcePath: 'Knowledge_Base/waterglass/thermal-transfer.md',
+                            score: 0.94,
+                            citation: null,
+                        }],
+                }],
+            graphContext,
+        });
+        expect(plan.claims[0].statement).toBe('Thermal transfer is governed by q = kA(T1 - T2) / L.');
+        expect(plan.claims[0].evidenceRefs[0].text).toBe(denseEvidence);
+    });
+    test('retains complete internal claims and preserves their evidence provenance', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'what is water glass',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack: {
+                ...ragContextPack,
+                fragments: [{
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'direct_water_glass_dense_evidence',
+                        role: 'direct_support',
+                        atomId: 'water_glass',
+                        title: 'Water Glass',
+                        text: [
+                            'A water glass is a transparent vessel used to hold water.',
+                            'It separates the liquid from the surrounding environment.',
+                            'Its wall conducts heat between the drink and the air.',
+                            'It is compared with a PET Plastic Cup and a Stainless Steel Metal Cup.',
+                            'The thermal field can be described by $$\\frac{\\partial T}{\\partial t}=\\alpha\\nabla^2 T$$.',
+                            'This clause is intentionally beyond the public definition budget and should remain internal.',
+                        ].join(' '),
+                        score: 0.9,
+                    }],
+            },
+        });
+        const directClaims = plan.claims
+            .filter((claim) => claim.evidenceRefs.some((reference) => reference.evidenceId === 'direct_water_glass_dense_evidence'))
+            .map((claim) => claim.statement);
+        expect(directClaims).toEqual(expect.arrayContaining([
+            'A water glass is a transparent vessel used to hold water.',
+            'It separates the liquid from the surrounding environment.',
+            'Its wall conducts heat between the drink and the air.',
+        ]));
+        expect(directClaims).toContain('It is compared with a PET Plastic Cup and a Stainless Steel Metal Cup.');
+        expect(directClaims).not.toContain('This clause is intentionally beyond the public definition budget and should remain internal.');
+        expect(plan.claims.find((claim) => claim.statement.includes('PET Plastic Cup'))?.evidenceRefs[0].evidenceId)
+            .toBe('direct_water_glass_dense_evidence');
+    });
+    test('retains distinct fact values from semantically similar conflict evidence', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'what is release date conflict probe?',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack: {
+                ...ragContextPack,
+                fragments: [
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'announced_release_date',
+                        role: 'direct_support',
+                        atomId: 'release_date_probe',
+                        title: 'Release Date Conflict Probe',
+                        text: 'The migration release date is 2026-07-01.',
+                        score: 0.92,
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'revised_release_date',
+                        role: 'conflict',
+                        atomId: 'release_date_probe',
+                        title: 'Release Date Conflict Probe',
+                        text: 'The migration release date is 2026-08-15.',
+                        score: 0.92,
+                    },
+                ],
+            },
+        });
+        expect(plan.claims.map((claim) => claim.statement)).toEqual(expect.arrayContaining([
+            'The migration release date is 2026-07-01.',
+            'The migration release date is 2026-08-15.',
+        ]));
+    });
+    test('retains distinct values when equivalent fact subjects use different word order', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'what is release date conflict probe?',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack: {
+                ...ragContextPack,
+                fragments: [
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'announced_release_date_reordered',
+                        role: 'direct_support',
+                        atomId: 'release_date_probe',
+                        title: 'Release Date Conflict Probe',
+                        text: 'The migration release date is 2026-07-01.',
+                        score: 0.92,
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'revised_release_date_reordered',
+                        role: 'conflict',
+                        atomId: 'release_date_probe',
+                        title: 'Release Date Conflict Probe',
+                        text: 'The release date for migration is 2026-08-15.',
+                        score: 0.92,
+                    },
+                ],
+            },
+        });
+        expect(plan.claims.map((claim) => claim.statement)).toEqual(expect.arrayContaining([
+            'The migration release date is 2026-07-01.',
+            'The release date for migration is 2026-08-15.',
+        ]));
+    });
+    test('retains comparison evidence that completes separate requested branches', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'compare cross version one state source with cross version two state source',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack: {
+                ...ragContextPack,
+                fragments: [
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'version_one_state',
+                        role: 'direct_support',
+                        atomId: 'version_one_state',
+                        sourcePath: 'Knowledge_Base/test/cross version one state source.md',
+                        title: 'Cross Version One State Source',
+                        text: 'Cross version one state source records that the migration gate status is enabled in version 1.0.',
+                        score: 0.92,
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'version_two_state',
+                        role: 'direct_support',
+                        atomId: 'version_two_state',
+                        sourcePath: 'Knowledge_Base/test/cross version two state source.md',
+                        title: 'Cross Version Two State Source',
+                        text: 'Cross version two state source records that the migration gate status is disabled in version 2.0.',
+                        score: 0.92,
+                    },
+                ],
+            },
+        });
+        expect(plan.claims.map((claim) => claim.statement)).toEqual(expect.arrayContaining([
+            'Cross version one state source records that the migration gate status is enabled in version 1.0.',
+            'Cross version two state source records that the migration gate status is disabled in version 2.0.',
+        ]));
+    });
+    test('labels comparison claims when otherwise identical evidence is distinguished only by node title', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'compare basalt with granite',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack: {
+                ...ragContextPack,
+                fragments: [
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'basalt_density',
+                        role: 'direct_support',
+                        atomId: 'basalt',
+                        sourcePath: 'Knowledge_Base/test/source-a.md',
+                        title: 'Basalt',
+                        text: 'Its density is high.',
+                        score: 0.92,
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'granite_density',
+                        role: 'direct_support',
+                        atomId: 'granite',
+                        sourcePath: 'Knowledge_Base/test/source-b.md',
+                        title: 'Granite',
+                        text: 'Its density is high.',
+                        score: 0.92,
+                    },
+                ],
+            },
+        });
+        expect(plan.claims.map((claim) => claim.statement)).toEqual(expect.arrayContaining([
+            'Basalt: Its density is high.',
+            'Granite: Its density is high.',
+        ]));
+    });
+    test('retains comparison branches whose only distinct token is a short version number', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'compare iOS 17 with iOS 18',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack: {
+                ...ragContextPack,
+                fragments: [
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'ios_17_status',
+                        role: 'direct_support',
+                        atomId: 'ios_17',
+                        sourcePath: 'Knowledge_Base/test/opaque-a.md',
+                        title: 'iOS 17',
+                        text: 'Its response status is stable.',
+                        score: 0.92,
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'ios_18_status',
+                        role: 'direct_support',
+                        atomId: 'ios_18',
+                        sourcePath: 'Knowledge_Base/test/opaque-b.md',
+                        title: 'iOS 18',
+                        text: 'Its response status is stable.',
+                        score: 0.92,
+                    },
+                ],
+            },
+        });
+        expect(plan.claims.map((claim) => claim.statement)).toEqual(expect.arrayContaining([
+            'iOS 17: Its response status is stable.',
+            'iOS 18: Its response status is stable.',
+        ]));
+    });
+    test('retains both operand claims when one side has only a two-token branch match', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'compare temporal current release source with temporal planned roadmap source',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack: {
+                ...ragContextPack,
+                query: 'compare temporal current release source with temporal planned roadmap source',
+                fragments: [
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'planned_release_date',
+                        role: 'direct_support',
+                        atomId: 'planned_release_date',
+                        sourcePath: 'Knowledge_Base/test/temporal-planned.md',
+                        title: 'Temporal Planned Roadmap Source',
+                        text: 'Temporal planned roadmap source records that the migration release date is 2026-09-20 in the planned rollout draft.',
+                        score: 0.94,
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'current_release_date',
+                        role: 'direct_support',
+                        atomId: 'current_release_date',
+                        sourcePath: 'Knowledge_Base/test/temporal-current.md',
+                        title: 'Temporal Current Release Source',
+                        text: 'Temporal current release source records that the migration release date is 2026-08-15 in the current release record.',
+                        score: 0.93,
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'current_retry_limit',
+                        role: 'direct_support',
+                        atomId: 'current_retry_limit',
+                        sourcePath: 'Knowledge_Base/test/temporal-current-retry.md',
+                        title: 'Temporal Current Retry Limit Source',
+                        text: 'Temporal current retry limit source records that the retry limit is 3 in the current release record.',
+                        score: 0.92,
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'historical_retry_limit',
+                        role: 'direct_support',
+                        atomId: 'historical_retry_limit',
+                        sourcePath: 'Knowledge_Base/test/temporal-history.md',
+                        title: 'Temporal Historical Retry Limit Source',
+                        text: 'Temporal historical retry limit source records that the retry limit is 5 in the historical rollback archive.',
+                        score: 0.9,
+                    },
+                ],
+            },
+        });
+        expect(plan.claims.map((claim) => claim.statement)).toEqual(expect.arrayContaining([
+            'Temporal planned roadmap source records that the migration release date is 2026-09-20 in the planned rollout draft.',
+            'Temporal current release source records that the migration release date is 2026-08-15 in the current release record.',
+        ]));
+        expect(plan.claims.map((claim) => claim.statement)).not.toEqual(expect.arrayContaining([
+            'Temporal current retry limit source records that the retry limit is 3 in the current release record.',
+            'Temporal historical retry limit source records that the retry limit is 5 in the historical rollback archive.',
+        ]));
+    });
+    test('retains comparison branches made only of one-character labels', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'compare A with B',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack: {
+                ...ragContextPack,
+                fragments: [
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'label_a_status',
+                        role: 'direct_support',
+                        atomId: 'label_a',
+                        sourcePath: 'Knowledge_Base/test/opaque-a.md',
+                        title: 'A',
+                        text: 'Its response status is stable.',
+                        score: 0.92,
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'label_b_status',
+                        role: 'direct_support',
+                        atomId: 'label_b',
+                        sourcePath: 'Knowledge_Base/test/opaque-b.md',
+                        title: 'B',
+                        text: 'Its response status is stable.',
+                        score: 0.92,
+                    },
+                ],
+            },
+        });
+        expect(plan.claims.map((claim) => claim.statement)).toEqual(expect.arrayContaining([
+            'A: Its response status is stable.',
+            'B: Its response status is stable.',
+        ]));
+    });
+    test('does not treat unrelated clauses as comparison evidence solely because their fragment title matches a branch', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'compare basalt with granite',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack: {
+                ...ragContextPack,
+                fragments: [
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'basalt_density_with_noise',
+                        role: 'direct_support',
+                        atomId: 'basalt',
+                        sourcePath: 'Knowledge_Base/test/basalt.md',
+                        title: 'Basalt',
+                        text: 'Its density is high. Mars has two moons.',
+                        score: 0.92,
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'granite_density_with_noise',
+                        role: 'direct_support',
+                        atomId: 'granite',
+                        sourcePath: 'Knowledge_Base/test/granite.md',
+                        title: 'Granite',
+                        text: 'Its density is high. Mars has two moons.',
+                        score: 0.92,
+                    },
+                ],
+            },
+        });
+        const statements = plan.claims.map((claim) => claim.statement);
+        expect(statements).toEqual(expect.arrayContaining([
+            'Basalt: Its density is high.',
+            'Granite: Its density is high.',
+        ]));
+        expect(statements).not.toContain('Basalt: Mars has two moons.');
+        expect(statements).not.toContain('Granite: Mars has two moons.');
+    });
+    test('removes structural CJK headings without removing an English subject phrase', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'explain optics in a water glass',
+            knowledgePoints: [{
+                    ...knowledgePoint,
+                    matchedSpans: [{
+                            atomId: 'optics_heading',
+                            title: '3. 光学：光与系统的相互作用',
+                            snippet: '3. 光学：光与系统的相互作用\n当光线穿过空气、玻璃和水时会发生折射。',
+                            sourcePath: 'Knowledge_Base/waterglass/optics.md',
+                            score: 0.94,
+                            citation: null,
+                        }],
+                }],
+            graphContext,
+        });
+        expect(plan.claims[0].statement).toBe('当光线穿过空气、玻璃和水时会发生折射。');
+    });
+    test('does not promote a numeric section marker into a definition claim', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'what is water glass',
+            knowledgePoints: [{
+                    ...knowledgePoint,
+                    matchedSpans: [{
+                            atomId: 'thermal_section',
+                            title: '4. Thermodynamics: Heat Transfer',
+                            snippet: '#### 4. Thermodynamics: Heat Transfer. The temperature field changes through heat conduction.',
+                            sourcePath: 'Knowledge_Base/waterglass/thermal.md',
+                            score: 0.9,
+                            citation: null,
+                        }],
+                }],
+            graphContext,
+        });
+        expect(plan.claims.map((claim) => claim.statement)).not.toContain('4.');
+        expect(plan.claims.map((claim) => claim.statement)).toContain('The temperature field changes through heat conduction.');
+    });
+    test('turns multilingual comparison prose into a required contrast claim', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'compare water glass and plastic cup',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack: {
+                ...ragContextPack,
+                query: 'compare water glass and plastic cup',
+                fragments: [
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'rag_parent_material_comparison',
+                        role: 'parent_context',
+                        atomId: 'water_glass',
+                        title: '相关技术与比较数学模型',
+                        text: [
+                            '光学系统比较模型: 水杯透镜 vs.',
+                            '热损失模型可写为 Q = kAΔT/d。',
+                            '这是一种远比水杯复杂的数学优化。',
+                            '玻璃水杯通常比PET塑料杯更透明。',
+                            '对于相同尺寸的杯子，PET塑料杯的热损失速率大约是玻璃杯的1/5。',
+                        ].join(' '),
+                        score: 0.88,
+                    },
+                ],
+            },
+        });
+        expect(plan.claims.map((claim) => ({
+            role: claim.role,
+            required: claim.required,
+            statement: claim.statement,
+        }))).toContainEqual(expect.objectContaining({
+            role: 'contrast',
+            required: true,
+            statement: '对于相同尺寸的杯子，PET塑料杯的热损失速率大约是玻璃杯的1/5。',
+        }));
+        expect(plan.requiredRoles).toContain('contrast');
+        expect(plan.claims).toContainEqual(expect.objectContaining({
+            role: 'contrast',
+            required: true,
+            statement: '玻璃水杯通常比PET塑料杯更透明。',
+        }));
+        expect(plan.claims.some((claim) => claim.statement.includes('数学优化'))).toBe(false);
+    });
+    test('does not spend compare-claim budget on a clause that covers only one requested branch', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'compare water glass and plastic cup',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack: {
+                ...ragContextPack,
+                query: 'compare water glass and plastic cup',
+                fragments: [{
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'rag_parent_mixed_comparisons',
+                        role: 'parent_context',
+                        atomId: 'water_glass',
+                        title: '相关技术与比较数学模型',
+                        text: [
+                            'PET塑料杯的热损失速率大约是玻璃杯的1/5。',
+                            '消色差透镜使用两种不同色散特性的玻璃组合。',
+                        ].join(' '),
+                        score: 0.88,
+                    }],
+            },
+        });
+        expect(plan.claims).toContainEqual(expect.objectContaining({
+            role: 'contrast',
+            statement: 'PET塑料杯的热损失速率大约是玻璃杯的1/5。',
+        }));
+        expect(plan.claims.some((claim) => claim.statement.includes('消色差透镜'))).toBe(false);
+    });
+    test('drops full-document comparison scaffolding while retaining remote facts for both operands', () => {
+        const plan = (0, graphAnswerPlan_1.buildGraphAnswerPlan)({
+            message: 'compare nominal date full scan source with field date full scan source',
+            knowledgePoints: [knowledgePoint],
+            graphContext,
+            ragContextPack: {
+                ...ragContextPack,
+                query: 'compare nominal date full scan source with field date full scan source',
+                fragments: [
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'nominal_full_document',
+                        role: 'direct_support',
+                        atomId: 'nominal_date',
+                        sourcePath: 'Knowledge_Base/test/nominal-date.md',
+                        title: 'Nominal Date Full Scan Source',
+                        text: 'Nominal date full scan source is the scoped comparison document for full-document release-date augmentation. This opening section is intentionally separate from the remote release-date statement. Local date filler paragraph one keeps the remote appendix away from the matched opening span.',
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'field_full_document',
+                        role: 'direct_support',
+                        atomId: 'field_date',
+                        sourcePath: 'Knowledge_Base/test/field-date.md',
+                        title: 'Field Date Full Scan Source',
+                        text: 'Field date full scan source is the scoped comparison document for full-document release-date augmentation. This opening section is intentionally separate from the remote release-date statement. Local date filler paragraph one keeps the remote appendix away from the matched opening span.',
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'nominal_remote_date',
+                        role: 'direct_support',
+                        atomId: 'nominal_remote_date',
+                        sourcePath: 'Knowledge_Base/test/nominal-date.md',
+                        title: 'Remote Nominal Date Appendix',
+                        text: 'The migration release date is 2026-07-01 in the remote nominal date appendix.',
+                    },
+                    {
+                        ...ragContextPack.fragments[0],
+                        fragmentId: 'field_remote_date',
+                        role: 'direct_support',
+                        atomId: 'field_remote_date',
+                        sourcePath: 'Knowledge_Base/test/field-date.md',
+                        title: 'Remote Field Date Appendix',
+                        text: 'The migration release date is 2026-08-15 in the remote field date appendix.',
+                    },
+                ],
+            },
+        });
+        const statements = plan.claims.map((claim) => claim.statement);
+        expect(statements).toEqual(expect.arrayContaining([
+            'The migration release date is 2026-07-01 in the remote nominal date appendix.',
+            'The migration release date is 2026-08-15 in the remote field date appendix.',
+        ]));
+        expect(statements.join(' ')).not.toContain('filler paragraph');
+        expect(statements.join(' ')).not.toContain('scoped comparison document');
+    });
+});