noteconnection 1.7.0 → 1.9.0

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

@@ -0,0 +1,412 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const vectorAccelerationAdapter_1 = require("./vectorAccelerationAdapter");
+describe('vector acceleration adapter', () => {
+    const originalFetch = globalThis.fetch;
+    const baseSelectionInput = {
+        atomCount: 180,
+        queryTokens: ['retrieval', 'mastery'],
+        queryWeights: new Map([
+            ['retrieval', 1.2],
+            ['mastery', 0.8],
+        ]),
+        topK: 4,
+        tokenToAtomIds: new Map([
+            ['retrieval', Array.from({ length: 60 }, (_v, index) => `atom_${index}`)],
+            ['mastery', Array.from({ length: 40 }, (_v, index) => `atom_${index + 20}`)],
+        ]),
+        signatureBuckets: new Map(),
+        annPrefilterEnabled: true,
+        representationVersion: 'local-vector-representation-v1',
+        embeddingModelId: 'local-semantic-tfidf-v1',
+        embeddingDimension: 512,
+        indexSignature: 'idx_sig_abc123',
+    };
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+        jest.restoreAllMocks();
+    });
+    test('normalizes acceleration adapter provider aliases', () => {
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('local')).toBe('local');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('external_stub')).toBe('external_stub');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('external-stub')).toBe('external_stub');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('stub')).toBe('external_stub');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('external_http')).toBe('external_http');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('external-http')).toBe('external_http');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('http')).toBe('external_http');
+        expect((0, vectorAccelerationAdapter_1.normalizeVectorAccelerationAdapterProvider)('unknown')).toBe('local');
+    });
+    test('returns undefined adapter for local provider', () => {
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('local');
+        expect(adapter).toBeUndefined();
+    });
+    test.each(['syncIndex', 'selectCandidates'])('cancels %s HTTP without retry or circuit failure', async (operation) => {
+        const controller = new AbortController();
+        const cancelled = new Error('turn_cancelled');
+        const fetchMock = jest.fn((_url, init) => new Promise((_resolve, reject) => {
+            const signal = init.signal;
+            signal.addEventListener('abort', () => reject(signal.reason), { once: true });
+            controller.abort(cancelled);
+        }));
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: { endpoint: 'http://127.0.0.1:18080', maxRetries: 3 },
+        });
+        const input = { ...baseSelectionInput, signal: controller.signal };
+        await expect(adapter[operation](input)).rejects.toBe(cancelled);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(JSON.parse(fetchMock.mock.calls[0][1].body)).not.toHaveProperty('signal');
+        expect(adapter.getHealth?.().consecutiveFailures).toBe(0);
+    });
+    test('cancels the connector retry delay before a second request', async () => {
+        const controller = new AbortController();
+        const cancelled = new Error('turn_cancelled');
+        globalThis.fetch = jest.fn().mockRejectedValue(new Error('socket_hang_up'));
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: { endpoint: 'http://127.0.0.1:18080', maxRetries: 3, retryDelayMs: 1000 },
+        });
+        const result = Promise.resolve(adapter.selectCandidates({ ...baseSelectionInput, signal: controller.signal }));
+        setImmediate(() => controller.abort(cancelled));
+        await expect(result).rejects.toBe(cancelled);
+        expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+    });
+    test('external stub adapter selects token-based candidates for large corpus', async () => {
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_stub');
+        expect(adapter).toBeDefined();
+        expect(adapter?.id).toBe('external-stub-vector-acceleration-v1');
+        const selection = await adapter?.selectCandidates(baseSelectionInput);
+        expect(selection?.used).toBe(true);
+        expect(selection?.mode).toBe('token_prefilter');
+        expect((selection?.candidateAtomIds || []).length).toBeGreaterThan(0);
+    });
+    test('external stub adapter returns full scan when prefilter is disabled', async () => {
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_stub');
+        const selection = await adapter?.selectCandidates({
+            ...baseSelectionInput,
+            queryTokens: ['retrieval'],
+            queryWeights: new Map([['retrieval', 1.0]]),
+            tokenToAtomIds: new Map([['retrieval', ['atom_a', 'atom_b']]]),
+            annPrefilterEnabled: false,
+        });
+        expect(selection?.used).toBe(false);
+        expect(selection?.mode).toBe('full_scan');
+        expect(selection?.candidateAtomIds).toEqual([]);
+    });
+    test('external http adapter throws endpoint-missing error when endpoint is not configured', async () => {
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http');
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('external_http_endpoint_missing');
+        expect(adapter?.getHealth?.().status).toBe('unavailable');
+        expect(String(adapter?.getHealth?.().message || '')).toContain('external_http_endpoint_missing');
+        expect(Number(adapter?.getHealth?.().failureCount || 0)).toBeGreaterThanOrEqual(1);
+        expect(adapter?.getHealth?.().representationVersion).toBe('local-vector-representation-v1');
+        expect(adapter?.getHealth?.().embeddingModelId).toBe('local-semantic-tfidf-v1');
+        expect(adapter?.getHealth?.().representationStatus).toBe('unknown');
+    });
+    test('external http adapter forwards selection request and normalizes connector response', async () => {
+        const fetchMock = jest.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: async () => ({
+                used: true,
+                mode: 'token_prefilter',
+                candidateAtomIds: ['atom_10', 'atom_21'],
+                representationVersion: 'local-vector-representation-v1',
+                embeddingModelId: 'local-semantic-tfidf-v1',
+                embeddingDimension: 512,
+                indexSignature: 'idx_sig_abc123',
+                representationStatus: 'aligned',
+            }),
+        });
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+                timeoutMs: 450,
+            },
+        });
+        const selection = await adapter?.selectCandidates(baseSelectionInput);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(String(fetchMock.mock.calls[0]?.[0] || '')).toContain('/select-candidates');
+        const requestOptions = fetchMock.mock.calls[0]?.[1];
+        const requestHeaders = requestOptions?.headers || {};
+        const requestBody = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body || '{}'));
+        expect(String(requestHeaders['x-request-id'] || '')).toContain('nc-vector-accel-');
+        expect(String(requestHeaders['x-correlation-id'] || '')).toBe(String(requestHeaders['x-request-id'] || ''));
+        expect(String(requestBody.representationVersion || '')).toBe('local-vector-representation-v1');
+        expect(String(requestBody.embeddingModelId || '')).toBe('local-semantic-tfidf-v1');
+        expect(Number(requestBody.embeddingDimension || 0)).toBe(512);
+        expect(String(requestBody.indexSignature || '')).toBe('idx_sig_abc123');
+        expect(selection?.used).toBe(true);
+        expect(selection?.mode).toBe('token_prefilter');
+        expect(selection?.candidateAtomIds).toEqual(['atom_10', 'atom_21']);
+        expect(selection?.representation?.validated).toBe(true);
+        expect(selection?.prefilterMetrics?.candidatesReturned).toBe(2);
+        expect(Number(selection?.prefilterMetrics?.totalAtomsInScope || 0)).toBeGreaterThan(0);
+        expect(adapter?.getHealth?.().status).toBe('ready');
+        expect(String(adapter?.getHealth?.().lastRequestId || '')).toContain('nc-vector-accel-');
+        expect(adapter?.getHealth?.().representationStatus).toBe('aligned');
+        expect(adapter?.getHealth?.().representationVersion).toBe('local-vector-representation-v1');
+        expect(adapter?.getHealth?.().embeddingModelId).toBe('local-semantic-tfidf-v1');
+        expect(Number(adapter?.getHealth?.().embeddingDimension || 0)).toBe(512);
+    });
+    test('external http adapter syncs remote index and caches matching signatures', async () => {
+        const fetchMock = jest.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            headers: {
+                get: (name) => {
+                    if (String(name || '').toLowerCase() === 'x-request-id') {
+                        return 'connector-sync-success';
+                    }
+                    return '';
+                },
+            },
+            json: async () => ({
+                synced: true,
+                atomCount: 180,
+                indexSignature: 'idx_sig_abc123',
+                representationVersion: 'local-vector-representation-v1',
+                embeddingModelId: 'local-semantic-tfidf-v1',
+                embeddingDimension: 512,
+                representationStatus: 'aligned',
+            }),
+        });
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+            },
+        });
+        const syncResult = await adapter?.syncIndex?.(baseSelectionInput);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(String(fetchMock.mock.calls[0]?.[0] || '')).toContain('/sync-index');
+        const requestBody = JSON.parse(String(fetchMock.mock.calls[0]?.[1]?.body || '{}'));
+        expect(Number(requestBody.atomCount || 0)).toBe(180);
+        expect(String(requestBody.indexSignature || '')).toBe('idx_sig_abc123');
+        expect(Array.isArray(requestBody.tokenToAtomIds)).toBe(true);
+        expect(Array.isArray(requestBody.signatureBuckets)).toBe(true);
+        expect(syncResult?.synced).toBe(true);
+        expect(syncResult?.indexSignature).toBe('idx_sig_abc123');
+        const healthAfterSync = adapter?.getHealth?.();
+        expect(healthAfterSync?.status).toBe('ready');
+        expect(healthAfterSync?.indexSyncStatus).toBe('ready');
+        expect(healthAfterSync?.syncRequestCount).toBe(1);
+        expect(healthAfterSync?.syncSuccessCount).toBe(1);
+        expect(healthAfterSync?.syncFailureCount).toBe(0);
+        expect(healthAfterSync?.syncedIndexSignature).toBe('idx_sig_abc123');
+        expect(healthAfterSync?.syncedAtomCount).toBe(180);
+        const cachedSyncResult = await adapter?.syncIndex?.(baseSelectionInput);
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(cachedSyncResult?.synced).toBe(true);
+        expect(adapter?.getHealth?.().indexSyncStatus).toBe('ready');
+    });
+    test('external http adapter filters out-of-scope candidate ids and keeps only valid ids', async () => {
+        const fetchMock = jest.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: async () => ({
+                used: true,
+                mode: 'token_prefilter',
+                candidateAtomIds: ['atom_999', 'atom_10', 'atom_10'],
+            }),
+        });
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+            },
+        });
+        const selection = await adapter?.selectCandidates(baseSelectionInput);
+        expect(selection?.used).toBe(true);
+        expect(selection?.candidateAtomIds).toEqual(['atom_10']);
+        expect(selection?.prefilterMetrics?.candidatesReturned).toBe(1);
+        expect(selection?.prefilterMetrics?.prefilterRatio).toBeGreaterThan(0);
+        expect(String(adapter?.getHealth?.().representationStatusReason || '')).toContain('candidate_ids_out_of_scope');
+    });
+    test('external http adapter infers representation mismatch when connector metadata drifts', async () => {
+        const fetchMock = jest.fn().mockResolvedValue({
+            ok: true,
+            status: 200,
+            json: async () => ({
+                used: true,
+                mode: 'token_prefilter',
+                candidateAtomIds: ['atom_10'],
+                representationVersion: 'remote-vector-representation-v2',
+                embeddingModelId: 'local-semantic-tfidf-v1',
+                embeddingDimension: 512,
+                indexSignature: 'idx_sig_abc123',
+            }),
+        });
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+            },
+        });
+        const selection = await adapter?.selectCandidates(baseSelectionInput);
+        expect(selection?.used).toBe(true);
+        expect(adapter?.getHealth?.().representationStatus).toBe('mismatch');
+        expect(String(adapter?.getHealth?.().representationStatusReason || '')).toContain('representation_version');
+    });
+    test('external http adapter retries transient status failures and recovers', async () => {
+        const fetchMock = jest
+            .fn()
+            .mockResolvedValueOnce({
+            ok: false,
+            status: 503,
+            headers: {
+                get: (name) => {
+                    const normalized = String(name || '').toLowerCase();
+                    if (normalized === 'retry-after') {
+                        return '0.03';
+                    }
+                    if (normalized === 'x-request-id') {
+                        return 'connector-retry-503';
+                    }
+                    return '';
+                },
+            },
+            json: async () => ({}),
+        })
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            headers: {
+                get: (name) => {
+                    if (String(name || '').toLowerCase() === 'x-request-id') {
+                        return 'connector-retry-success';
+                    }
+                    return '';
+                },
+            },
+            json: async () => ({
+                used: true,
+                mode: 'token_prefilter',
+                candidateAtomIds: ['atom_22'],
+            }),
+        });
+        globalThis.fetch = fetchMock;
+        const originalSetTimeout = global.setTimeout;
+        const recordedTimeoutDelays = [];
+        const setTimeoutSpy = jest.spyOn(global, 'setTimeout').mockImplementation(((handler, timeout, ...args) => {
+            recordedTimeoutDelays.push(Math.floor(Number(timeout || 0)));
+            return originalSetTimeout(handler, timeout, ...args);
+        }));
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+                maxRetries: 2,
+                retryDelayMs: 0,
+            },
+        });
+        const selection = await adapter?.selectCandidates(baseSelectionInput);
+        setTimeoutSpy.mockRestore();
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(selection?.used).toBe(true);
+        expect(selection?.candidateAtomIds).toEqual(['atom_22']);
+        expect(adapter?.getHealth?.().status).toBe('ready');
+        expect(recordedTimeoutDelays.some((delay) => delay >= 30)).toBe(true);
+        expect(String(adapter?.getHealth?.().lastRequestId || '')).toBe('connector-retry-success');
+        expect(String(adapter?.getHealth?.().lastErrorCode || '')).toBe('');
+        expect(Number(adapter?.getHealth?.().lastRetryAfterMs || 0)).toBe(30);
+    });
+    test('external http adapter does not retry non-transient status failures', async () => {
+        const fetchMock = jest.fn().mockResolvedValue({
+            ok: false,
+            status: 400,
+            json: async () => ({}),
+        });
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+                maxRetries: 3,
+                retryDelayMs: 0,
+            },
+        });
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('external_http_status_400');
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        expect(adapter?.getHealth?.().status).toBe('unavailable');
+    });
+    test('external http adapter retries transient network failures up to max retries', async () => {
+        const fetchMock = jest.fn().mockRejectedValue(new Error('socket_hang_up'));
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+                maxRetries: 2,
+                retryDelayMs: 0,
+            },
+        });
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('socket_hang_up');
+        expect(fetchMock).toHaveBeenCalledTimes(3);
+        expect(adapter?.getHealth?.().status).toBe('degraded');
+    });
+    test('external http adapter propagates connector failures and marks degraded health', async () => {
+        const fetchMock = jest.fn().mockRejectedValue(new Error('socket_hang_up'));
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+            },
+        });
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('socket_hang_up');
+        expect(adapter?.getHealth?.().status).toBe('degraded');
+        expect(String(adapter?.getHealth?.().message || '')).toContain('socket_hang_up');
+    });
+    test('external http adapter opens circuit after consecutive failures and short-circuits requests', async () => {
+        const fetchMock = jest.fn().mockRejectedValue(new Error('socket_hang_up'));
+        globalThis.fetch = fetchMock;
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+                maxRetries: 0,
+                retryDelayMs: 0,
+                circuitFailureThreshold: 2,
+                circuitCooldownMs: 10000,
+            },
+        });
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('socket_hang_up');
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('socket_hang_up');
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('external_http_circuit_open');
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(adapter?.getHealth?.().status).toBe('unavailable');
+        expect(String(adapter?.getHealth?.().message || '')).toContain('external_http_circuit_open');
+    });
+    test('external http adapter enters half-open after cooldown and closes on successful probe', async () => {
+        const fetchMock = jest
+            .fn()
+            .mockRejectedValueOnce(new Error('socket_hang_up'))
+            .mockResolvedValueOnce({
+            ok: true,
+            status: 200,
+            json: async () => ({
+                used: true,
+                mode: 'token_prefilter',
+                candidateAtomIds: ['atom_23'],
+            }),
+        });
+        globalThis.fetch = fetchMock;
+        let nowMs = 1000;
+        jest.spyOn(Date, 'now').mockImplementation(() => nowMs);
+        const adapter = (0, vectorAccelerationAdapter_1.createVectorAccelerationAdapter)('external_http', {
+            externalHttp: {
+                endpoint: 'http://127.0.0.1:18080',
+                maxRetries: 0,
+                retryDelayMs: 0,
+                circuitFailureThreshold: 1,
+                circuitCooldownMs: 500,
+            },
+        });
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('socket_hang_up');
+        await expect(adapter?.selectCandidates(baseSelectionInput)).rejects.toThrow('external_http_circuit_open');
+        expect(fetchMock).toHaveBeenCalledTimes(1);
+        nowMs += 600;
+        const recovered = await adapter?.selectCandidates(baseSelectionInput);
+        expect(fetchMock).toHaveBeenCalledTimes(2);
+        expect(recovered?.used).toBe(true);
+        expect(recovered?.candidateAtomIds).toEqual(['atom_23']);
+        expect(adapter?.getHealth?.().status).toBe('ready');
+        expect(String(adapter?.getHealth?.().message || '')).toContain('circuit=closed');
+    });
+});

package/dist/src/learning/workspaceHydration.js

@@ -0,0 +1,168 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deriveKnowledgeTargetLookupQueries = deriveKnowledgeTargetLookupQueries;
+exports.normalizeKnowledgeSourcePath = normalizeKnowledgeSourcePath;
+exports.buildKnowledgeSourceInventoryDiff = buildKnowledgeSourceInventoryDiff;
+exports.markdownPreviewMatchesTitleLikeQueries = markdownPreviewMatchesTitleLikeQueries;
+const path = __importStar(require("path"));
+function normalizeLookupQuery(value) {
+    return String(value || '')
+        .normalize('NFKC')
+        .replace(/[?？!！。.;；:,，]+/gu, ' ')
+        .replace(/\s+/gu, ' ')
+        .trim()
+        .toLowerCase();
+}
+function stripDefinitionPredicate(value) {
+    return value
+        .replace(/^(?:what\s+is|what\s+are|define|explain|tell\s+me\s+about|what's)\s+/iu, '')
+        .replace(/^(?:什么是|何谓|解释(?:一下)?|介绍(?:一下)?|请(?:解释|介绍)(?:一下)?)\s*/u, '')
+        .trim();
+}
+/**
+ * Extracts bounded title-like variants from a user query. Compound prompts keep
+ * their first definition clause so a Chinese subject can resolve an English
+ * filename without scanning the whole corpus.
+ */
+function deriveKnowledgeTargetLookupQueries(query) {
+    const source = String(query || '').normalize('NFKC');
+    const candidates = new Set();
+    const add = (value) => {
+        const normalized = normalizeLookupQuery(value);
+        if (!normalized) {
+            return;
+        }
+        candidates.add(normalized);
+        const stripped = stripDefinitionPredicate(normalized);
+        if (stripped) {
+            candidates.add(stripped);
+            candidates.add(stripped.replace(/\s+/gu, ''));
+        }
+    };
+    add(source);
+    source.split(/[?？!！。.;；\n\r]+/gu).forEach(add);
+    const definitionSubject = source.match(/^(?:what\s+is|what\s+are|define|explain|tell\s+me\s+about|what's|什么是|何谓|解释(?:一下)?|介绍(?:一下)?|请(?:解释|介绍)(?:一下)?)\s*([^?？!！。.;；\n\r]+)/iu);
+    if (definitionSubject?.[1]) {
+        const subject = definitionSubject[1]
+            .replace(/\s+(?:我应该|应该|how\s+should|what\s+should).*$/iu, '')
+            .trim();
+        add(subject);
+    }
+    if (candidates.has('water glass') || candidates.has('waterglass')) {
+        candidates.add('water glass');
+        candidates.add('waterglass');
+        candidates.add('水玻璃');
+        candidates.add('水杯');
+    }
+    return Array.from(candidates.values()).filter(Boolean);
+}
+/**
+ * Produces the case-folded path key used only for inventory reconciliation.
+ * The original spelling is retained in diff output for diagnostics and ingest.
+ */
+function normalizeKnowledgeSourcePath(value) {
+    return String(value || '')
+        .normalize('NFKC')
+        .replace(/\\/g, '/')
+        .replace(/^\/+/, '')
+        .replace(/\/{2,}/g, '/')
+        .replace(/\/+$/g, '')
+        .toLowerCase();
+}
+function buildKnowledgeSourceInventoryDiff(params) {
+    const collect = (sourcePaths) => {
+        const byNormalizedPath = new Map();
+        sourcePaths.forEach((sourcePath) => {
+            const normalized = normalizeKnowledgeSourcePath(sourcePath);
+            if (normalized && !byNormalizedPath.has(normalized)) {
+                byNormalizedPath.set(normalized, sourcePath);
+            }
+        });
+        return byNormalizedPath;
+    };
+    const disk = collect(params.diskSourcePaths);
+    const indexed = collect(params.indexedSourcePaths);
+    const addedSourcePaths = Array.from(disk.entries())
+        .filter(([normalizedPath]) => !indexed.has(normalizedPath))
+        .map(([, sourcePath]) => sourcePath)
+        .sort((left, right) => normalizeKnowledgeSourcePath(left).localeCompare(normalizeKnowledgeSourcePath(right)));
+    const removedSourcePaths = Array.from(indexed.entries())
+        .filter(([normalizedPath]) => !disk.has(normalizedPath))
+        .map(([, sourcePath]) => sourcePath)
+        .sort((left, right) => normalizeKnowledgeSourcePath(left).localeCompare(normalizeKnowledgeSourcePath(right)));
+    return { addedSourcePaths, removedSourcePaths };
+}
+function normalizeTitleCandidate(value) {
+    return String(value || '')
+        .normalize('NFKC')
+        .replace(/[^\p{L}\p{N}\s_-]+/gu, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase()
+        .replace(/^(?:the|a|an)\s+/u, '')
+        .trim();
+}
+function collectPreviewTitleCandidates(sourcePath, preview) {
+    const candidates = new Set();
+    const basename = path.posix.basename(String(sourcePath || '').replace(/\\/g, '/'))
+        .replace(/\.[^.]+$/u, '');
+    if (basename) {
+        candidates.add(basename);
+    }
+    String(preview || '').split(/\r?\n/u).forEach((line) => {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            return;
+        }
+        const heading = trimmed.match(/^#{1,6}\s+(.+?)\s*#*$/u);
+        if (heading?.[1]) {
+            candidates.add(heading[1]);
+            return;
+        }
+        if (candidates.size <= 1 && !/^```|^[-*+]\s|^\d+[.)]\s/u.test(trimmed)) {
+            candidates.add(trimmed);
+        }
+    });
+    return Array.from(candidates.values()).map(normalizeTitleCandidate).filter(Boolean);
+}
+function markdownPreviewMatchesTitleLikeQueries(input) {
+    const queries = Array.from(new Set(input.titleLikeQueries.map(normalizeTitleCandidate).filter((query) => query.length >= 2)));
+    if (queries.length <= 0) {
+        return false;
+    }
+    const candidates = collectPreviewTitleCandidates(input.sourcePath, input.preview);
+    return candidates.some((candidate) => queries.some((query) => candidate === query || candidate.includes(query)));
+}

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

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const workspaceHydration_1 = require("./workspaceHydration");
+describe('workspaceHydration', () => {
+    test('detects source files that exist on disk but are absent from the indexed workspace', () => {
+        const diff = (0, workspaceHydration_1.buildKnowledgeSourceInventoryDiff)({
+            diskSourcePaths: [
+                'Knowledge_Base/waterglass/water glass.md',
+                'Knowledge_Base/waterglass/Amorphous ice.md',
+            ],
+            indexedSourcePaths: [
+                'knowledge_base\\waterglass\\water glass.md',
+            ],
+        });
+        expect(diff.addedSourcePaths).toEqual([
+            'Knowledge_Base/waterglass/Amorphous ice.md',
+        ]);
+        expect(diff.removedSourcePaths).toEqual([]);
+    });
+    test('matches a Chinese heading when the file basename uses the English concept name', () => {
+        expect((0, workspaceHydration_1.markdownPreviewMatchesTitleLikeQueries)({
+            sourcePath: 'Knowledge_Base/waterglass/Amorphous ice.md',
+            preview: '## 非晶冰\n\n非晶冰（Amorphous ice）是水的一种固态形式。',
+            titleLikeQueries: ['非晶冰'],
+        })).toBe(true);
+    });
+    test('keeps the definition subject from a compound Chinese conversation query', () => {
+        expect((0, workspaceHydration_1.deriveKnowledgeTargetLookupQueries)('什么是非晶冰？我应该通过哪些知识点学习？')).toEqual(expect.arrayContaining(['非晶冰']));
+    });
+});